Prosody RTP processing: API: sm_vmprx_status

Prototype Definition

int sm_vmprx_status(struct sm_vmprx_status_parms *statusp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_status_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kSMVMPrxStatus {
		kSMVMPrxStatusRunning,
		kSMVMPrxStatusStopped,
		kSMVMPrxStatusDetectTone,
		kSMVMPrxStatusEndTone,
		kSMVMPrxStatusGotPorts,
		kSMVMPrxStatusNewSSRC,
		kSMVMPrxStatusUnhandledPayload,
		kSMVMPrxStatusCodecSpecific,
		kSMVMPrxStatusGotPortsIPv6,
		kSMVMPrxStatusNewSSRCIPv6,
		kSMVMPrxStatusSTUNBindRequest,
		kSMVMPrxStatusSTUNBindResponse,
		kSMVMPrxStatusJBResync,
		kSMVMPrxStatusProfileSpecific,
	} status;						/* out */
	union {
		struct {
			tSM_INT id;				/* out */
			double volume;				/* out */
			unsigned duration;			/* out */
		} tone;						/* out */
		struct {
			int RTP_Port;				/* out */
			int RTCP_Port;				/* out */
			struct in_addr address;			/* out */
		} ports;					/* out */
		struct {
			tSM_INT no_data;			/* out */
		} run;						/* out */
		struct {
			struct in_addr address;			/* out */
			int port;				/* out */
			int ssrc;				/* out */
		} ssrc;						/* out */
		struct {
			int type;				/* out */
		} payload;					/* out */
		struct {
			int payload_type;			/* out */
		} codec_specific;				/* out */
		struct {
			int RTP_Port;				/* out */
			int RTCP_Port;				/* out */
			struct in6_addr address;		/* out */
		} ports_ipv6;					/* out */
		struct {
			struct in6_addr address;		/* out */
			int port;				/* out */
			int ssrc;				/* out */
		} ssrc_ipv6;					/* out */
		struct {
			int recv_port;				/* out */
			enum kSMAddressType {
				kSMAddressTypeIPv4,
				kSMAddressTypeIPv6,
			} address_type;				/* out */
			union {
				struct in_addr ipv4;		/* out */
				struct in6_addr ipv6;		/* out */
			} address;				/* out */
			int port;				/* out */
			tSM_UT32 priority;			/* out */
			int use_candidate;			/* out */
			int remote_is_controlling;		/* out */
		} bind_request;					/* out */
		struct {
			int recv_port;				/* out */
			char transaction_id[12];		/* out */
			enum kSMVMPrxSTUNResult {
				kSMVMPrxSTUNResultSuccess,
				kSMVMPrxSTUNResultError,
				kSMVMPrxSTUNResultInvalid,
				kSMVMPrxSTUNResultTimeout,
			} result;				/* out */
			tSM_INT error_code;			/* out */
			enum kSMAddressType address_type;	/* out */
			union {
				struct in_addr ipv4;		/* out */
				struct in6_addr ipv6;		/* out */
			} address;				/* out */
			int port;				/* out */
			int local_was_controlling;		/* out */
		} bind_response;				/* out */
		struct {
			tSM_UT32 timestamp;			/* out */
			tSM_UT64 localtimeref;			/* out */
		} jbresync;					/* out */
		struct {
			tSM_INT notification_code;		/* out */
		} profile_specific;				/* out */
	} u;							/* out */
} SM_VMPRX_STATUS_PARMS;

Description

Returns the current status of the VMP[rx] or an error to indicate that an error has occurred.

When the VMP[rx] event, obtained from sm_vmprx_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the VMP[rx].

Fields

vmprx

The VMP[rx] to interrogate

status

One of these values:

kSMVMPrxStatusRunning: The VMP[rx] is running normally.
kSMVMPrxStatusStopped: Indicates that the VMP[rx] has stopped processing RTP and that it is safe to destroy
kSMVMPrxStatusDetectTone: Indicates that a tone has been received by the vmprx
kSMVMPrxStatusEndTone: Indicates that the tone being received by the vmprx has ended
kSMVMPrxStatusGotPorts: Indicates that IPv4 port information is available. In addition to being reported with this status, this information can be retrieved with sm_vmprx_get_ports() at any time until the VMP[x] is stopped.
kSMVMPrxStatusNewSSRC: Indicates that a new SSRC value from an IPv4 endpoint is being used.
kSMVMPrxStatusUnhandledPayload: Indicates that a packet was received with a payload type that could not be handled
kSMVMPrxStatusCodecSpecific: Indicates that codec specific status information is available
kSMVMPrxStatusGotPortsIPv6: Indicates that IPv6 port information is available. In addition to being reported with this status, this information can be retrieved with sm_vmprx_get_ports() at any time until the VMP[x] is stopped.
kSMVMPrxStatusNewSSRCIPv6: Indicates that a new SSRC value from and IPv6 endpoint is being used.
kSMVMPrxStatusSTUNBindRequest: Indicates that a STUN bind request has been received.
kSMVMPrxStatusSTUNBindResponse: Indicates that a STUN bind response has been received.
kSMVMPrxStatusJBResync: Indicates that a jitter buffer resync has occurred.
kSMVMPrxStatusProfileSpecific: Indicates that profile specific plugin has detected a a state transition. This information should be be retrieved with sm_vmprx_status_profile_specific() .

u

Additional information relating to the current status of the VMP[rx]

tone

This field is only valid if the status is kSMVMPrxStatusDetectTone or kSMVMPrxStatusEndTone.

id: The RFC2833 identifier for the recognised tone
volume: The volume of the tone expressed in dBm0
duration: The duration of the tone.

ports

This field is only valid if the status is kSMVMPrxStatusGotPorts.

RTP_Port: The UDP port number on which this VMP[rx] is listening for RTP
RTCP_Port: The UDP port number on which this VMP[rx] is listening for RTCP
address: The address on which this VMP[rx] is listening.

run

This field is only valid if the status is kSMVMPrxStatusRunning.

no_data: Non zero when the VMP[rx] is experiencing a loss of data that has reached the threshold set by sm_vmprx_config_dataloss()

ssrc

This field is only valid if the status is kSMVMPrxStatusNewSSRC.

address: The address from which the SSRC was received.
port: The UDP port number from which the SSRC was received.
ssrc: The new SSRC value.

payload

This field is only valid if the status is kSMVMPrxStatusUnhandledPayload.

type: The payload type identifier from the RTP packet

codec_specific

This field is only valid if the status is kSMVMPrxStatusCodecSpecific

payload_type: The payload type identifier for the codec

ports_ipv6

This field is only valid if the status is kSMVMPrxStatusGotPortsIPv6.

RTP_Port: The UDP port number on which this VMP[rx] is listening for RTP
RTCP_Port: The UDP port number on which this VMP[rx] is listening for RTCP
address: The address on which this VMP[rx] is listening.

ssrc_ipv6

This field is only valid if the status is kSMVMPrxStatusNewSSRCIPv6.

address: The address from which the SSRC was received.
port: The UDP port number from which the SSRC was received.
ssrc: The new SSRC value.

bind_request

This field is only valid if the status is kSMVMPrxStatusSTUNBindRequest

recv_port

The port the STUN bind request was received on.

address_type

The type of the request's source address. One of these values:

kSMAddressTypeIPv4: An IPv4 address is present.
kSMAddressTypeIPv6: An IPv6 address is present.

address

ipv4: The IPv4 address from which the STUN bind request was received from. Only valid when type is kSMAddressTypeIPv4.
ipv6: The IPv6 address from which the STUN bind request was received from. Only valid when type is kSMAddressTypeIPv6.

port

The port from which the STUN bind request was received from.

priority

The priority value from the STUN bind request.

use_candidate

An indication of whether the STUN bind request included a USE-CANDIDATE attribute. Non-zero when the attribute is present.

remote_is_controlling

An indication of ICE role from the STUN bind request. It is zero if the remote agent is in the controlled role and non-zero otherwise.

bind_response

This field is only valid if the status is kSMVMPrxStatusSTUNBindResult

recv_port

The port the STUN bind result was received on.

transaction_id

The transaction ID used for the request.

result

The result type. One of these values:

kSMVMPrxSTUNResultSuccess: A valid success response was received.
kSMVMPrxSTUNResultError: A valid error response was received.
kSMVMPrxSTUNResultInvalid: A invalid response was received.
kSMVMPrxSTUNResultTimeout: No response was received.

error_code

The value of the first ERROR-CODE attribute, or zero if no such attribute is present.

address_type

The type of the reflexive address in the response. One of these values:

kSMAddressTypeIPv4: An IPv4 address is present.
kSMAddressTypeIPv6: An IPv6 address is present.

address

ipv4: The reflexive IPv4 address. Only valid when address_type is kSMAddressTypeIPv4.
ipv6: The reflexive IPv6 address. Only valid when address_type is kSMAddressTypeIPv6.

port

The reflexive port.

local_was_controlling

An indication of local ICE role when the STUN bind request was sent. It is zero if the local agent was in the controlled role and non-zero otherwise.

jbresync

This field is only valid if the status is kSMVMPrxStatusJBResync

timestamp: The timestamp to which the VMP[rx] resynchronised.
localtimeref: A local time reference in uints of microseconds (to aid in calculating stream synchronisation delays).

profile_specific

This field is only valid if the status is kSMVMPrxStatusProfileSpecific

notification_code: A profile specific notification code.

Returns

0 if call completed successfully, otherwise a standard error such as:

ERR_SM_DEVERR - device error
ERR_SM_NO_RESOURCES - if insufficient resources existed to create the VMP[rx]

This function is part of the Prosody RTP processing API.