Prosody RTP processing: API

a structure of the following type:

typedef struct sm_rtcphand_config_bandwidth_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSM_INT rtcp_bw;					/* in */
	tSM_INT rtcprx_bw;					/* in */
	tSM_INT rtcptx_bw;					/* in */
} SM_RTCPHAND_CONFIG_BANDWIDTH_PARMS;

Description

Configures the RTCP bandwidth.

Fields

rtcphand: The RTCP handler to configure
rtcp_bw: The bandwidth, in bits per second, allocated for use by RTCP in the session in which this RTCP handler is participating. This is the value rtcp_bw specified in IETF RFC 3550.
rtcprx_bw: The bandwith, in bits per second, allocated for use by RTCP reports from RTP receivers. This is the value specified by "b=RR:<bandwith-value>" in SDP (IETF RFC 3556).
rtcptx_bw: The bandwith, in bits per second, allocated for use by RTCP reports from RTP senders. This is the value specified by "b=RT:<bandwith-value>" in SDP (IETF RFC 3556).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_config_options

Prototype Definition

int sm_rtcphand_config_options(struct sm_rtcphand_config_options_parms *rvp)

Parameters

a structure of the following type:

typedef struct sm_rtcphand_config_options_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSM_INT rtcptx_suppress_xr;				/* in */
} SM_RTCPHAND_CONFIG_OPTIONS_PARMS;

Description

Configures options releated to the RTCP protocol. Currently the only option is one to alter the default behaviour of including XR elements in RTCP packets generated by Prosody-S/Prosody-X.

Fields

rtcphand: The RTCP handler to configure
rtcptx_suppress_xr: Non-zero value will supress the inclusion of XR elements in transmitted RTCP packets.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_config_reports

Prototype Definition

int sm_rtcphand_config_reports(struct sm_rtcphand_config_reports_parms *rvp)

Parameters

a structure of the following type:

typedef struct sm_rtcphand_config_reports_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSM_INT reports;					/* in */
} SM_RTCPHAND_CONFIG_REPORTS_PARMS;

Description

Configures the reports to be locally generated by RTCP. The reports are collected using sm_rtcphand_get_data().

Fields

rtcphand: The RTCP handler to configure
reports: The reports desired. This is a bitmask of the desired reports, with bit N indicating that report type N is to be generated. Summary reports should not be included in the bit mask as these are solicited explicitly. The type numbers are the same as for sm_rtcphand_get_data().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_config_sdes

Prototype Definition

int sm_rtcphand_config_sdes(struct sm_rtcphand_config_sdes_parms *rvp)

Parameters

a structure of the following type:

typedef struct sm_rtcphand_config_sdes_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSM_INT itemnum;					/* in */
	tSM_INT stringlen;					/* in */
	char *stringval;					/* in */
} SM_RTCPHAND_CONFIG_SDES_PARMS;

Description

Configures one string to be used by RTCP. The strings are used to specify the source description (SDES) items. Since Canonical End-Point Identifier SDES Item (CNAME) is mandatory in RTCP packets, it should be configured before the RTCP handler needs to transmit RTCP packets.

When a string which has already been configured is configured again, the new value replaces the old one.

Fields

rtcphand: The RTCP handler to configure
itemnum: Which SDES item to configure. This is the SDES type (for example, as defined in section 12.2 of IETF RFC 3550).
stringlen: The length of the string in octets.
stringval: The string contents.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_create

Prototype Definition

int sm_rtcphand_create(struct sm_rtcphand_create_parms *rtcphandp)

Parameters

*rtcphandp

a structure of the following type:

typedef struct sm_rtcphand_create_parms {
	tSMRTCPHandId rtcphand;					/* out */
	tSMModuleId module;					/* in */
} SM_RTCPHAND_CREATE_PARMS;

Description

Creates a RTCP handler. Note that you must configure the CNAME with sm_rtcphand_config_sdes() before the RTCP handler can generate RTCP packets.

This requires the module rtcp to have been downloaded.

Fields

rtcphand: The newly created RTCP handler identifier
module: A value obtained from sm_open_module() which indicates the module where the VMP[tx] is to be allocated.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_destroy

Prototype Definition

int sm_rtcphand_destroy(tSMRTCPHandId rtcphand)

Parameters

rtcphand: A tSMRTCPHandId that has been prevously created by a call to sm_rtcphand_create().

Description

Destroys rtcphand and invalidates the tSMRTCPHandId.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_get_data

Prototype Definition

int sm_rtcphand_get_data(struct sm_rtcphand_get_data_parms *datap)

Parameters

*datap

a structure of the following type:

typedef struct sm_rtcphand_get_data_parms {
	tSMRTCPHandId rtcphand;					/* in */
	char *data;						/* in */
	tSM_INT max_length;					/* in */
	tSM_INT done_length;					/* out */
} SM_RTCPHAND_GET_DATA_PARMS;

Description

Attempt to read data from an RTCP handler. If the event obtained from sm_rtcphand_get_event() is currently signalled, then this function will not block, but instead read less than max_length of data when either:

there is a status change which must be checked
there is no more data to read

To permit maximum system throughput, this function refuses to read from a RTCP handler whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status when a call to sm_rtcphand_get_data() returns with done_length equal to zero.

If an error is reported, the done_length field indicates the amount of data which was read before the error occurred.

The data is a stream which contains records. Note that this means that a single call to sm_rtcphand_get_data(). does not always return exactly one record - it may return data from part of a record or from multiple consecutive records. Each record starts with two 32-bit words encoded with the least significant byte first, like this:

data[0] = length & 0xff
data[1] = (length >> 8) & 0xff
data[2] = (length >> 16) & 0xff
data[3] = (length >> 24) & 0xff
data[4] = type & 0xff
data[5] = (type >> 8) & 0xff
data[6] = (type >> 16) & 0xff
data[7] = (type >> 24) & 0xff

The first word, length, is the number of octets of additional data which follows. If this value is not a multiple of four, padding octets follow to bring the total to a multiple of four.

The second word, type, indicates the meaning of any additional data. The values currently defined are:

Value	Meaning
2	Transmitted RTCP - the data is an IP datagram which is an RTCP report generated by the RTCP handler
3	Received RTCP - the data is an IP datagram containing an RTCP report received by the RTCP handler
4	Summary report - the data is a report giving statistics of all traffic so far - provoked by sm_rtcphand_request_statistics()
5	Received RTCP with NTP - the data is same as for Received RTP above except that it is preceded by a 8 byte field which, when NTP time is available, will contain a network byte order fixed-point NTP timestamp as described in RFC 3550 giving the packet arrival time of the RTCP packet allowing round trip time to be calculated.
6	Augmented summary report - the data is a report giving additional packet timing information - provoked by sm_rtcphand_request_statistics()

Note that IP datagrams may not be the actual data transmitted or received for two reasons. Firstly, they are unencrypted, even if they would be encrypted while in transit, and secondly they may be reconstructions which do not fill in irrelevant fields so, for example, the time-to-live field might be zero, and IP options present in transit may be missing. The format is specified to be an IP datagram to guarantee that any information which might be in the real IP datagram can be easily represented in the data retrieved through sm_rtcphand_get_data().

A sample library for processing RTCP handler data is provided with TiNG, see Prosody RTCP library for documentation.

Fields

rtcphand: The RTCP handler to use
data: A pointer to the buffer into which data should be read.
max_length: The amount of space in the buffer.
done_length: The amount of data actually read.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_get_event

Prototype Definition

int sm_rtcphand_get_event(struct sm_rtcphand_event_parms *eventp)

Parameters

a structure of the following type:

typedef struct sm_rtcphand_event_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSMEventId event;					/* out */
} SM_RTCPHAND_EVENT_PARMS;

Description

If the call completes successfully event will hold the tSMEventId belonging to rtcphand. The tSMEventId is valid until the RTCP handler is destroyed using sm_rtcphand_destroy(). This event will be signalled when there is data to be collected using sm_rtcphand_get_data() or when a status change occurs on the RTCP handler. When the event is signalled the user should call sm_rtcphand_get_data() to try collecting data. If there is no data, the user must call sm_rtcphand_status() to discover the nature of the status change.

Fields

rtcphand: The RTCP handler
event: The event identifier

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_request_statistics

Prototype Definition

int sm_rtcphand_request_statistics(struct sm_rtcphand_request_statistics_parms *rrsp)

Parameters

*rrsp

a structure of the following type:

typedef struct sm_rtcphand_request_statistics_parms {
	tSMRTCPHandId rtcphand;					/* in */
	tSM_INT statcode;					/* in */
} SM_RTCPHAND_REQUEST_STATISTICS_PARMS;

Description

Instructs RTCP handler to provide a statistics report as soon as possible for the specified category of statistics. The statistics report will appear in the data retrieved through sm_rtcphand_get_data() and may be in addition to statistics reports generated for other reasons. It may not be an additional report if the RTCP handler was about to produce a report of the requested type anyway, for example if the specified report type is currently enabled by sm_rtcphand_config_reports()

Fields

rtcphand: The RTCP handler which is to provide the statistics
statcode: Which statistics are to be provided. See sm_rtcphand_get_data() for the possible types of statistics and their codes.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_rtcphand_status

Prototype Definition

int sm_rtcphand_status(struct sm_rtcphand_status_parms *statusp)

Parameters

a structure of the following type:

typedef struct sm_rtcphand_status_parms {
	tSMRTCPHandId rtcphand;					/* in */
	enum kSMRTCPHandStatus {
		kSMRTCPHandStatusRunning,
	} status;						/* out */
} SM_RTCPHAND_STATUS_PARMS;

Description

Returns the current status of the RTCP handler. This function must be called when the event obtained from sm_rtcphand_get_event() is signalled and sm_rtcphand_get_data() indicates that no data is available for collection.

Fields

rtcphand

The RTCP handler to interrogate

One of these values:

kSMRTCPHandStatusRunning: The RTCP handler is running normally.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_authentication_hmac_sha1

Prototype Definition

int sm_vmprx_config_authentication_hmac_sha1(struct sm_vmprx_config_authentication_hmac_sha1_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_authentication_hmac_sha1_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
	tSM_INT taglen;						/* in */
} SM_VMPRX_CONFIG_AUTHENTICATION_HMAC_SHA1_PARMS;

Description

Configures a VMP[rx] to use HMAC-SHA1 authentication, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmprx: The VMP[rx] to configure
keylen: The length of the authentication key in octets.
key: The authentication key.
taglen: The length of the authentication tag in bits.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_authentication_null

Prototype Definition

int sm_vmprx_config_authentication_null(struct sm_vmprx_config_authentication_null_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_authentication_null_parms {
	tSMVMPrxId vmprx;					/* in */
} SM_VMPRX_CONFIG_AUTHENTICATION_NULL_PARMS;

Description

Disables any authentication which may have been in use by a VMP[rx].

Fields

vmprx: The VMP[rx] to configure

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_alaw

Prototype Definition

int sm_vmprx_config_codec_alaw(struct sm_vmprx_codec_alaw_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_alaw_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode {
		kSMPLCModeDisabled,
		kSMPLCModeEnabled,
	} plc_mode;						/* in */
} SM_VMPRX_CODEC_ALAW_PARMS;

Description

Configures an A-law codec to the VMP[rx] setting the payload type mapping to payload_type.

It is possible to change the payload type mapping of a codec whilst a VMP[rx] remains valid by specifying a new payload type mapping for a given codec. This supersedes any previous mappings that were in effect for that codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_amrnb

Prototype Definition

int sm_vmprx_config_codec_amrnb(struct sm_vmprx_codec_amrnb_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_amrnb_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT aligned;					/* in */
	tSM_INT gsmefr;						/* in */
	enum kSMPLCMode plc_mode;				/* in */
	tSM_INT report_cmr;					/* in */
} SM_VMPRX_CODEC_AMRNB_PARMS;

Description

Configures the VMP[rx] to use the AMR narrow-band codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module amr-nb to have been downloaded. Alternatively the module amr-nb-all can be used if amr-nb-prs functionality is also required.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

aligned

Packet alignment (bandwidth efficient mode). 0 if packet is not aligned, otherwise packet is aligned.

gsmefr

Configures the codec to perform GSM-EFR equivalent decoding. This will assume non-aligned packets, non-sorted bits and 12.2 kHz mode encoding.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

report_cmr

Enables or disables the notification of CMR changes. If non-zero, then CMR changes will be reported via sm_vmprx_status_codec_amrnb().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_amrwb

Prototype Definition

int sm_vmprx_config_codec_amrwb(struct sm_vmprx_codec_amrwb_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_amrwb_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT aligned;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
	tSM_INT report_cmr;					/* in */
} SM_VMPRX_CODEC_AMRWB_PARMS;

Description

Configures the VMP[rx] to use the AMR wide-band codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module amr-wb to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

aligned

Packet alignment (bandwidth efficient mode). 0 if packet is not aligned, otherwise packet is aligned.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

report_cmr

Enables or disables the notification of CMR changes. If non-zero, then CMR changes will be reported via sm_vmprx_status_codec_amrwb().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_comfort_noise

Prototype Definition

int sm_vmprx_config_codec_comfort_noise(struct sm_vmprx_codec_comfort_noise_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_comfort_noise_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_COMFORT_NOISE_PARMS;

Description

Configures a comfort noise codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

This field is ignored. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_evrc

Prototype Definition

int sm_vmprx_config_codec_evrc(struct sm_vmprx_codec_evrc_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_evrc_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT post_filter;					/* in */
	enum kSMEVRCRTPMode {
		kSMEVRCRTPModeHeaderless,
		kSMEVRCRTPModeRFC2658,
		kSMEVRCRTPModeRFC3558,
	} rtp_mode;						/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_EVRC_PARMS;

Description

Configures the VMP[rx] to use the Enhanced Variable Rate Codec (EVRC), setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module evrc to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

post_filter

Configures whether or not to use a post-filter. It is used if this value is non-zero.

rtp_mode

Selects the RTP format for this codec. There are two commonly-used specifications for how to pack the the encoded data into an RTP packet. One of these values:

kSMEVRCRTPModeHeaderless: Encodes the bitstream as raw encoded bytes, with no headers. This requires that there is only one frame per packet.
kSMEVRCRTPModeRFC2658: Encodes the bitstream as specified in IETF RFC 2658. The header is one byte. This specification only allows for one frame per packet.
kSMEVRCRTPModeRFC3558: Encodes the bitstream as specified in IETF RFC 3558. The header is two bytes, plus one byte for every two frames in the packet.

Configures packet loss concealment for this codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g722

Prototype Definition

int sm_vmprx_config_codec_g722(struct sm_vmprx_codec_g722_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g722_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_G722_PARMS;

Description

Configures the VMP[rx] to use the G.722 codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module g722 to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g722_1

Prototype Definition

int sm_vmprx_config_codec_g722_1(struct sm_vmprx_codec_g722_1_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g722_1_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT bitrate;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_G722_1_PARMS;

Description

Configures the VMP[rx] to use the G.722.1, licensed from Polycom®, wideband codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module g722-1 to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

bitrate

Bitrate of the incoming data. Must be 24000 or 32000 (the superwideband bit rates specified in G.722.1 Annex C are not supported).

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g723_1

Prototype Definition

int sm_vmprx_config_codec_g723_1(struct sm_vmprx_codec_g723_1_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g723_1_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT post_filter;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_G723_1_PARMS;

Description

Configures the VMP[rx] to use the G.723.1 codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module rtcp to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

post_filter

Configures whether or not to use a post-filter. It is used if this value is non-zero.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g726

Prototype Definition

int sm_vmprx_config_codec_g726(struct sm_vmprx_codec_g726_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g726_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT bits;						/* in */
	enum kSMPLCMode plc_mode;				/* in */
	enum kSMG726Variant {
		kSMG726VariantRFC3551,
		kSMG726VariantAAL2,
	} variant;						/* in */
} SM_VMPRX_CODEC_G726_PARMS;

Description

Configures the VMP[rx] to use the G.726 codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module g726 to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

bits

The bit rate at which the codec runs, specified as the number of bits per sample. This must be 2, 3, 4, or 5.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

The sample packing variant to use One of these values:

kSMG726VariantRFC3551: Use the packing mode described in RFC 3551
kSMG726VariantAAL2: Use the packing mode used by AAL2 (ITU-T I.366.2)

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g728

Prototype Definition

int sm_vmprx_config_codec_g728(struct sm_vmprx_codec_g728_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g728_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT rate;						/* in */
	tSM_INT post_filter;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_G728_PARMS;

Description

Configures the VMP[rx] to use the G.728 codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module g728 to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

rate

The decoding rate to use, in bits per second. G.728 supports three rates: 9600, 12800 and 16000.

post_filter

Configures whether or not to use a post-filter. It is used if this value is non-zero.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g729ab

Prototype Definition

int sm_vmprx_config_codec_g729ab(struct sm_vmprx_codec_g729ab_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g729ab_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_G729AB_PARMS;

Description

Configures an G.729 AB codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

This requires the module g729ab to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_g729i

Prototype Definition

int sm_vmprx_config_codec_g729i(struct sm_vmprx_codec_g729i_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_g729i_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMG729IMode {
		kSMG729IModeG729D,
		kSMG729IModeG729,
		kSMG729IModeG729E,
	} g729_mode;						/* in */
} SM_VMPRX_CODEC_G729I_PARMS;

Description

Configures an G.729 I codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

This requires the module g729i to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

g729_mode

Sets the data rate according to G.729 Annex D, to the basic G.729 standard, or to G.729 Annex E, respectively. This mode should be chosen to match the payload type. One of these values:

kSMG729IModeG729D: G.729 Annex D
kSMG729IModeG729: G.729 standard
kSMG729IModeG729E: G.729 Annex E

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_gsmefr

Prototype Definition

int sm_vmprx_config_codec_gsmefr(struct sm_vmprx_codec_gsmefr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_gsmefr_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_GSMEFR_PARMS;

Description

Configures the VMP[rx] to use the GSM-EFR codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

Note that this function is for use with the lightweight gsm-efr module only. Where full AMR-NB support is also required, please use sm_vmprx_config_codec_amrnb() with parameter gsmefr=1 and the module amr-nb or amr-nb-all instead.

This requires the module gsm-efr to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Configures packet loss concealment for this codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_gsmfr

Prototype Definition

int sm_vmprx_config_codec_gsmfr(struct sm_vmprx_codec_gsmfr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_gsmfr_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMGSMVariant {
		kSMGSMVariantStandard,
		kSMGSMVariantMS,
	} variant;						/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_GSMFR_PARMS;

Description

Configures the VMP[rx] to use the GSM full-rate codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module gsm-fr to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Configures which GSM variant is to be used. One of these values:

kSMGSMVariantStandard: Use the standard GSM 06.10 codec.
kSMGSMVariantMS: Decode packets using the alternate MS-GSM encoding scheme. The GSM 06.10 codec itself is identical, however the bitstream is packed with two frames in 65 bytes instead of one frame in 33 bytes.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_ilbc

Prototype Definition

int sm_vmprx_config_codec_ilbc(struct sm_vmprx_codec_ilbc_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_ilbc_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT frame_len;					/* in */
	tSM_INT enhancer;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_ILBC_PARMS;

Description

Configures the VMP[rx] to use the iLBC codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module ilbc to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

frame_len

Length of each frame which will be received, in milliseconds. This must be either 20 or 30.

enhancer

Configures whether or not to use an enhancer. It is used if this value is non-zero.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_isac

Prototype Definition

int sm_vmprx_config_codec_isac(struct sm_vmprx_codec_isac_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_isac_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_ISAC_PARMS;

Description

Configures an iSAC to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

This requires the module isac to have been downloaded.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_l16

Prototype Definition

int sm_vmprx_config_codec_l16(struct sm_vmprx_codec_l16_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_l16_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_L16_PARMS;

Description

Configures an L16 codec to the VMP[rx] setting the payload type mapping to payload_type.

The L16 encoding is as described in IETF RFC 3551 section 4.5.11

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_l8

Prototype Definition

int sm_vmprx_config_codec_l8(struct sm_vmprx_codec_l8_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_l8_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_L8_PARMS;

Description

Configures an L8 codec to the VMP[rx] setting the payload type mapping to payload_type.

The L8 encoding is as described in IETF RFC 3551 section 4.5.10

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_melpe

Prototype Definition

int sm_vmprx_config_codec_melpe(struct sm_vmprx_codec_melpe_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_melpe_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_MELPE_PARMS;

Description

Configures a melpe codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

This requires the module melpe to have been downloaded.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_mulaw

Prototype Definition

int sm_vmprx_config_codec_mulaw(struct sm_vmprx_codec_mulaw_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_mulaw_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_MULAW_PARMS;

Description

Configures a mu-law codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_opus

Prototype Definition

int sm_vmprx_config_codec_opus(struct sm_vmprx_codec_opus_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_opus_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT decode_fec;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_OPUS_PARMS;

Description

Configures a VMP[rx] to use Opus codec as defined in IETF RFC 6716, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

The sample rate of the resulting audio is set to match the VMP[rx], and in the current release should be either 8000 or 16000.

Fields

vmprx: The VMP[rx] to which to add the codec.
decode_fec: Set to zero if FEC (forward error correction) information in packets is not to be decoded, set to 1 to enable FEC decode. On low packet loss network inhibiting FEC decode can reduce CPU load when there is little likelyhood of this information being used.
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_rfc2833

Prototype Definition

int sm_vmprx_config_codec_rfc2833(struct sm_vmprx_codec_rfc2833_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_rfc2833_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_RFC2833_PARMS;

Description

Configures an IETF RFC 2833 codec on the VMP[rx], setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

This field is ignored. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_rfc4040

Prototype Definition

int sm_vmprx_config_codec_rfc4040(struct sm_vmprx_codec_rfc4040_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_rfc4040_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_RFC4040_PARMS;

Description

Configures an IETF RFC 4040 codec on the VMP[rx], setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_rttext

Prototype Definition

int sm_vmprx_config_codec_rttext(struct sm_vmprx_codec_rttext_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_rttext_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT redundant_payload_type;				/* in */
	tSM_INT out_of_order_delay;				/* in */
} SM_VMPRX_CODEC_RTTEXT_PARMS;

Description

Configures the VMP[rx] to be able to receive real-time text, setting the payload type mapping to payload_type and the redundant format payload type mapping to redundant_payload_type . This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload types will be decoded using this codec.

The packet format is described in IETF RFC 4103.

A VMP[rx] that is configured to use this codec will output octet data rather than audio. As such it will normally be connected to a channel configured for data communitcations with the raw protocol and no encoding. The data collected from the channel will be 32 bit values, presented as 4 octets with the least significant octet first. The values will correspond to UCS4 characters.

This requires the module rttext to have been downloaded.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
redundant_payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13) for packets with redundant data. Supply a value of -1 if redundant data is not to be received.
out_of_order_delay: The time in milliseconds to wait for a text block once a later block has been received.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_silk

Prototype Definition

int sm_vmprx_config_codec_silk(struct sm_vmprx_codec_silk_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_silk_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_SILK_PARMS;

Description

Configures the VMP[rx] to use the SILK codec from Skype, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

The sample rate of the resulting audio is set to match the VMP[rx], and in the current release should be either 8000 or 16000.

Note that the current firmware implementation of the decoder does not make use of any "forward error correction" (FEC) data transmitted by the encoder.

This requires the module silk to have been downloaded.

Fields

The VMP[rx] to which to add the codec.

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_smv

Prototype Definition

int sm_vmprx_config_codec_smv(struct sm_vmprx_codec_smv_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_smv_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_SMV_PARMS;

Description

Configures the VMP[rx] to use the SMV codec, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be decoded using this codec.

This requires the module smv to have been downloaded.

Fields

The VMP[rx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Enables or disables PLC (packet loss concealment) as appropriate for the codec. Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_speex

Prototype Definition

int sm_vmprx_config_codec_speex(struct sm_vmprx_codec_speex_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_speex_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_UT32 nb_channels;					/* in */
	tSM_UT32 sampling_rate;					/* in */
	enum kSMSpeexMode {
		kSMSpeexNarrowbandMode,
		kSMSpeexWidebandMode,
		kSMSpeexUltrawidebandMode,
	} bandwidth;						/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_SPEEX_PARMS;

Description

Configures the VMP[rx] to use Speex for encoding data, as defined in IETF RFC 5574. However, neither variable bit-rate coding (VBR) nor discontinuous transmission (DTX) are supported.

This requires the module speex_vmp to have been downloaded.

Fields

The VMP[rx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

nb_channels

Number of channels (mono vs stereo: options 1 or 2)

sampling_rate

The desired sampling rate of the audio.

bandwidth

Ignored. kSMSpeexNarrowbandMode is always used since it is the only value supported by current firmware. One of these values:

kSMSpeexNarrowbandMode: Narrowband (8 kHz sampling rate) mode
kSMSpeexWidebandMode: Wideband (16 kHz sampling rate) mode
kSMSpeexUltrawidebandMode: Ultrawideband (32 kHz sampling rate) mode

Option for packet loss concealment (plc). Note the codec implementation may not allow PLC to be disabled. One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_speex_mode

Prototype Definition

int sm_vmprx_config_codec_speex_mode(struct sm_vmprx_codec_speex_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_speex_mode_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_UT32 enh;						/* in */
} SM_VMPRX_CODEC_SPEEX_MODE_PARMS;

Description

Configures the VMP[rx] to use Speex for encoding data, as defined in IETF RFC 5574.

This function requires the module speex_vmp to have been downloaded, and may be called at any time after the corresponding call to sm_vmprx_config_codec_speex.

Fields

vmprx: The VMP[rx] to which to add this codec
enh: Enhanced output enabled (1) or disabled (0). Controls whether the perceived quality of the output is to be artificially enhanced, at the cost of a slightly reduced channel count. Default: 0. Recommended value (unless channel count is critical): 1.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_sse

Prototype Definition

int sm_vmprx_config_codec_sse(struct sm_vmprx_codec_sse_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_sse_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_SSE_PARMS;

Description

Configures the VMP[rx] to be able to receive SSE messages, setting the payload type mapping to payload_type. This supersedes any previous mapping that was in effect for this codec.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches the specified payload type will be treated as SSE messages.

This requires the module sse to have been downloaded.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec_tetra

Prototype Definition

int sm_vmprx_config_codec_tetra(struct sm_vmprx_codec_tetra_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_tetra_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPRX_CODEC_TETRA_PARMS;

Description

Configures a TETRA speech codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using this codec.

If the codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

There is not currently a standard packet encoding for wrapping TETRA-encoded speech into RTP. This implementation expects RTP frames that have standard RTP header followed by: ETSI two octet Payload header (with bits for framing rate, frame number, information element control, traffic type, contents control and payload) - the payload header follows the format described in ETSI TS 100 392-3-8 V0.0.8 section 5.2.1 TETRA ISI payload encoding. Two 18 octet tetra frames - each frame consisting of BFI bit followed by 137 bits of tetra encoded data (holding 30ms of encoded audio data according to traffic type 0 followed by 6 padding bits) - thus this pair of frames conveys 60ms of audio

The tetra encoded data in the 18 octet tetra frames is expected to be traffic type 0 - ACELP (ETS 300 395-2, 4.2.2.7) following MSB-LSB bit order.

The contents of the ETSI payload header are ignored apart from contents control bits which have following effect:

0 - normal case - traffic 1 and traffic 2 are used to construct signal
1 - use BFI procedure to fill in gap left by absent traffic 1
3 - use BFI procedure to fill in gap left by absent traffic 2
4 - use BFI procedure to fill in gap left by absent traffic 1

all other values: - we use packet loss concealment algorithm to fill in gap left by absent traffic 1 and traffic 2

Note for incoming data, the RTP timestamp is used to control jitter buffer frame numbers in Tetra payload header are ignored.

This requires the module tetra to have been downloaded.

Fields

vmprx: The VMP[rx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_dataloss

Prototype Definition

int sm_vmprx_config_dataloss(struct sm_vmprx_dataloss_parms *datalossp)

Parameters

*datalossp

a structure of the following type:

typedef struct sm_vmprx_dataloss_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT loss_threshold;					/* in */
} SM_VMPRX_DATALOSS_PARMS;

Description

Configures the data loss threshold for a VMP[rx]. When the VMP[rx] is running, sm_vmprx_status(), indicates whether or not data is currently being received. If no valid data is available for at least the data loss threshold since the last valid data, the status indicates that data is not being received. The status changes to indicate that data is being received when a valid data packet is received.

Packets which are discarded (for example, duplicates or those which fail authentication) are not considered valid data.

A data loss threshold of zero disables the reporting of data loss.

The VMP[rx] event is signalled when the first data packet is received, any time subsequently when the data loss threshold is reached, and any time when data arrives after data loss. When a VMP[rx] is first configured, it is already experiencing data loss (because there has obviously been no data for the data loss period, since there has never been data), so the VMP[rx] event is not signalled. If an application wants to have a data loss timeout to guard against no data ever being received, it needs to implement its own timer.

Fields

vmprx: The VMP[rx] to be configured
loss_threshold: The threshold to use (in mS).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_encryption_aes_cm

Prototype Definition

int sm_vmprx_config_encryption_aes_cm(struct sm_vmprx_config_encryption_aes_cm_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_encryption_aes_cm_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
} SM_VMPRX_CONFIG_ENCRYPTION_AES_CM_PARMS;

Description

Configures a VMP[rx] to use AES-CM encryption, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmprx: The VMP[rx] to configure
keylen: The length of the encryption key in octets.
key: The encryption key.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_encryption_aes_f8

Prototype Definition

int sm_vmprx_config_encryption_aes_f8(struct sm_vmprx_config_encryption_aes_f8_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_encryption_aes_f8_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
} SM_VMPRX_CONFIG_ENCRYPTION_AES_F8_PARMS;

Description

Configures a VMP[rx] to use AES-f8 encryption, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmprx: The VMP[rx] to configure
keylen: The length of the encryption key in octets.
key: The encryption key.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_encryption_null

Prototype Definition

int sm_vmprx_config_encryption_null(struct sm_vmprx_config_encryption_null_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_encryption_null_parms {
	tSMVMPrxId vmprx;					/* in */
} SM_VMPRX_CONFIG_ENCRYPTION_NULL_PARMS;

Description

Disables any encryption which may have been in use by a VMP[rx].

Fields

vmprx: The VMP[rx] to configure

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_forwarding

Prototype Definition

int sm_vmprx_config_forwarding(struct sm_vmprx_config_forwarding_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_forwarding_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kVMPrxFwdMode {
		kVMPrxFwdModeNone,
		kVMPrxFwdModeAll,
		kVMPrxFwdModeTypes,
	} mode;							/* in */
	enum kSMVMPrxFwdDestType {
		kSMVMPrxFwdDestTypeIPv4,
		kSMVMPrxFwdDestTypeIPv6,
	} dest_type;						/* in */
	union {
		struct {
			SOCKADDR_IN destination;		/* in */
			SOCKADDR_IN source;			/* in */
			int TOS;				/* in */
		} ipv4;						/* in */
		struct {
			SOCKADDR_IN6 destination;		/* in */
			SOCKADDR_IN6 source;			/* in */
		} ipv6;						/* in */
	} u;							/* in */
	int num_types;						/* in */
	struct sm_vmprx_forward_types {
		int incoming_pt;				/* in */
		int outgoing_pt;				/* in */
		enum kVMPrxFwdTranscoding {
			kVMPrxFwdTranscodingNone,
			kVMPrxFwdTranscodingAlawToMulaw,
			kVMPrxFwdTranscodingMulawToAlaw,
		} transcoding;
	} types[kVMPrxFwdMaxTypes];				/* in */
} SM_VMPRX_CONFIG_FORWARDING_PARMS;

Description

Configure a VMP[rx] to forward packet payloads to another endpoint

Fields

The VMP[rx] to forward packet payloads

mode

The payload forwarding mode One of these values:

kVMPrxFwdModeNone: Forward no packet payloads
kVMPrxFwdModeAll: Forward all packet payloads
kVMPrxFwdModeTypes: Forward only payloads that match the types specified

dest_type

One of these values:

kSMVMPrxFwdDestTypeIPv4: The packet payloads are to be forwarded to an IPv4 destination
kSMVMPrxFwdDestTypeIPv6: The packet payloads are to be forwarded to an IPv6 destination

ipv4

This field is only used if dest_type is kSMVMPrxFwdDestTypeIPv4.

destination: The SOCKADDR_IN structure specifying the destination IP address and port for the forwarded packet payloads. A struct SOCKADDR_IN must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
source: The SOCKADDR_IN structure allows you to specify the source IP address and port for the forwarded packets. A struct SOCKADDR_IN must be configured with an address family. The IP address may be specified, or the value INADDR_ANY may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
TOS: The Type Of Service (TOS) indicator to be sent with payloads

ipv6

This field is only used if dest_type is kSMVMPrxFwdDestTypeIPv6.

destination: The SOCKADDR_IN6 structure specifying the destination IP address and port for the forwarded packet payloads. A struct SOCKADDR_IN6 must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network byte order.
source: The SOCKADDR_IN6 structure allows you to specify the source IP address and port for the forwarded packets. A struct SOCKADDR_IN6 must be configured with an address family. The IP address may be specified, or a value equivalent to in6addr_any may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order.

num_types

types

The payload types to be forwarded

incoming_pt

The incoming payload type identifier

outgoing_pt

The outgoing payload type identifier to map this payload to

transcoding

The payload data transcoding One of these values:

kVMPrxFwdTranscodingNone: No transcoding
kVMPrxFwdTranscodingAlawToMulaw: Transcode payload data from A-law to Mu-law
kVMPrxFwdTranscodingMulawToAlaw: Transcode payload data from Mu-law to A-law

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_jitter

Prototype Definition

int sm_vmprx_config_jitter(struct sm_vmprx_jitter_parms *jitterp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_jitter_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_UT32 max_delay_ms;					/* in */
	tSM_UT32 initial_delay_ms;				/* in */
} SM_VMPRX_JITTER_PARMS;

Description

Allows an application to confgure the jitter buffer belonging to a VMP[rx]. Default values are used for the jitter buffer when a VMP[rx] is created, so explicit configuration may not be necesary. Reconfiguration of the jitter buffer may result in audible artifacts in the audio stream during reconfiguration.

It is generally considered that the total end-to-end delay must be no more than about 150 milliseconds for acceptable usability. Unavoidable delay comes from two main sources: packetisation delay and propagation delay. A codec causes packetisation delay, for example, the G.711 codec sending packets each containing 20 mS of data must add 20 mS of delay. Propagation delay obviously varies with the distance covered, with the longest Earthbound link (halfway around the world) taking at least 67 mS, as limited by the speed of light. In practice, delays of about 10 to 25 mS can be found within the U.S.A., with international delays being longer (e.g. U.S.A. to U.K. about 50 to 60 mS). This means that the jitter buffer should generally be limited to 100 mS, with a smaller value used for long-distance calls or when using codecs which impose a longer packetisation delay..

Fields

vmprx: The VMP[rx] to be configured
max_delay_ms: Maximum allowable length for the jitter buffer in milliseconds. The default is 100.
initial_delay_ms: Initial amount of audio the jitter buffer should accumulate at startup. The default is 50.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_jitter_mode

Prototype Definition

int sm_vmprx_config_jitter_mode(struct sm_vmprx_config_jitter_mode_parms *jitterp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_jitter_mode_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kSMVMPrxJitterBufferMode {
		kSMVMPrxJitterBufferModeNormal,
		kSMVMPrxJitterBufferModeAdaptive,
	} mode;							/* in */
	union {
		struct {
			tSM_UT32 target_delay;			/* in */
			float freq_upper_tolerance;		/* in */
			float freq_lower_tolerance;		/* in */
		} adaptive;					/* in */
	} u;							/* in */
} SM_VMPRX_CONFIG_JITTER_MODE_PARMS;

Description

Allows an application to confgure the mode of the jitter buffer belonging to a VMP[rx].

When mode is kSMVMPrxJitterBufferModeAdaptive the jitter buffer will attempt to keep the delay it introduces to target_delay. The rate at which corrections to the delay are made depends on the packet jitter and the transmitters sample clock frequency. Packet jitter may cause unnecessary corrections. This is more likely when the allowed sample clock frequency tolerance range is large.

The sample clock frequency tolerances are specified as percentages of the expected sample clock frequency. For example, if the expected frequency is 8kHz and freq_upper_tolerance is 1.5 and freq_lower_tolerance is 0.5, then the jitter buffer will attempt to track sample clock frequencies between 8.12kHz and 7.96kHz.

Fields

The VMP[rx] to be configured

mode

The mode of the jitter buffer. One of these values:

kSMVMPrxJitterBufferModeNormal: The normal jitter buffer mode.
kSMVMPrxJitterBufferModeAdaptive: The adaptive jitter buffer mode.

adaptive

This field is only valid if mode is kSMVMPrxJitterBufferModeAdaptive

target_delay: The target delay in milliseconds
freq_upper_tolerance: The upper limit of the sample clock frequency tolerance as a percentage
freq_lower_tolerance: The lower limit of the sample clock frequency tolerance as a percentage

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_jitter_resync_notify

Prototype Definition

int sm_vmprx_config_jitter_resync_notify(struct sm_vmprx_config_jitter_resync_notify_parms *notifyp)

Parameters

*notifyp

a structure of the following type:

typedef struct sm_vmprx_config_jitter_resync_notify_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT enable;						/* in */
} SM_VMPRX_CONFIG_JITTER_RESYNC_NOTIFY_PARMS;

Description

Configures the notification of VMP[rx] timestamp resync. The clock rate of an incomming RTP stream may deviate by a small amount from that of the local system (clock drift) requiring the VMP[rx] jitter buffer to resynchronise when the accumulated drift exceeds jitter buffer capacity. By default the the application is unaware of any such resyncs, but this call allows the VMP[rx] to be configured so that the VMP[rx] event is signalled when such resync occurs. The application then must invoke sm_vmprx_status() to obtain the resync status information.

Fields

vmprx: The VMP[rx] to be configured
enable: A non-zero value value enables notification of sync loss.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_profile_specific

Prototype Definition

int sm_vmprx_config_profile_specific(struct sm_vmprx_config_profile_specific_parms *psp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_profile_specific_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT enable;						/* in */
	char *plugin;						/* in */
	tSM_INT paramlen;					/* in */
	char *paramval;						/* in */
} SM_VMPRX_CONFIG_PROFILE_SPECIFIC_PARMS;

Description

Normally profile specific RTP extensions (such as use of RTP extension header) are ignored. Invoking this call allows profile specific processing to be performed on received RTP packets by a specified ProsodyS plugin. Typically such a plugin will cause occasional VMP[rx] events and status notifications to occur in order to indicate that profile specific state transitions have taken place. Information pertaining to a state transition can then be obtained by invoking sm_vmprx_status() and sm_vmprx_status_profile_specific() . See documentation supplied with ProsodyS profile specific plugin for further details.

Fields

vmprx: The VMP[rx] to configure
enable: Set non-zero to enable profile specific RTP processing.
plugin: Set to a zero terminated string identifying plugin that should perform profile specific processing.
paramlen: The length of the plugin specific parameter string in octets.
paramval: The plugin specific parameter string contents.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_sample_rate

Prototype Definition

int sm_vmprx_config_sample_rate(struct sm_vmprx_sample_rate_parms *sample_ratep)

Parameters

*sample_ratep

a structure of the following type:

typedef struct sm_vmprx_sample_rate_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_UT32 sample_rate;					/* in */
} SM_VMPRX_SAMPLE_RATE_PARMS;

Description

Allows an application to confgure the sample rate for output from a VMP[rx]. If no rate is configured, it defaults to 8000 samples per second. Some codecs (for example, PCMA - the G.711 A-law codec) can run at any sampling rate, other codecs are designed to run only at specific sampling rates. While the VMP[rx] may produce data at any sampling rate for any codec, running a codec at a non-standard sampling rate may result in unsatisfactory performance.

Fields

vmprx: The VMP[rx] to be configured
sample_rate: The sample rate in samples per second. The default is 8000.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_sprt

Prototype Definition

int sm_vmprx_config_sprt(struct sm_vmprx_config_sprt_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_config_sprt_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSMSPRTId sprt;						/* in */
} SM_VMPRX_CONFIG_SPRT_PARMS;

Description

Configure the association of a VMP[rx] with a SPRT end point. If payload_type is -1 then sprt can be kSMNullSPRTId, otherwise it must be a value created by a call to sm_sprt_create().

This requires the module sprt to have been downloaded.

Fields

vmprx: The VMP[rx] to be associated with a SPRT endpoint
payload_type: The payload type identifer to use for SPRT packets (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the SPRT end point, preventing its use.
sprt: The SPRT end point that will handle SPRT packets

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_tones

Prototype Definition

int sm_vmprx_config_tones(struct sm_vmprx_tone_parms *tonep)

Parameters

a structure of the following type:

typedef struct sm_vmprx_tone_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT regen_tones;					/* in */
	tSM_INT detect_tones;					/* in */
	tSM_INT enforce_tone_spacing;				/* in */
} SM_VMPRX_TONE_PARMS;

Description

Allows an application to specify the action to be taken upon receipt of RFC2833 tones packets in an RTP stream.

Regenerating the tones is a requirement for applications acting as a VoIP to TDM gateway. Applications that need to detect tones from the audio stream will frequently be required to regenerate tones from RFC 2833 packets, this is of particular importance when using codecs that cannot adequately encode tones (e.g. G.729). If regen_tones contains a non-zero value, the VMP[rx] will attempt to regenerate tones in the audio stream when an RFC2833 packet is received.

Some nonconformant RTP IP phones can generate RFC 2833 packets with less than the required minimum gap between consecutive tones. If enforce_tone_spacing contains a non-zero value, the VMP[rx] will trim the start of any regenerated tone that follows on too early after a previous regenerated tone in order to ensure that the minimum gap is always observed.

Applications that terminate a VoIP call may choose not to regenerate tones and to rely on the RFC2833 tone notifications. Supplying a non-zero value in the detect_tones field instructs the VMP[rx] to notify the user when an RFC 2833 tone packet is received in the RTP stream. The VMP[rx]'s event will be set when a tone notification is available.

Fields

vmprx: The VMP[rx] to be configured
regen_tones: Indicator of whether RFC2833 tones that are present in the data stream should be regenerated as audio data. A non-zero value instructs the VMP[rx] to regenerate these tones (see supported tones from RFC2833).
detect_tones: A non-zero value instructs the VMP[rx] to notify the user when an RFC2833 tone is detected in the RTP stream.
enforce_tone_spacing: A non-zero value instructs the VMP[rx] to enforce a minimum silence between regenerated tones.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_unhandled_payload_reporting

Prototype Definition

int sm_vmprx_config_unhandled_payload_reporting(struct sm_vmprx_unhandled_payload_reporting_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_unhandled_payload_reporting_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT delay;						/* in */
} SM_VMPRX_UNHANDLED_PAYLOAD_REPORTING_PARMS;

Description

Configures a VMP[rx] to report when packets arrive with a payload type it is not configured to handle. The delay prevents repeat notifications from being sent too often. A zero delay will cause every packet with an unhandled payload type to be reported. A negative delay disables reporting of unhandled payload types.

Fields

vmprx: The VMP[rx] to be configured
delay: The minimum delay between reports of unhandled payload types (in ms).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_create

Prototype Definition

int sm_vmprx_create(struct sm_vmprx_create_parms *vmprxp)

Parameters

*vmprxp

a structure of the following type:

typedef struct sm_vmprx_create_parms {
	tSMVMPrxId vmprx;					/* out */
	tSMModuleId module;					/* in */
	enum kSMVMPrxType {
		kSMVMPrxTypeIPv4,
		kSMVMPrxTypeIPv6,
	} type;							/* in */
	struct in_addr address;					/* in */
	struct in6_addr ipv6_address;				/* in */
	tSM_INT mux_rtcp;					/* in */
} SM_VMPRX_CREATE_PARMS;

Description

Allocates, on a specific module, a new VMP[rx] to receive incoming RTP data. If the call completes successfully, the parameter vmprx will be set to the identifier for that vmprx.

A VMP[rx] is automatically allocated an even numbered port number for incoming RTP data, this information may be obtained by waiting for sm_vmprx_status() to return the port information. Any RTP data arriving at the VMP[rx] will be interpreted based on the codec configuration. The VMP[rx] will discard any incoming packets that do not match it's current configuration settings.

This requires the module vmprx to have been downloaded.

Fields

The newly created VMP[rx].

module

A value obtained from sm_open_module() which indicates the module where the VMP[rx] is to be allocated.

type

One of these values:

kSMVMPrxTypeIPv4: The VMP[rx] is to receive IPv4 packets
kSMVMPrxTypeIPv6: The VMP[rx] is to receive IPv6 packets

The address on which this VMP[rx] is to listen if type is kSMVMPrxTypeIPv4.

ipv6_address

The address on which this VMP[rx] is to listen if type is kSMVMPrxTypeIPv6.

mux_rtcp

If this field is non-zero, indicates any RTCP packets are expected to arrive on same port as incoming RTP data rather than the usual convention of arriving on next odd numbered port. In this case, as per RFC5761, use of RTP payload types 64..95 should not be configured for this VMP[rx].

Returns

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

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

Prosody RTP processing: API: sm_vmprx_destroy

Prototype Definition

int sm_vmprx_destroy(tSMVMPrxId vmprx)

Parameters

vmprx: A tSMVMPrxId that has been prevously created by a call to sm_vmprx_create().

Description

Destroys vmprx and invalidates the tSMVMPrxId. Normally, a VMP[rx] will only be destroyed when it is in the stopped state. If the VMP[rx] is not in the stopped state, it will be implicitly stopped. It is an error to refer to a VMP[rx] once it has been destroyed.

If a call to sm_vmprx_create() completes successfully, sm_vmprx_stop() should be used to stop to the VMP[rx] and move it into the stopped state.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_get_datafeed

Prototype Definition

int sm_vmprx_get_datafeed(struct sm_vmprx_datafeed_parms *datafeedp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_datafeed_parms {
	tSMVMPrxId vmprx;					/* in */
	tSMDatafeedId datafeed;					/* out */
} SM_VMPRX_DATAFEED_PARMS;

Description

Request a datafeed identifier from a VMP[rx]. This identifer can subsequently be used in a call to any of the *_datafeed_connect() functions to connect the output from the VMP[rx] to a destination. It is valid until the VMP[rx] is destroyed. Datafeed connections can only be made between objects allocated on the same tSMModuleId.

Requires the module datafeed to have been downloaded.

Fields

vmprx: The VMP[rx] from which to obtain a datafeed
datafeed: The datafeed object associated with the VMP[rx]

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_get_event

Prototype Definition

int sm_vmprx_get_event(struct sm_vmprx_event_parms *eventp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_event_parms {
	tSMVMPrxId vmprx;					/* in */
	tSMEventId event;					/* out */
} SM_VMPRX_EVENT_PARMS;

Description

If the call completes successfully event will hold the tSMEventId belonging to vmprx. The tSMEventId is valid until the VMP[rx] is destroyed using sm_vmprx_destroy(). This event will be signalled when a status change occurs on the VMP[rx]. When the event is signalled the user must call sm_vmprx_status() to discover the nature of the status change.

Fields

vmprx: The VMP[rx]
event: The event identifier

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_get_ports

Prototype Definition

int sm_vmprx_get_ports(struct sm_vmprx_port_parms *portp)

Parameters

*portp

a structure of the following type:

typedef struct sm_vmprx_port_parms {
	tSMVMPrxId vmprx;					/* in */
	int RTP_port;						/* out */
	int RTCP_port;						/* out */
	struct in_addr address;					/* out */
	struct in6_addr ipv6_address;				/* out */
	tSM_UT32 nowait;					/* in */
} SM_VMPRX_PORT_PARMS;

Description

Retrieves the RTP and RTCP port numbers which have been allocated by this VMP[rx] and on which it is listening.

If the call completes successfully, RTP_port will contain the port number where RTP packets should be directed for this VMP[rx]. Similarly, RTCP_port will contain the port number where RTCP packets should be directed.

Fields

vmprx: The VMP[rx] to be interrogated
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 if this is a IPv4 VMP[rx].
ipv6_address: The address on which this VMP[rx] is listening if this is a IPv6 VMP[rx].
nowait: Selects blocking or non-blocking mode for this API call. In non-blocking mode the API call may return without the requested information. It is recommended that users wait for sm_vmprx_status() to inform the application that the port and address information is available, rather than using this API call. If the nowait flag is clear, the API call will block until the desired information is available, otherwise the API call will return immediately.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_ice_stun_change_role

Prototype Definition

int sm_vmprx_ice_stun_change_role(struct sm_vmprx_ice_stun_change_role_parms *rolep)

Parameters

*rolep

a structure of the following type:

typedef struct sm_vmprx_ice_stun_change_role_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kSMICERole local_role;				/* in */
} SM_VMPRX_ICE_STUN_CHANGE_ROLE_PARMS;

Description

Changes the role of ICE compatible STUN on the VMP[rx].

Note: the role can only be changed when in either the controlled or controlling role and it can only be changed to the controlling or controlled role.

This requires the module icestun to have been downloaded.

Fields

A VMP[rx] running ICE compatible STUN.

local_role

The new role of the local ICE agent. Note: changing to kSMICERoleNone or kSMICERoleLite is not permitted. One of these values:

kSMICERoleNone: The VidMP[rx] does not handle STUN packets.
kSMICERoleLite: The local ICE agent is an ice-lite agent.
kSMICERoleControlled: The local ICE agent is controlled.
kSMICERoleControlling: The local ICE agent is controlling.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_ice_stun_config

Prototype Definition

int sm_vmprx_ice_stun_config(struct sm_vmprx_ice_stun_config_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_ice_stun_config_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kSMICERole {
		kSMICERoleNone,
		kSMICERoleLite,
		kSMICERoleControlled,
		kSMICERoleControlling,
	} local_role;						/* in */
	char *local_ice_ufrag;					/* in */
	tSM_UT32 local_ice_ufrag_length;			/* in */
	char *local_ice_pwd;					/* in */
	tSM_UT32 local_ice_pwd_length;				/* in */
	tSM_UT64 role_tiebreaker;				/* in */
} SM_VMPRX_ICE_STUN_CONFIG_PARMS;

Description

Enables or disables ICE compatible STUN on the VMP[rx]. See IETF RFC 5245 and IETF RFC 5389 for more details.

This requires the module icestun to have been downloaded.

Fields

local_ice_ufrag_length

The VMP[rx] being configured.

local_role

The role of the local ICE agent. One of these values:

kSMICERoleNone: The VMP[rx] does not handle STUN packets.
kSMICERoleLite: The local ICE agent is an ice-lite agent.
kSMICERoleControlled: The local ICE agent is controlled.
kSMICERoleControlling: The local ICE agent is controlling.

local_ice_ufrag

The local ICE username fragment.

The length of the local ICE username fragment.

local_ice_pwd

The local ICE password.

local_ice_pwd_length

The length of the local ICE password.

role_tiebreaker

The ICE role tiebreaker value.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_ice_stun_remote_credentials

Prototype Definition

int sm_vmprx_ice_stun_remote_credentials(struct sm_vmprx_ice_stun_remote_credentials_parms *credentialsp)

Parameters

*credentialsp

a structure of the following type:

typedef struct sm_vmprx_ice_stun_remote_credentials_parms {
	tSMVMPrxId vmprx;					/* in */
	char *remote_ice_ufrag;					/* in */
	tSM_UT32 remote_ice_ufrag_length;			/* in */
	char *remote_ice_pwd;					/* in */
	tSM_UT32 remote_ice_pwd_length;				/* in */
} SM_VMPRX_ICE_STUN_REMOTE_CREDENTIALS_PARMS;

Description

Sets the remote credentials.

This requires the module icestun to have been downloaded.

Fields

vmprx: A VMP[rx] running ICE compatible STUN.
remote_ice_ufrag: The remote ICE username fragment.
remote_ice_ufrag_length: The length of the remote ICE username fragment.
remote_ice_pwd: The remote ICE password.
remote_ice_pwd_length: The length of the remote ICE password.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_ice_stun_send_bind_request

Prototype Definition

int sm_vmprx_ice_stun_send_bind_request(struct sm_vmprx_ice_stun_send_bind_request_parms *requestp)

Parameters

*requestp

a structure of the following type:

typedef struct sm_vmprx_ice_stun_send_bind_request_parms {
	tSMVMPrxId vmprx;					/* in */
	int use_RTCP_port;					/* in */
	char transaction_id[12];				/* in */
	union {
		SOCKADDR_IN ipv4;				/* in */
		SOCKADDR_IN6 ipv6;				/* in */
	} destination;						/* in */
	tSM_UT32 priority;					/* in */
	tSM_INT use_candidate;					/* in */
} SM_VMPRX_ICE_STUN_SEND_BIND_REQUEST_PARMS;

Description

Sets up VMP[rx] to send periodic STUN bind requests at successively longer intervals starting from 500ms to destination address until a reply is received or 7 attempts have been made with no reply occuring. Multiple calls to this function can set up a VMP[rx] with multiple STUN bind destination addreses (up to a set of 16 simultainuous ongoing candidates). A destination address is removed from the set of candidates when a reply is received or a timeout is signalled (indicated by a sm_vmprx_status() kSMVMPrxStatusSTUNBindResponse).

This requires the module icestun to have been downloaded.

Fields

A VMP[rx] running ICE compatible STUN.

use_RTCP_port

Which port to use as the source for the request. When non-zero, use the RTCP port. Otherwise, the RTP port is used

transaction_id

The transaction ID to use, in the same byte order as the packet.

destination

ipv4: The destination on the bind request when the VMP[rx] is an IPv4 endpoint.
ipv6: The destination on the bind request when the VMP[rx] is an IPv6 endpoint.

priority

The priority to assign to a learned peer reflexive address.

use_candidate

An indicator of whether to include the USE-CANDIDATE attribute.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_set_rtcphand

Prototype Definition

int sm_vmprx_set_rtcphand(struct sm_vmprx_set_rtcphand_parms *rvp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_set_rtcphand_parms {
	tSMVMPrxId vmprx;					/* in */
	tSMRTCPHandId rtcphand;					/* in */
} SM_VMPRX_SET_RTCPHAND_PARMS;

Description

Configures the RTCP handler which handles RTCP for the VMP[rx]. The RTCP handler and VMP[rx] must have been allocated on same module.

Fields

vmprx: The VMP[rx] to be configured
rtcphand: The RTCP handler to use. The value kSMNullRTCPHandId, means that no RTCP handler is to be used.

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

The VMP[rx] to interrogate

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() .

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()

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

The port the STUN bind request was received on.

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

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

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.

remote_is_controlling

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.

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

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.

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.

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

local_was_controlling

The reflexive port.

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]

Prosody RTP processing: API: sm_vmprx_status_codec_amrnb

Prototype Definition

int sm_vmprx_status_codec_amrnb(struct sm_vmprx_status_codec_amrnb_parms *amrnbp)

Parameters

*amrnbp

a structure of the following type:

typedef struct sm_vmprx_status_codec_amrnb_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPrxAMRNBStatus {
		kSMVMPrxAMRNBStatusNone,
		kSMVMPrxAMRNBStatusNewCMR,
	} status;						/* out */
	union {
		struct {
			tSM_INT bitrate;			/* out */
		} cmr;						/* out */
	} u;							/* out */
} SM_VMPRX_STATUS_CODEC_AMRNB_PARMS;

Description

Fields

The VMP[rx] to query

The payload type which is configured as AMR-NB

The AMR-NB status One of these values:

kSMVMPrxAMRNBStatusNone: No AMR-NB status to report
kSMVMPrxAMRNBStatusNewCMR: An AMR-NB packet with a different CMR had been received.

cmr

This is only valid when status is kSMVMPrxAMRNBStatusNewCMR

bitrate: The received CMR bitrate value. Note that zero is returned when no specific mode is requested.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_status_codec_amrwb

Prototype Definition

int sm_vmprx_status_codec_amrwb(struct sm_vmprx_status_codec_amrwb_parms *amrwbp)

Parameters

*amrwbp

a structure of the following type:

typedef struct sm_vmprx_status_codec_amrwb_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPrxAMRWBStatus {
		kSMVMPrxAMRWBStatusNone,
		kSMVMPrxAMRWBStatusNewCMR,
	} status;						/* out */
	union {
		struct {
			tSM_INT bitrate;			/* out */
		} cmr;						/* out */
	} u;							/* out */
} SM_VMPRX_STATUS_CODEC_AMRWB_PARMS;

Description

Fields

The VMP[rx] to query

The payload type which is configured as AMR-WB

The AMR-WB status One of these values:

kSMVMPrxAMRWBStatusNone: No AMR-WB status to report
kSMVMPrxAMRWBStatusNewCMR: An AMR-WB packet with a different CMR had been received.

cmr

This is only valid when status is kSMVMPrxAMRWBStatusNewCMR

bitrate: The received CMR bitrate value. Note that zero is returned when no specific mode is requested.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_status_codec_sse

Prototype Definition

int sm_vmprx_status_codec_sse(struct sm_vmprx_status_codec_sse_parms *ssep)

Parameters

*ssep

a structure of the following type:

typedef struct sm_vmprx_status_codec_sse_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPrxSSEStatus {
		kSMVMPrxSSEStatusNone,
		kSMVMPrxSSEStatusMessage,
	} status;						/* out */
	char *payload;						/* inout */
	tSM_INT max_length;					/* in */
	tSM_INT length;						/* out */
} SM_VMPRX_STATUS_CODEC_SSE_PARMS;

Description

This requires the module sse to have been downloaded.

Fields

The VMP[rx] to query

The payload type which is configured as SSE

The SSE status One of these values:

kSMVMPrxSSEStatusNone: No SSE status to report
kSMVMPrxSSEStatusMessage: A SSE message has been received

payload

A pointer to a buffer to receive the SSE message payload

max_length

The length of the buffer

length

The length of data written to the buffer

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_status_discard_codec_specific

Prototype Definition

int sm_vmprx_status_discard_codec_specific(tSMVMPrxId vmprx)

Parameters

vmprx: The VMP[rx] to discard the codec specific status from

Description

When sm_vmprx_status() has reported a status of kSMVMPrxStatusCodecSpecific the codec specific status must be read before further status updates can be reported. This function is used to discard such codec specific status reports when the application is not interested in them. As such, this function is the default call for handling such status reports.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_status_profile_specific

Prototype Definition

int sm_vmprx_status_profile_specific(struct sm_vmprx_status_profile_specific_parms *psp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_status_profile_specific_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT notification_code;				/* in */
	char *payload;						/* inout */
	tSM_INT max_length;					/* in */
	tSM_INT length;						/* out */
} SM_VMPRX_STATUS_PROFILE_SPECIFIC_PARMS;

Description

This call should be invoked following a status, kSMVMPRxStatusProfileSpecific, being obtained from sm_vmprx_status() . The profile specicic notification code obtained from that call should be supplied as the notification_code parameter. Additional profile specific information will be retrieved into the supplied buffer. See documentation supplied with ProsodyS profile specific plugin for further details.

Fields

vmprx: The VMP[rx] to query
notification_code: The notification code previously obtained from sm_vmprx_status()
payload: A pointer to a buffer to receive the payload related to profile specific state transition
max_length: The length of the buffer
length: The length of data written to the buffer

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_stop

Prototype Definition

int sm_vmprx_stop(struct sm_vmprx_stop_parms *stopp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_stop_parms {
	tSMVMPrxId vmprx;					/* in */
} SM_VMPRX_STOP_PARMS;

Description

Requests that a VMP[rx] stops executing. The user will be notified that a VMP[rx] has terminated by a final status, kSMVMPrxStatusStopped, from sm_vmprx_status(). Once the stopped status notification has been received the VMP[rx] can be destroyed using sm_vmprx_destroy().

Once the VMP[rx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_vmprx_destroy() is called.

Fields

vmprx: A tSMVMPrxId that has been previously created by a call to sm_vmprx_create().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config

Prototype Definition

int sm_vmptx_config(struct sm_vmptx_config_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_parms {
	tSMVMPtxId vmptx;					/* in */
	SOCKADDR_IN destination_rtp;				/* in */
	SOCKADDR_IN source_rtp;					/* in */
	int TOS_RTP;						/* in */
	SOCKADDR_IN destination_rtcp;				/* in */
	SOCKADDR_IN source_rtcp;				/* in */
	int TOS_RTCP;						/* in */
} SM_VMPTX_CONFIG_PARMS;

Description

Configures a VMP[tx] to send RTP and RTCP data to a device with the specified IP address and port numbers.

If the call completes successfully RTP data generated by the vmptx will be sent to the address and port as specified in destination_rtp. Any associated RTCP data will be delivered to the address and port specified by destination_rtcp. Specifying the source_rtp instructs the VMP[tx] to use the given IP address and port for outgoing RTP data. Specifying the source_rtcp instructs the VMP[tx] to use the given IP address and port for outgoing RTCP data.

This requires the module vmptx to have been downloaded.

Fields

vmptx: The VMP[tx] to configure
destination_rtp: The SOCKADDR_IN structure specifying the destination IP address and port for the RTP stream. A struct SOCKADDR_IN must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
source_rtp: The SOCKADDR_IN structure allows you to specify the source IP address and port for the RTP stream. A struct SOCKADDR_IN must be configured with an address family. The IP address may be specified, or the value INADDR_ANY may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
TOS_RTP: The Type Of Service (TOS) indicator to be sent with RTP data
destination_rtcp: The SOCKADDR_IN structure specifying the destination IP address and port for the RTCP stream. A struct SOCKADDR_IN must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network bytes order. The structure must be correctly cast such that an IP V4 address is specified.
source_rtcp: The SOCKADDR_IN structure allows you to specify the source IP address and port for the RTCP stream. A struct SOCKADDR_IN must be configured with an address family. The IP address may be specified, or the value INADDR_ANY may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network bytes order. The structure must be correctly cast such that an IP V4 address is specified.
TOS_RTCP: The Type Of Service (TOS) indicator to be sent with RTCP data

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_authentication_hmac_sha1

Prototype Definition

int sm_vmptx_config_authentication_hmac_sha1(struct sm_vmptx_config_authentication_hmac_sha1_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_authentication_hmac_sha1_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
	tSM_INT taglen;						/* in */
} SM_VMPTX_CONFIG_AUTHENTICATION_HMAC_SHA1_PARMS;

Description

Configures a VMP[tx] to use HMAC-SHA1 authentication, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmptx: The VMP[tx] to configure
keylen: The length of the authentication key in octets.
key: The authentication key.
taglen: The length of the authentication tag in bits.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_authentication_null

Prototype Definition

int sm_vmptx_config_authentication_null(struct sm_vmptx_config_authentication_null_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_authentication_null_parms {
	tSMVMPtxId vmptx;					/* in */
} SM_VMPTX_CONFIG_AUTHENTICATION_NULL_PARMS;

Description

Disables any authentication which may have been in use by a VMP[tx].

Fields

vmptx: The VMP[tx] to configure

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_alaw

Prototype Definition

int sm_vmptx_config_codec_alaw(struct sm_vmptx_codec_alaw_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_alaw_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode {
		kSMVMPTxVADModeDisabled,
		kSMVMPTxVADModeEnabled,
		kSMVMPTxVADModeComfortNoise,
	} VADMode;						/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_ALAW_PARMS;

Description

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrnb

Prototype Definition

int sm_vmptx_config_codec_amrnb(struct sm_vmptx_codec_amrnb_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_amrnb_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT aligned;					/* in */
	tSM_INT gsmefr;						/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_AMRNB_PARMS;

Description

Configures a VMP[tx] to use AMR narrow-band for encoding data, as defined in IETF RFC 3267.

This requires the module amr-nb to have been downloaded. Alternatively the module amr-nb-all can be used if amr-nb-prs functionality is also required.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

aligned

Packet alignment (bandwidth efficient mode). 0 if packet is not aligned, otherwise packet is aligned.

gsmefr

Configures the codec to perform GSM-EFR equivalent encoding. This will assume non-aligned packets and 12.2 kHz mode encoding.

The mode of operation for the voice activity detector. Note that for this codec kSMVMPTxVADModeEnabled and kSMVMPTxVADModeComfortNoise are equivalent, in that the codec will generate SID frames when the signal is not active. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The number of frames to send per packet. This value is normally one, which encodes 20 milliseconds per packet, but larger values can be used, reducing the packet overhead at the expense of extra delay.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrnb_cmr

Prototype Definition

int sm_vmptx_config_codec_amrnb_cmr(struct sm_vmptx_config_codec_amrnb_cmr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_amrnb_cmr_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT bitrate;					/* in */
} SM_VMPTX_CONFIG_CODEC_AMRNB_CMR_PARMS;

Description

Configures the AMR narrow-band codec to request the given mode.

Fields

vmptx: The VMP[tx] to which to add the codec
bitrate: The speed to request via the CMR field, in bits per second. It must be one of the speeds which the AMR narrow-band codec can encode (which are: 4750, 5150, 5900, 6700, 7400, 7950, 10200, and 12200), or 0 to request "any rate" (CMR = 15).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrnb_mode

Prototype Definition

int sm_vmptx_config_codec_amrnb_mode(struct sm_vmptx_config_codec_amrnb_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_amrnb_mode_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT bitrate;					/* in */
} SM_VMPTX_CONFIG_CODEC_AMRNB_MODE_PARMS;

Description

Configures the AMR narrow-band codec to use the given mode.

Fields

vmptx: The VMP[tx] to which to add the codec
bitrate: The speed to use in bits per second. It must be one of the speeds which the AMR codec can encode, which are: 4750, 5150, 5900, 6700, 7400, 7950, 10200, and 12200.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrwb

Prototype Definition

int sm_vmptx_config_codec_amrwb(struct sm_vmptx_codec_amrwb_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_amrwb_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT aligned;					/* in */
	tSM_INT VADMode;					/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_AMRWB_PARMS;

Description

Configures a VMP[tx] to use AMR wide-band for encoding data, as defined in IETF RFC 3267.

This requires the module amr-wb to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
aligned: Packet alignment (bandwidth efficient mode). 0 if packet is not aligned, otherwise packet is aligned.
VADMode: The mode of operation for the voice activity detector (i.e. discontinuous transmission, or DTX). 0 to disable DTX, otherwise enabled.
frames_per_packet: The number of frames to send per packet. This value is normally one, which encodes 20 milliseconds per packet, but larger values could be used, to reduce the packet overhead at the expense of extra delay. This field is currently ignored. Packets are always transmitted with one frame per packet.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrwb_cmr

Prototype Definition

int sm_vmptx_config_codec_amrwb_cmr(struct sm_vmptx_config_codec_amrwb_cmr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_amrwb_cmr_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT bitrate;					/* in */
} SM_VMPTX_CONFIG_CODEC_AMRWB_CMR_PARMS;

Description

Configures the AMR wide-band codec to request the given mode.

Fields

vmptx: The VMP[tx] to which to add the codec
bitrate: The speed to request via the CMR field, in bits per second. It must be one of the speeds which the AMR wide-band codec can encode (which are: 6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, and 23850), or 0 to request "any rate" (CMR = 15).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_amrwb_mode

Prototype Definition

int sm_vmptx_config_codec_amrwb_mode(struct sm_vmptx_config_codec_amrwb_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_amrwb_mode_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT bitrate;					/* in */
} SM_VMPTX_CONFIG_CODEC_AMRWB_MODE_PARMS;

Description

Configures the AMR wide-band codec to use the given mode.

Fields

vmptx: The VMP[tx] to which to add the codec
bitrate: The speed to use in bits per second. It must be one of the speeds which the AMR wideband codec can encode, which are: 6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, and 23850.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_comfort_noise

Prototype Definition

int sm_vmptx_config_codec_comfort_noise(struct sm_vmptx_codec_comfort_noise_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_comfort_noise_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPTX_CODEC_COMFORT_NOISE_PARMS;

Description

Configures the comfort noise codec. This codec is only used if the main codec for the VMP[tx] has been set to use RFC 3389 comfort noise. For example, the A-law codec is configured to use comfort noise with sm_vmptx_config_codec_alaw(), by specifying a VADmode of kSMVMPTxVADModeComfortNoise.

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_evrc

Prototype Definition

int sm_vmptx_config_codec_evrc(struct sm_vmptx_codec_evrc_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_evrc_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT high_pass_filter;				/* in */
	tSM_INT noise_suppression_filter;			/* in */
	enum kSMEVRCRTPMode rtp_mode;				/* in */
	enum kSMEVRCRate {
		kSMEVRCRateEighth,
		kSMEVRCRateHalf,
		kSMEVRCRateFull,
	} max_rate;						/* in */
	enum kSMEVRCRate min_rate;				/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_EVRC_PARMS;

Description

Configures a VMP[tx] to use the Enhanced Variable Rate Codec (EVRC) for encoding data.

This requires the module evrc to have been downloaded.

Fields

The VMP[tx] to which to add this codec

noise_suppression_filter

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

high_pass_filter

Selects whether or not a high-pass filter is used on the data to be encoded. The filter is used if this value is non-zero.

Selects whether or not a noise suppression filter is used on the data to be encoded. The filter is used if this value is non-zero.

rtp_mode

Selects the RTP format for this codec. There are two commonly-used specifications for how to pack the the encoded data into an RTP packet. One of these values:

kSMEVRCRTPModeHeaderless: Encodes the bitstream as raw encoded bytes, with no headers. This requires that there is only one frame per packet.
kSMEVRCRTPModeRFC2658: Encodes the bitstream as specified in IETF RFC 2658. The header is one byte. This specification only allows for one frame per packet.
kSMEVRCRTPModeRFC3558: Encodes the bitstream as specified in IETF RFC 3558. The header is two bytes, plus one byte for every two frames in the packet.

max_rate

The maximum encoding rate to use. All frames are guaranteed to be this size or smaller. One of these values:

kSMEVRCRateEighth: Eighth rate: 16 bits per frame. This rate is only used for comfort noise frames.
kSMEVRCRateHalf: Half rate: 80 bits per frame.
kSMEVRCRateFull: Full rate: 171 bits per frame.

min_rate

The minimum encoding rate to use. All frames are guaranteed to be at least this size, or be elided if VAD is enabled. One of these values:

kSMEVRCRateEighth: Eighth rate: 16 bits per frame. This rate is only used for comfort noise frames.
kSMEVRCRateHalf: Half rate: 80 bits per frame.
kSMEVRCRateFull: Full rate: 171 bits per frame.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g722

Prototype Definition

int sm_vmptx_config_codec_g722(struct sm_vmptx_codec_g722_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g722_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT packetlen;					/* in */
} SM_VMPTX_CODEC_G722_PARMS;

Description

Configures a VMP[tx] to use G.722 for encoding wideband data.

This requires the module g722 to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
packetlen: The number of samples of data to encode and send in each RTP packet. This should be a multiple of 160 (i.e. a multiple of 10 mS).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g722_1

Prototype Definition

int sm_vmptx_config_codec_g722_1(struct sm_vmptx_codec_g722_1_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g722_1_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT bitrate;					/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_G722_1_PARMS;

Description

Configures a VMP[tx] to use G.722.1, licensed from Polycom®, wideband codec for encoding data, as defined in IETF RFC 3047.

This requires the module g722-1 to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
bitrate: Bitrate of the encoded data. Must be 24000 or 32000 (the ultrawideband bit rates specified in G.722.1 Annex C are not supported).
frames_per_packet: The number of frames to send per packet. This value is normally one, which encodes 20 milliseconds per packet, but larger values could be used, to reduce the packet overhead at the expense of extra delay.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g723_1

Prototype Definition

int sm_vmptx_config_codec_g723_1(struct sm_vmptx_codec_g723_1_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g723_1_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT high_pass_filter;				/* in */
	tSM_INT rate;						/* in */
	tSM_INT silence_compression;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_G723_1_PARMS;

Description

Configures a VMP[tx] to use G.723.1 for encoding data.

This requires the module g7231a to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
high_pass_filter: Selects whether or not a high-pass filter is used on the data to be encoded. A filter is used if this value is non-zero.
rate: The encoding rate to use, in bits per second. G.723.1 supports two rates: 6300 and 5300.
silence_compression: Selects whether or not Annex A silence compression is to be used. It is used if this value is non-zero.
frames_per_packet: The number of frames to send per packet. This value is normally one, which encodes 30 milliseconds per packet, but larger values can be used, reducing the packet overhead at the expense of extra delay.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g726

Prototype Definition

int sm_vmptx_config_codec_g726(struct sm_vmptx_codec_g726_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g726_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT bits;						/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT packetlen;					/* in */
	enum kSMG726Variant variant;				/* in */
} SM_VMPTX_CODEC_G726_PARMS;

Description

Configures a VMP[tx] to use G.726 for encoding data.

This requires the module g726 to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

bits

The bit rate at which the codec runs, specified as the number of bits per sample. This must be 2, 3, 4, or 5.

The mode of operation for the voice activity detector. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

packetlen

The number of samples of data to encode and send in each RTP packet. This should be a multiple of 80 (i.e. a multiple of 10 mS).

The sample packing variant to use One of these values:

kSMG726VariantRFC3551: Use the packing mode described in RFC 3551
kSMG726VariantAAL2: Use the packing mode used by AAL2 (ITU-T I.366.2)

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g728

Prototype Definition

int sm_vmptx_config_codec_g728(struct sm_vmptx_codec_g728_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g728_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT rate;						/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_G728_PARMS;

Description

Configures a VMP[tx] to use G.728 for encoding data.

This requires the module g728 to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

rate

The encoding rate to use, in bits per second. G.728 supports three rates: 9600, 12800 and 16000.

The mode of operation for the voice activity detector. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g729ab

Prototype Definition

int sm_vmptx_config_codec_g729ab(struct sm_vmptx_codec_g729ab_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g729ab_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_G729AB_PARMS;

Description

This requires the module g729ab to have been downloaded.

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector. The codec will generate only 'A' frames if the mode is kSMVMPTxVADModeDisabled, otherwise both 'A' and 'B' frames may be produced. The codec does not perform DTX. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_g729i

Prototype Definition

int sm_vmptx_config_codec_g729i(struct sm_vmptx_codec_g729i_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_g729i_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMG729IMode g729_mode;				/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_G729I_PARMS;

Description

This requires the module g729i to have been downloaded.

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

g729_mode

Sets the data rate according to G.729 Annex D, to the basic G.729 standard, or to G.729 Annex E, respectively. The payload type should be chosen to match this value. One of these values:

kSMG729IModeG729D: G.729 Annex D
kSMG729IModeG729: G.729 standard
kSMG729IModeG729E: G.729 Annex E

The mode of operation for the voice activity detector. (This is not currently implemented, so the codec will encode all data supplied to it). One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_gsmefr

Prototype Definition

int sm_vmptx_config_codec_gsmefr(struct sm_vmptx_codec_gsmefr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_gsmefr_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_GSMEFR_PARMS;

Description

Configures a VMP[tx] to use GSM-EFR for encoding data.

Note that this function is for use with the lightweight gsm-efr module only. Where full AMR-NB support is also required, please use sm_vmptx_config_codec_amrnb() with parameter gsmefr=1 and the module amr-nb or amr-nb-all instead.

This requires the module gsm-efr to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_gsmfr

Prototype Definition

int sm_vmptx_config_codec_gsmfr(struct sm_vmptx_codec_gsmfr_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_gsmfr_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMGSMVariant {
		kSMGSMVariantStandard,
		kSMGSMVariantMS,
	} variant;						/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_GSMFR_PARMS;

Description

Configures a VMP[tx] to use GSM full-rate for encoding data.

This requires the module gsm-fr to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

One of these values:

kSMGSMVariantStandard: Use the standard GSM 06.10 codec.
kSMGSMVariantMS: Encode packets using the alternate MS-GSM encoding scheme. The GSM 06.10 codec itself is identical, however the bitstream is packed with two frames in 65 bytes instead of one frame in 33 bytes. If this variant is used then frames_per_packet must be a multiple of 2.

The mode of operation for the voice activity detector. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_ilbc

Prototype Definition

int sm_vmptx_config_codec_ilbc(struct sm_vmptx_codec_ilbc_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_ilbc_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT frame_len;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_ILBC_PARMS;

Description

Configures a VMP[tx] to use iLBC for encoding data.

This requires the module ilbc to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

frame_len

The number of milliseconds of audio to encode in each frame. This must be either 20 or 30. This value multiplied by frames_per_packet gives the total length of each packet.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The number of frames to send per packet. This value is normally one but larger values can be used, reducing the packet overhead at the expense of extra delay. This value multiplied by frame_len gives the total length of each packet.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_isac

Prototype Definition

int sm_vmptx_config_codec_isac(struct sm_vmptx_codec_isac_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_isac_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSMVMPrxId partner;					/* in */
	tSM_INT channel_associated_mode;			/* in */
} SM_VMPTX_CODEC_ISAC_PARMS;

Description

Configures a VMP[tx] to use the iSAC codec for encoding data.

An iSAC codec can automatically adapt its transmitter to network conditions using information derived from the corresponding receiver. When partner is set to a VMP[rx] already configured for the iSAC codec and channel_associated_mode is non zero this transmitter will be automatically adjusted based on the data seen by that receiver. Otherwise, sm_vmptx_config_isac_rate() is used to configure the rate.

The partner field may be kSMNullVMPrxId. However, channel counts may be improved by partnering.

This requires the module isac to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
partner: The VMP[rx] which is already running the iSAC codec
channel_associated_mode: Sets whether the transmitter automatically adjusts to network conditions based on the data seen by the partner receiver.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_l16

Prototype Definition

int sm_vmptx_config_codec_l16(struct sm_vmptx_codec_l16_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_l16_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_L16_PARMS;

Description

The L16 encoding is as described in IETF RFC 3551 section 4.5.11

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_l8

Prototype Definition

int sm_vmptx_config_codec_l8(struct sm_vmptx_codec_l8_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_l8_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_L8_PARMS;

Description

The L8 encoding is as described in IETF RFC 3551 section 4.5.10

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_melpe

Prototype Definition

int sm_vmptx_config_codec_melpe(struct sm_vmptx_codec_melpe_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_melpe_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_MELPE_PARMS;

Description

This requires the module melpe to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
ptime: The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_mulaw

Prototype Definition

int sm_vmptx_config_codec_mulaw(struct sm_vmptx_codec_mulaw_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_mulaw_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_CODEC_MULAW_PARMS;

Description

Fields

The VMP[tx] to which to add the codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The length of the RTP media, in milliseconds, to send in each packet. It is usually desirable to send 20 ms packets. Applications should specify ptime as a multiple of 10 ms.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_opus

Prototype Definition

int sm_vmptx_config_codec_opus(struct sm_vmptx_codec_opus_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_opus_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT sample_rate;					/* in */
	tSM_INT bit_rate;					/* in */
	tSM_INT ptime;						/* in */
	tSM_INT packet_loss;					/* in */
	tSM_INT complexity;					/* in */
	tSM_INT use_fec;					/* in */
	tSM_INT use_dtx;					/* in */
	enum kSMOPUSRate {
		kSMOPUSRateConstrainedVariable,
		kSMOPUSRateUnconstrainedVariable,
		kSMOPUSRateConstant,
	} rate_control;						/* in */
	enum kSMOPUSSignalTypeHint {
		kSMOPUSSignalTypeHintNone,
		kSMOPUSSignalTypeHintVoice,
		kSMOPUSSignalTypeHintMusic,
	} signal_type_hint;					/* in */
	enum kSMOPUSAppType {
		kSMOPUSAppTypeVoIP,
		kSMOPUSAppTypeAudio,
		kSMOPUSAppTypeLowDelay,
	} application_type;					/* in */
	tSM_INT disable_prediction;				/* in */
} SM_VMPTX_CODEC_OPUS_PARMS;

Description

Configures a VMP[tx] to use Opus codec as defined in IETF RFC 6716.

Fields

The VMP[tx] to which to add this codec.

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

sample_rate

Sample rate of the audio being encoded. In the current release, this should be either 8000 (narrowband) or 16000 (wideband).

bit_rate

The target bit rate which the codec should aim to produce. A value of zero indicates automatic rate selection. A negative value indicates maximum possible rate should be used. Otherwise a value in range 500 to 512000 should be specified. For most applications automatic rate selection would be used unless peer indicates otherwise.

The duration in milliseconds of audio conveyed in each frame. This should be set to a value of 10, 20, 40, or 60. Normally should be set to 20.

packet_loss

An estimate of the current level of packet loss to which the encoded data will be subjected, as a percentage. Normally set to zero.

complexity

The complexity of the algorithms used to encode the data: 0..10 This controls the trade-off between channel count and audio quality. 0 will give the biggest channel count; 10 will give best quality.

use_fec

Set to any non-zero value to include data for "forward error correction" (FEC) in the transmitted stream. Only recommended if really needed, as it reduces quality unless there is significant packet loss.

use_dtx

Set to any non-zero value to suppress transmission of data during silence. Not recommended unless average bit rate is absolutely critical.

rate_control

Control variation of encoded bit rate. One of these values:

kSMOPUSRateConstrainedVariable: Constrained variable rate.
kSMOPUSRateUnconstrainedVariable: Unconstrained variable rate.
kSMOPUSRateConstant: Constant bit rate.

signal_type_hint

Provides hint about nature of signal being encoded. One of these values:

kSMOPUSSignalTypeHintNone: Nature of signal not known.
kSMOPUSSignalTypeHintVoice: Signal to be encoded is voice.
kSMOPUSSignalTypeHintMusic: Signal to be encoded is music.

application_type

Provides hint about application type. One of these values:

kSMOPUSAppTypeVoIP: Process signal for improved speech intelligibility.
kSMOPUSAppTypeAudio: Favour faithfulness to the original input..
kSMOPUSAppTypeLowDelay: Configure the minimum possible coding delay by disabling certain modes of operation.

disable_prediction

Set to zero for default behaviour, set to 1 to disable almost all use of prediction, making frames almost completely independent.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_opus_mode

Prototype Definition

int sm_vmptx_config_codec_opus_mode(struct sm_vmptx_config_codec_opus_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_opus_mode_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT sample_rate;					/* in */
	tSM_INT bit_rate;					/* in */
	tSM_INT ptime;						/* in */
	tSM_INT packet_loss;					/* in */
	tSM_INT complexity;					/* in */
	tSM_INT use_fec;					/* in */
	tSM_INT use_dtx;					/* in */
	enum kSMOPUSRate rate_control;				/* in */
	enum kSMOPUSSignalTypeHint signal_type_hint;		/* in */
	enum kSMOPUSAppType application_type;			/* in */
	tSM_INT disable_prediction;				/* in */
} SM_VMPTX_CONFIG_CODEC_OPUS_MODE_PARMS;

Description

Modifies the configuration of the Opus codec.

Fields

The VMP[tx] for which to change the codec parameters.

sample_rate

Sample rate of the audio being encoded. This must be the same as that previously specified when sm_vmptx_config_codec_opus() was called to configure the VMP[tx].

bit_rate

The duration in milliseconds of audio conveyed in each frame. This should be set to a value of 10, 20, 40, or 60. Normally should be set to 20.

packet_loss

An estimate of the current level of packet loss to which the encoded data will be subjected, as a percentage. Normally set to zero.

complexity

The complexity of the algorithms used to encode the data: 0..10 This controls the trade-off between channel count and audio quality. 0 will give the biggest channel count; 10 will give best quality.

use_fec

use_dtx

Set to any non-zero value to suppress transmission of data during silence. Not recommended unless average bit rate is absolutely critical.

rate_control

Control variation of encoded bit rate. One of these values:

kSMOPUSRateConstrainedVariable: Constrained variable rate.
kSMOPUSRateUnconstrainedVariable: Unconstrained variable rate.
kSMOPUSRateConstant: Constant bit rate.

signal_type_hint

Provides hint about nature of signal being encoded. One of these values:

kSMOPUSSignalTypeHintNone: Nature of signal not known.
kSMOPUSSignalTypeHintVoice: Signal to be encoded is voice.
kSMOPUSSignalTypeHintMusic: Signal to be encoded is music.

application_type

Provides hint about application type. One of these values:

kSMOPUSAppTypeVoIP: Process signal for improved speech intelligibility.
kSMOPUSAppTypeAudio: Favour faithfulness to the original input..
kSMOPUSAppTypeLowDelay: Configure the minimum possible coding delay by disabling certain modes of operation.

disable_prediction

Set to zero for default behaviour, set to 1 to disable almost all use of prediction, making frames almost completely independent.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_rfc2833

Prototype Definition

int sm_vmptx_config_codec_rfc2833(struct sm_vmptx_codec_rfc2833_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_rfc2833_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPTX_CODEC_RFC2833_PARMS;

Description

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_rfc4040

Prototype Definition

int sm_vmptx_config_codec_rfc4040(struct sm_vmptx_codec_rfc4040_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_rfc4040_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT packetlen;					/* in */
} SM_VMPTX_CODEC_RFC4040_PARMS;

Description

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
packetlen: The number of octets of data to encode and send in each RTP packet.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_rttext

Prototype Definition

int sm_vmptx_config_codec_rttext(struct sm_vmptx_codec_rttext_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_rttext_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT redundant_payload_type;				/* in */
	tSM_INT redundancy_level;				/* in */
	tSM_INT buffer_time;					/* in */
	tSM_INT idle_time;					/* in */
} SM_VMPTX_CODEC_RTTEXT_PARMS;

Description

Configures a VMP[tx] to be able to send real-time text.

The packet format is described in IETF RFC 4103.

A VMP[tx] that is configured to use this codec will expect to be provided with octet data rather than audio. As such it will normally be connected to a channel configured for data communitcations with the raw protocol and no encoding. The data written to the channel must be 32 bit values, presented as 4 octets with the least significant octet first. The values should correspond to UCS4 characters.

The firmware does not attempt to ensure that composite character sequences are sent in the same packet. However, there is usually only a small number of characters in each call to smdc_tx_data() and these blocks are normally sent in a single packet.

This requires the module rttext to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
redundant_payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13) for redundant data packets. Supplying a value of -1 will prevent redundancy being used.
redundancy_level: The number of redundant payloads per packet. If zero is specified, the default of 2 is used. To disable redundancy, set redundant_payload_type to -1.
buffer_time: The time in milliseconds that text may be buffered for before being transmitted.
idle_time: The time in milliseconds before an empty block is sent.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_silk

Prototype Definition

int sm_vmptx_config_codec_silk(struct sm_vmptx_codec_silk_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_silk_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT sample_rate;					/* in */
	tSM_INT internal_rate;					/* in */
	tSM_INT bit_rate;					/* in */
	tSM_INT frames_per_packet;				/* in */
	tSM_INT packet_loss;					/* in */
	tSM_INT complexity;					/* in */
	tSM_INT use_fec;					/* in */
	tSM_INT use_dtx;					/* in */
} SM_VMPTX_CODEC_SILK_PARMS;

Description

Configures a VMP[tx] to use the SILK codec from Skype.

This requires the module silk to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec.
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
sample_rate: Sample rate of the audio being encoded. In the current release, this should be either 8000 (narrowband) or 16000 (wideband).
internal_rate: Maximum sample rate used internally by the codec. Must be no greater than sample_rate and must also be equal to one of the standard SILK internal sample rate values, i.e. 8000, 12000, 16000, or 24000.
bit_rate: The target bit rate which the codec should aim to produce. This value must be between 5000 and 100000. Recommended values are between 5000 and 20000 for 8kHz-sampled (narrowband) signals, and between 8000 and 30000 for 16kHz (wideband) sampling.
frames_per_packet: The number of frames to send per packet. This value is normally one, which encodes 20 milliseconds per packet, but larger values could be used, to reduce the packet overhead at the expense of extra delay.
packet_loss: An estimate of the current level of packet loss to which the encoded data will be subjected, as a percentage. Normally set to zero.
complexity: The complexity of the algorithms used to encode the data: 0, 1, or 2. This controls the trade-off between channel count and audio quality. 0 will give the biggest channel count; 2 will give best quality.
use_fec: Set to any non-zero value to include data for "forward error correction" (FEC) in the transmitted stream. Only recommended if really needed, as it reduces quality unless there is significant packet loss.
use_dtx: Set to any non-zero value to suppress transmission of data during silence. Not recommended unless average bit rate is absolutely critical.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_silk_mode

Prototype Definition

int sm_vmptx_config_codec_silk_mode(struct sm_vmptx_config_codec_silk_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_codec_silk_mode_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT sample_rate;					/* in */
	tSM_INT internal_rate;					/* in */
	tSM_INT bit_rate;					/* in */
	tSM_INT frames_per_packet;				/* in */
	tSM_INT packet_loss;					/* in */
	tSM_INT complexity;					/* in */
	tSM_INT use_fec;					/* in */
	tSM_INT use_dtx;					/* in */
} SM_VMPTX_CONFIG_CODEC_SILK_MODE_PARMS;

Description

Modifies the configuration of the SILK codec.

Fields

vmptx: The VMP[tx] for which to change the codec parameters.
sample_rate: Sample rate of the audio being encoded. This must be the same as that previously specified when sm_vmptx_config_codec_silk() was called to configure the VMP[tx].
internal_rate: Maximum sample rate used internally by the codec. See sm_vmptx_config_codec_silk() for more details.
bit_rate: The target bit rate. See sm_vmptx_config_codec_silk() for more details.
frames_per_packet: The number of frames to send per packet. See sm_vmptx_config_codec_silk() for more details.
packet_loss: An estimate of the current level of packet loss. See sm_vmptx_config_codec_silk() for more details.
complexity: The complexity of the algorithms used. See sm_vmptx_config_codec_silk() for more details.
use_fec: Non-zero to include data for "forward error correction" (FEC). See sm_vmptx_config_codec_silk() for more details.
use_dtx: Non-zero to suppress transmission of data during silence. See sm_vmptx_config_codec_silk() for more details.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_smv

Prototype Definition

int sm_vmptx_config_codec_smv(struct sm_vmptx_codec_smv_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_smv_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_SMV_PARMS;

Description

Configures a VMP[tx] to use SMV for encoding data.

This requires the module smv to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

The mode of operation for the voice activity detector One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_speex

Prototype Definition

int sm_vmptx_config_codec_speex(struct sm_vmptx_codec_speex_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_speex_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMSpeexMode bandwidth;				/* in */
	enum kSMVMPTxVADMode VADMode;				/* in */
	tSM_INT frames_per_packet;				/* in */
} SM_VMPTX_CODEC_SPEEX_PARMS;

Description

Configures a VMP[tx] to use Speex for encoding data, as defined in IETF RFC 5574. However, neither variable bit-rate coding (VBR) nor discontinuous transmission (DTX) are supported.

This requires the module speex_vmp to have been downloaded.

Fields

The VMP[tx] to which to add this codec

The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

bandwidth

Ignored. kSMSpeexNarrowbandMode is always used since it is the only value supported by current firmware. One of these values:

kSMSpeexNarrowbandMode: Narrowband (8 kHz sampling rate) mode
kSMSpeexWidebandMode: Wideband (16 kHz sampling rate) mode
kSMSpeexUltrawidebandMode: Ultrawideband (32 kHz sampling rate) mode

Currently ignored. Neither VAD nor CNG processing is implemented. One of these values:

kSMVMPTxVADModeDisabled: Disable VAD - all data delivered to the VMP[tx] is encoded and sent
kSMVMPTxVADModeEnabled: Enable VAD - if the signal is inactive, no data is sent (DTX)
kSMVMPTxVADModeComfortNoise: Enable VAD with comfort noise generation - if the signal is inactive, comfort noise packets are sent. If the main codec does not define its own comfort noise, it must have been configured by sm_vmptx_config_codec_comfort_noise().

The number of frames to send per packet. This value is normally one, which encodes 20 milliseconds per packet, but larger values could be used, to reduce the packet overhead at the expense of extra delay. This field is currently ignored. Packets are always transmitted with one 20ms frame per packet.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_speex_mode

Prototype Definition

int sm_vmptx_config_codec_speex_mode(struct sm_vmptx_codec_speex_mode_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_speex_mode_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_UT32 complexity;					/* in */
	tSM_UT32 quality;					/* in */
	tSM_UT32 bitrate;					/* in */
	tSM_UT32 denoiser;					/* in */
} SM_VMPTX_CODEC_SPEEX_MODE_PARMS;

Description

Configures a VMP[tx] to use Speex for encoding data, as defined in IETF RFC 5574.

This function requires the module speex_vmp to have been downloaded, and must be called to make the codec operational. It must be called once, and only once, after each call to sm_vmptx_config_codec_speex.

Fields

vmptx: The VMP[tx] to which to add this codec
complexity: This determines the amount of processor time available to the encoding process. Higher complexity gives a better trade-off between quality and bitrate, especially for non-speech sounds (e.g. music), but it will give a lower channel count. A range of values from 0 to 10 may be used. The recommended range is from 2 to 4.
quality: This affects the quality of the encoded speech. A value between 0 and 10 may be used. The default is 8. There is a trade-off between complexity, quality, bitrate, and achievable channel count. This value may be overridden by the bitrate parameter, below.
bitrate: This specifies the encoded data rate in bits per second. The actual bitrate used will be one of: 2150, 3950, 5950, 8000, 11000, 15000, 18200, and 24600 bits per second. Only a few quality settings are compatible with each bitrate. In this API call, bitrate takes precedence over quality.
denoiser: Disable (0) or enable (any non-zero value, e.g. 1) pre-processing to reduce the audibility of background noise. Use of the denoiser will severely reduce the channel count. This field is currently ignored: the denoiser is not implemented because of its impact on channel count.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_sse

Prototype Definition

int sm_vmptx_config_codec_sse(struct sm_vmptx_codec_sse_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_sse_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT retransmissions;				/* in */
	tSM_INT delay;						/* in */
} SM_VMPTX_CODEC_SSE_PARMS;

Description

Configures a VMP[tx] to be able to send SSE messages

This requires the module sse to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add this codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.
retransmissions: The number of retransmissions
delay: The time in milliseconds between retransmissions

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec_tetra

Prototype Definition

int sm_vmptx_config_codec_tetra(struct sm_vmptx_codec_tetra_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_codec_tetra_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
} SM_VMPTX_CODEC_TETRA_PARMS;

Description

There is not currently a standard packet encoding for wrapping TETRA-encoded speech into RTP. This implementation creates RTP frames that have standard RTP header followed by: ETSI two octet Payload header (with bits for framing rate, frame number, information element control, traffic type, contents control and payload) - the payload header follows the format described in ETSI TS 100 392-3-8 V0.0.8 section 5.2.1 TETRA ISI payload encoding. Two 18 octet tetra frames - each frame consisting of BFI bit followed by 137 bits of tetra encoded data (holding 30ms of encoded audio data according to traffic type 0 followed by 6 padding bits) - thus this pair of frames conveys 60ms of audio.

The tetra encoded data in the 18 octet tetra frames is always traffic type 0 - ACELP (ETS 300 395-2, 4.2.2.7) following MSB-LSB bit order.

This requires the module tetra to have been downloaded.

Fields

vmptx: The VMP[tx] to which to add the codec
payload_type: The payload type identifer to use with this codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the codec preventing its use.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_encryption_aes_cm

Prototype Definition

int sm_vmptx_config_encryption_aes_cm(struct sm_vmptx_config_encryption_aes_cm_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_encryption_aes_cm_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
} SM_VMPTX_CONFIG_ENCRYPTION_AES_CM_PARMS;

Description

Configures a VMP[tx] to use AES-CM encryption, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmptx: The VMP[tx] to configure
keylen: The length of the encryption key in octets.
key: The encryption key.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_encryption_aes_f8

Prototype Definition

int sm_vmptx_config_encryption_aes_f8(struct sm_vmptx_config_encryption_aes_f8_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_encryption_aes_f8_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT keylen;						/* in */
	char *key;						/* in */
} SM_VMPTX_CONFIG_ENCRYPTION_AES_F8_PARMS;

Description

Configures a VMP[tx] to use AES-f8 encryption, as defined in IETF RFC 3711.

This requires the module securertp to have been downloaded.

Fields

vmptx: The VMP[tx] to configure
keylen: The length of the encryption key in octets.
key: The encryption key.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_encryption_null

Prototype Definition

int sm_vmptx_config_encryption_null(struct sm_vmptx_config_encryption_null_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_encryption_null_parms {
	tSMVMPtxId vmptx;					/* in */
} SM_VMPTX_CONFIG_ENCRYPTION_NULL_PARMS;

Description

Disables any encryption which may have been in use by a VMP[tx].

Fields

vmptx: The VMP[tx] to configure

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_ipv6

Prototype Definition

int sm_vmptx_config_ipv6(struct sm_vmptx_config_ipv6_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_ipv6_parms {
	tSMVMPtxId vmptx;					/* in */
	SOCKADDR_IN6 destination_rtp;				/* in */
	SOCKADDR_IN6 source_rtp;				/* in */
	SOCKADDR_IN6 destination_rtcp;				/* in */
	SOCKADDR_IN6 source_rtcp;				/* in */
} SM_VMPTX_CONFIG_IPV6_PARMS;

Description

Configures a VMP[tx] to send RTP and RTCP data to a device with the specified IPv6 address and port numbers.

If the call completes successfully RTP data generated by the vmptx will be sent to the address and port as specified in destination_rtp. Any associated RTCP data will be delivered to the address and port specified by destination_rtcp. Specifying the source_rtp instructs the VMP[tx] to use the given IPv6 address and port for outgoing RTP data. Specifying the source_rtcp instructs the VMP[tx] to use the given IPv6 address and port for outgoing RTCP data.

This requires the module vmptx to have been downloaded.

Fields

vmptx: The VMP[tx] to configure
destination_rtp: The SOCKADDR_IN6 structure specifying the destination IP address and port for the RTP stream. A struct SOCKADDR_IN6 must be configured with an address family, an IPv6 address and a port. Note that most operating systems define this structure such that fields are in network byte order.
source_rtp: The SOCKADDR_IN6 structure allows you to specify the source IP address and port for the RTP stream. A struct SOCKADDR_IN6 must be configured with an address family. The IP address may be specified, or a value equivalent to in6addr_any may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order.
destination_rtcp: The SOCKADDR_IN6 structure specifying the destination IP address and port for the RTCP stream. A struct SOCKADDR_IN6 must be configured with an address family, an IPv6 address and a port. Note that most operating systems define this structure such that fields are in network bytes order.
source_rtcp: The SOCKADDR_IN6 structure allows you to specify the source IP address and port for the RTCP stream. A struct SOCKADDR_IN6 must be configured with an address family. The IP address may be specified, or a value equivalent to in6addr_any may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network bytes order.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_isac_rate

Prototype Definition

int sm_vmptx_config_isac_rate(struct sm_vmptx_isac_rate_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_isac_rate_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT rate;						/* in */
	tSM_INT ptime;						/* in */
} SM_VMPTX_ISAC_RATE_PARMS;

Description

Configures a VMP[tx] which is running the iSAC codec to generate output data at an explict rate. The data rate of an iSAC codec can be explicitly configured or it can automatically adapt its transmitter to network conditions using information derived from the corresponding receiver.

Note that if a transmitter is already running and automatically adapting using a corresponding receiver, the rate configured with this function is ignored.

Fields

vmptx: The VMP[tx] which is running the iSAC codec
rate: The short-term average bit rate in bits per second.
ptime: The length of the RTP media, in milliseconds, to send in each packet. Applications should specify ptime as 30, or 60.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_profile_specific

Prototype Definition

int sm_vmptx_config_profile_specific(struct sm_vmptx_config_profile_specific_parms *psp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_config_profile_specific_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT enable;						/* in */
	char *plugin;						/* in */
	tSM_INT paramlen;					/* in */
	char *paramval;						/* in */
} SM_VMPTX_CONFIG_PROFILE_SPECIFIC_PARMS;

Description

Normally a VMP [tx] generates standard RTP packets. Use of profile specific RTP extensions (such as use of RTP extension header) can be set up to be performed by a specified ProsodyS plugin through invoking this call. Once use of plugin with this VMP [tx] has been set up, some plugin specific control over generated RTP can occur through invoking sm_vmptx_set_profile_specific() . See documentation supplied with ProsodyS profile specific plugin for further details.

Fields

vmptx: The VMP[tx] to configure
enable: Set non-zero to enable profile specific RTP processing.
plugin: Set to a zero terminated string identifying plugin that should perform profile specific processing.
paramlen: The length of the plugin specific parameter string in octets.
paramval: The plugin specific parameter string contents.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_sample_rate

Prototype Definition

int sm_vmptx_config_sample_rate(struct sm_vmptx_sample_rate_parms *sample_ratep)

Parameters

*sample_ratep

a structure of the following type:

typedef struct sm_vmptx_sample_rate_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_UT32 sample_rate;					/* in */
} SM_VMPTX_SAMPLE_RATE_PARMS;

Description

Allows an application to confgure the sample rate for input to a VMP[tx]. If no rate is configured, it defaults to 8000 samples per second. Some codecs (for example, PCMA - the G.711 A-law codec) can run at any sampling rate, other codecs are designed to run only at specific sampling rates. While the VMP[tx] will attempt to run the codec at the specified rate, running a codec at a non-standard sampling rate may result in unsatisfactory performance.

Note that any data supplied to the VMP[tx] at the wrong sampling rate will be ignored. This allows the sampling rate to be changed without encoding a burst of data at the wrong rate.

Fields

vmptx: The VMP[tx] to be configured
sample_rate: The sample rate in samples per second. The default is 8000.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_tag

Prototype Definition

int sm_vmptx_config_tag(struct sm_vmptx_tag_parms *tagp)

Parameters

*tagp

a structure of the following type:

typedef struct sm_vmptx_tag_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMVMPTxTagType {
		kSMVMPTxTagTypeUlaw,
		kSMVMPTxTagTypeAlaw,
	} tag_type;						/* in */
	tSM_UT32 min_time;					/* in */
	tSM_UT32 max_time;					/* in */
} SM_VMPTX_TAG_PARMS;

Description

Fields

The VMP[tx] to be configured

The payload type of the packets to be tagged.

tag_type

One of these values:

kSMVMPTxTagTypeUlaw: The tag is in G.711 U-law.
kSMVMPTxTagTypeAlaw: The tag is in G.711 A-law.

min_time

The minimum time between tags in milliseconds.

max_time

The maximum time between tags in milliseconds.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_tones

Prototype Definition

int sm_vmptx_config_tones(struct sm_vmptx_tone_parms *tonep)

Parameters

a structure of the following type:

typedef struct sm_vmptx_tone_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT convert_tones;					/* in */
	tSM_INT elim_tones;					/* in */
	tSMVMPTxToneSetId tone_set_id;				/* in */
	enum kSMVMPtxRFC2833MinDuration {
		kSMVMPtxRFC2833MinDurationNoMinimum,
		kSMVMPtxRFC2833MinDuration40,
	} min_duration;						/* in */
} SM_VMPTX_TONE_PARMS;

Description

Allows an application to specify how DTMF tones in the audio stream are handled when transmitting RTP data.

It may be desirable to encode tones as per RFC 2833, rather than using the chosen audio codec. Some codecs, such as G.711, can represent DTMF tones and do not require an alternative encoding, however, applications may still choose to send tones as RFC 2833. For audio codecs that cannot adequately represent DTMF tones (e.g. G.729) it is necessary to send tones using an alternative encoding if the tones must be detected by the system which terminates an RTP stream. In this scenario, applications should supply a non-zero value for convert_tones in order to enable this feature.

This requires the module vtdet to have been downloaded.

Fields

The VMP[tx] to be configured

convert_tones

Indicator of whether tones that could be sent using the RFC 2833 standard that are detected in the audio should be encoded as RFC 2833 RTP packets. A non-zero value instructs the VMP[tx] to encode these tones according to RFC 2833(see supported tones from RFC2833).

elim_tones

Indicator of whether tones that could be sent using the RFC 2833 encoding, that are detected in the audio, should be eliminated from the audio. A non-zero value instructs the VMP[tx] to eliminate these tones (see supported tones from RFC2833).

tone_set_id

The tone set that is to be used when converting and eliminating tones. This is the result of a call to sm_vmptx_create_toneset() The same module value must have been used to allocate both this VMP[tx] and the tone set.

min_duration

How much tone needs to be detected before RFC 2833 packets are generated. One of these values:

kSMVMPtxRFC2833MinDurationNoMinimum
kSMVMPtxRFC2833MinDuration40

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_create

Prototype Definition

int sm_vmptx_create(struct sm_vmptx_create_parms *vmptxp)

Parameters

*vmptxp

a structure of the following type:

typedef struct sm_vmptx_create_parms {
	tSMVMPtxId vmptx;					/* out */
	tSMModuleId module;					/* in */
} SM_VMPTX_CREATE_PARMS;

Description

Allocates, on a specific module, a new VMP[tx] to transmit RTP data to a remote device.

If the call completes successfully, the parameter vmptx will be set to the identifier for that vmptx.

This requires the module vmptx to have been downloaded.

Fields

vmptx: The newly created VMP[tx].
module: A value obtained from sm_open_module() which indicates the module where the VMP[tx] is to be allocated.

Returns

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

ERR_SM_DEVERR - device error
ERR_SM_NO_RESOURCES - if insufficient resources exist to create the VMP[tx]

Prosody RTP processing: API: sm_vmptx_create_csrc_list

Prototype Definition

int sm_vmptx_create_csrc_list(struct sm_vmptx_create_csrc_list_parms *csrcp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_create_csrc_list_parms {
	tSMVMPTxCSRCListId csrc_list;				/* out */
	tSMModuleId module;					/* in */
} SM_VMPTX_CREATE_CSRC_LIST_PARMS;

Description

Creates a CSRC list object that can be used by multiple VMP[tx].

The CSRC values can be set using sm_vmptx_csrc_list_set().

Fields

csrc_list: The newly created CSRC list.
module: A value obtained from sm_open_module() which indicates the module where the CSRC list is to be allocated.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_create_toneset

Prototype Definition

int sm_vmptx_create_toneset(struct sm_vmptx_create_toneset_parms *tonesetp)

Parameters

*tonesetp

a structure of the following type:

typedef struct sm_vmptx_create_toneset_parms {
	tSMVMPTxToneSet *toneset;				/* in */
	tSMModuleId module;					/* in */
	tSMVMPTxToneSetId tone_set_id;				/* out */
} SM_VMPTX_CREATE_TONESET_PARMS;

Description

Configures the tones to be detected for use in rfc 2833. A tones set containing all the DTMF tones is included in the API, it is called kSMVMPTxDefaultToneSet.

This requires the module td to have been downloaded.

Fields

toneset: the ToneSet to configure
module: the Module to configure the toneset for
tone_set_id: the returned ToneSetID

Returns

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

ERR_SM_DEVERR -device error

Prosody RTP processing: API: sm_vmptx_csrc_list_set

Prototype Definition

int sm_vmptx_csrc_list_set(struct sm_vmptx_csrc_list_set_parms *csrcp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_csrc_list_set_parms {
	tSMVMPTxCSRCListId csrc_list;				/* in */
	int num_csrc;						/* in */
	int *csrc;						/* in */
} SM_VMPTX_CSRC_LIST_SET_PARMS;

Description

Sets the CSRC list contents. Any VMP[tx] using this list will use the specified CSRC list contents.

Fields

csrc_list: The CSRC list.
num_csrc: The number of CSRCs in the array
csrc: A pointer to an array of CSRCs

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_datafeed_connect

Prototype Definition

int sm_vmptx_datafeed_connect(struct sm_vmptx_datafeed_connect_parms *datafeedp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_datafeed_connect_parms {
	tSMDatafeedId data_source;				/* in */
	tSMVMPtxId vmptx;					/* in */
} SM_VMPTX_DATAFEED_CONNECT_PARMS;

Description

Connects a datafeed to a VMP[tx]. The data_source must be a datafeed obtained a call to any of the *_get_datafeed() functions. The VMP[tx] vmptx will receive any data that is generated by the output task from which data_source was derived.

To disconnect a VMP[tx] from a datafeed, specify kSMNullDatafeedId as the tSMDatafeedId in data_source

Requires the module datafeed to have been downloaded.

Fields

data_source: The datafeed acting as a source of data
vmptx: The VMP[tx] that will receive the data

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_destroy

Prototype Definition

int sm_vmptx_destroy(tSMVMPtxId vmptx)

Parameters

vmptx: A tSMVMPtxId that has been prevously created by a call to sm_vmptx_create().

Description

Destroys vmptx and invalidates the tSMVMPtxId. Normally, a VMP[tx] will only be destroyed when it is in the stopped state. If the VMP[tx] is not in the stopped state, it will be implicitly stopped. It is an error to refer to a VMP[tx] once it has been destroyed.

If a call to sm_vmptx_create() completes successfully, sm_vmptx_stop() should be used to stop to the VMP[tx] and move it into the stopped state.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_destroy_csrc_list

Prototype Definition

int sm_vmptx_destroy_csrc_list(struct sm_vmptx_destroy_csrc_list_parms *csrcp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_destroy_csrc_list_parms {
	tSMVMPTxCSRCListId csrc_list;				/* in */
} SM_VMPTX_DESTROY_CSRC_LIST_PARMS;

Description

Destroys a CSRC list.

Fields

csrc_list: The CSRC list to destroy

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_destroy_toneset

Prototype Definition

int sm_vmptx_destroy_toneset(struct sm_vmptx_destroy_toneset_parms *tonep)

Parameters

a structure of the following type:

typedef struct sm_vmptx_destroy_toneset_parms {
	tSMVMPTxToneSetId tone_set_id;				/* in */
} SM_VMPTX_DESTROY_TONESET_PARMS;

Description

Destroys a toneset used to rfc2833 generation.

Fields

tone_set_id: The toneset to destroy

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_generate_jitter

This function is under development. It could be changed or withdrawn, and may not be implemented in this release.

Prototype Definition

int sm_vmptx_generate_jitter(struct sm_vmptx_generate_jitter_parms *jitterp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_generate_jitter_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT external_jitter_threshold;			/* in */
	tSM_INT inter_jitter_gap;				/* in */
	tSM_INT added_jitter;					/* in */
	tSM_INT max_packet_age;					/* in */
} SM_VMPTX_GENERATE_JITTER_PARMS;

Description

Configures a VMP[tx] to add jitter to the outgoing RTP stream by occasionally buffering packets.

This requires the module vmptx to have been downloaded.

Fields

vmptx (Only in Preliminary Documentation): The VMP[tx] to generate jitter.
external_jitter_threshold (Only in Preliminary Documentation): The time between VMP[tx] execution that is considered to indicate that epochs have been delayed due to external conditions. Note that the normal time between VMP[tx] execution can be up to 20ms, so values larger than this should be used. A value of 0 disables the addition of jitter.
inter_jitter_gap (Only in Preliminary Documentation): The time that must elapse after a jitter burst before the buffering starts again.
added_jitter (Only in Preliminary Documentation): The duration of buffering used to add jitter.
max_packet_age (Only in Preliminary Documentation): The maximum age of packets that are transmitted. A value of 0 will allow all packets to be sent, regardless of their age.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_generate_tones

Prototype Definition

int sm_vmptx_generate_tones(struct sm_vmptx_generate_tones_parms *tonep)

Parameters

a structure of the following type:

typedef struct sm_vmptx_generate_tones_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT *tones;						/* in */
	tSM_INT num;						/* in */
	tSM_INT duration;					/* in */
	tSM_INT interval;					/* in */
	tSM_INT volume;						/* in */
} SM_VMPTX_GENERATE_TONES_PARMS;

Description

Causes a VMP[tx] to generate rfc2833 tone packets for a sequence of tones, containing num tones. Each tone will have duration duration And the interval between the tones will be interval. tones contains a list of tone identifiers for the tones to be generated, as defined in IETF RFC 2833). Both duration and interval must be given as a multiple of 10ms. The volume must be between 0 and -15 inclusive.

Note that this function by itself is not sufficient to cause the VMP[tx] to transmit RTP packets. The VMP[tx] must also have a valid datafeed which has been connected using sm_vmptx_datafeed_connect().

Fields

vmptx: The VMP[tx] that you wish to generates tones with
tones: The tones to generate
num: The number of tones in the list
duration: The duration of the tones.
interval: The interval between the tones
volume: The volume of the tone in dBm0

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_generate_tones_abort

Prototype Definition

int sm_vmptx_generate_tones_abort(struct sm_vmptx_generate_tones_abort_parms *tonep)

Parameters

a structure of the following type:

typedef struct sm_vmptx_generate_tones_abort_parms {
	tSMVMPtxId vmptx;					/* in */
} SM_VMPTX_GENERATE_TONES_ABORT_PARMS;

Description

Causes a VMP[tx] to abort generate rfc2833 tone packets, discarding the current tone and any still pending.

Fields

vmptx: The VMP[tx] that is to generating tones

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_get_event

Prototype Definition

int sm_vmptx_get_event(struct sm_vmptx_event_parms *eventp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_event_parms {
	tSMVMPtxId vmptx;					/* in */
	tSMEventId event;					/* out */
} SM_VMPTX_EVENT_PARMS;

Description

If the call completes successfully event will hold the tSMEventId belonging to vmptx. The tSMEventId is valid until the VMP[tx] is destroyed using sm_vmptx_destroy(). This event will be signalled when a status change occurs on the VMP[tx]. When the event is signalled the user must call sm_vmptx_status() to discover the nature of the status change.

Fields

vmptx: The VMP[tx]
event: The event identifier

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_propagate_rtcp_sr_ntp

Prototype Definition

int sm_vmptx_propagate_rtcp_sr_ntp(struct sm_vmptx_propagate_rtcp_sr_ntp_parms *propp)

Parameters

*propp

a structure of the following type:

typedef struct sm_vmptx_propagate_rtcp_sr_ntp_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_UT64 localtimeref;					/* in */
	tSM_UT64 ntp_timestamp;					/* in */
} SM_VMPTX_PROPAGATE_RTCP_SR_NTP_PARMS;

Description

RTCP sender reports (SRs) include an RTP timestamp and a 64 bit NTP time with this NTP time indicating the wallclock time corresponding to the sample with the given RTP timestamp. For SR associated with a VMP[tx] this NTP time is normally the time of the epoch in which that packet would be emitted. This call sets an adjustment to cause each RTCP SR NTP time to be an earlier time in order to allow the relation between NTP time and a given sample to be maintained when forwarding an RTP signal from a VMP[rx] via a signal pipeline to a VMP[tx]. The passed in ntp_timestamp needs to be calculated by the application, normally using a received RTCP sender report NTP time, and the difference between RTCP SR RTP timestamp and the RTP timestamp obtained on occurrence of sm_vmprx_status() kSMVMPrxStatusJBResync, as a basis for the calculation.

Fields

vmptx: The VMP[tx]
localtimeref: A local time reference in units of microseconds obtained on occurrence of kSMVMPrxStatusJBResync.
ntp_timestamp: The NTP time that should correspond to this localtimeref for this VMP[tx].

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_send_sse

Prototype Definition

int sm_vmptx_send_sse(struct sm_vmptx_send_sse_parms *sendssep)

Parameters

*sendssep

a structure of the following type:

typedef struct sm_vmptx_send_sse_parms {
	tSMVMPtxId vmptx;					/* in */
	char *payload;						/* in */
	tSM_INT payload_length;					/* in */
} SM_VMPTX_SEND_SSE_PARMS;

Description

Instructs a VMP[tx] to send a SSE message. The VMP[tx] must be configured to for SSE using sm_vmptx_config_codec_sse().

This requires the module sse to have been downloaded.

Fields

vmptx: The VMP[tx] used to send the SSE message
payload: A pointer to the payload to be sent
payload_length: The length of the payload

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_set_csrc

Prototype Definition

int sm_vmptx_set_csrc(struct sm_vmptx_set_csrc_parms *csrcp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_set_csrc_parms {
	tSMVMPtxId vmptx;					/* in */
	unsigned repeat_delay;					/* in */
	unsigned packet_count;					/* in */
	enum kSMVMPTxCSRCType {
		kSMVMPTxCSRCTypeArray,
		kSMVMPTxCSRCTypeList,
	} type;							/* in */
	union {
		struct {
			int num_csrc;				/* in */
			int *csrc;				/* in */
		} csrc_array;					/* in */
		struct {
			tSMVMPTxCSRCListId csrc_list_id;	/* in */
			int exclude_ssrc;			/* in */
			int ssrc;				/* in */
		} csrc_list;					/* in */
	} u;							/* in */
} SM_VMPTX_SET_CSRC_PARMS;

Description

Sets the CSRC list to be sent in the RTP packets.

When type is kSMVMPTxCSRCTypeArray, the CSRC list is specified using num_csrc and csrc. If num_csrc is zero then no CSRC list will be sent.

When type is kSMVMPTxCSRCTypeList, the field csrc_list_id must be a list object created using sm_vmptx_create_csrc_list(), or kSMNullVMPTxCSRCListId to clear the CSRC list. Any changes to the list object will automatically be reflected in the RTP packets being sent. Where this VMP[tx] has a corresponding VMP[rx], the appropriate SSRC can be excluded from the CSRC list of the RTP packets sent by this VMP[tx]. When the field exclude_ssrc is non-zero, the SSRC passed in ssrc will not be included in the CSRC list of RTP packets sent by this VMP[tx] even if it is included in the CSRC list object. The list object and vmptx must have been allocated on the same tSMModuleId.

Fields

The VMP[tx] to be configured

repeat_delay

The minimum delay (in ms) between blocks of packets with the CSRC list included. A delay of zero means every packet will include the CSRC list.

packet_count

The number of packets in each block to include the CSRC list.

type

One of these values:

kSMVMPTxCSRCTypeArray: The CSRC list is specified as an array.
kSMVMPTxCSRCTypeList: The CSRC list is specified using a CSRC list object.

csrc_array

This field is only valid if type is kSMVMPTxCSRCTypeArray.

num_csrc: The number of CSRCs in the array
csrc: A pointer to an array of CSRCs

csrc_list

This field is only valid if type is kSMVMPTxCSRCTypeList.

csrc_list_id: The CSRC list to use
exclude_ssrc: An indicator of whether to exclude the SSRC from CSRC list
ssrc: The SSRC to exclude from CSRC list

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_set_profile_specific

Prototype Definition

int sm_vmptx_set_profile_specific(struct sm_vmptx_set_profile_specific_parms *psp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_set_profile_specific_parms {
	tSMVMPtxId vmptx;					/* in */
	tSM_INT paramlen;					/* in */
	char *paramval;						/* in */
} SM_VMPTX_SET_PROFILE_SPECIFIC_PARMS;

Description

Sets profile specific parameters for a VMP[tx] previously set up to encode RTP extensions with call to sm_vmptx_config_profile_specific() . See documentation supplied with ProsodyS profile specific plugin for further details.

Fields

vmptx: The VMP[tx] to be configured
paramlen: The length of the plugin specific parameter string in octets.
paramval: The plugin specific parameter string contents.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_set_rtcphand

Prototype Definition

int sm_vmptx_set_rtcphand(struct sm_vmptx_set_rtcphand_parms *rvp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_set_rtcphand_parms {
	tSMVMPtxId vmptx;					/* in */
	tSMRTCPHandId rtcphand;					/* in */
} SM_VMPTX_SET_RTCPHAND_PARMS;

Description

Configures the RTCP handler which handles RTCP for the VMP[tx]. The RTCP handler and VMP[tx] must have been allocated on same module.

Fields

vmptx: The VMP[tx] to be configured
rtcphand: The RTCP handler to use. The value kSMNullRTCPHandId, means that no RTCP handler is to be used.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_status

Prototype Definition

int sm_vmptx_status(struct sm_vmptx_status_parms *statusp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_status_parms {
	tSMVMPtxId vmptx;					/* in */
	enum kSMVMPtxStatus {
		kSMVMPtxStatusRunning,
		kSMVMPtxStatusStopped,
		kSMVMPtxStatusToneOngoing,
		kSMVMPtxStatusToneCompleted,
		kSMVMPtxStatusSSRC,
	} status;						/* out */
	union {
		struct {
			int ssrc;				/* out */
		} ssrc;						/* out */
	} u;							/* out */
} SM_VMPTX_STATUS_PARMS;

Description

Returns the current status of the VMP[tx] or an error to indicate that a problem occurred during start-up.

When the event, obtained from sm_vmptx_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[tx].

Fields

The VMP[tx] to interrogate

One of these values:

kSMVMPtxStatusRunning: Indicates that there is nothing significant to report
kSMVMPtxStatusStopped: Indicates that the VMP[tx] has stopped transmitting RTP and that it is safe to destroy
kSMVMPtxStatusToneOngoing: Indicates that the VMP[tx] is producing tones
kSMVMPtxStatusToneCompleted: Indicates that the tone generation has completed
kSMVMPtxStatusSSRC: Indicates that the SSRC value has been chosen. The value is given in the ssrc field.

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

This field is only valid if the status is kSMVMPtxStatusSSRC.

ssrc: The SSRC value chosen.

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[tx]

Prosody RTP processing: API: sm_vmptx_stop

Prototype Definition

int sm_vmptx_stop(struct sm_vmptx_stop_parms *stopp)

Parameters

a structure of the following type:

typedef struct sm_vmptx_stop_parms {
	tSMVMPtxId vmptx;					/* in */
} SM_VMPTX_STOP_PARMS;

Description

Requests that a VMP[tx] stops executing. The user will be notified that a VMP[tx] has terminated by a final status, kSMVMPtxStatusStopped, from sm_vmptx_status(). Once the stopped status notification has been received the VMP[tx] can be destroyed using sm_vmptx_destroy().

Once the VMP[tx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_vmptx_destroy() is called.

Fields

vmptx: A tSMVMPtxId that has been previously created by a call to sm_vmptx_create().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_config_codec_rfc3984

This function is deprecated.

Prototype Definition

int sm_vidmprx_config_codec_rfc3984(struct sm_vidmprx_codec_rfc3984_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_codec_rfc3984_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSM_INT payload_type;					/* in */
	enum kSMRFC3984PicSize {
		kSMRFC3984PicSizeSubQCIF=1,
		kSMRFC3984PicSizeQCIF,
		kSMRFC3984PicSizeCIF,
		kSMRFC3984PicSize4CIF,
		kSMRFC3984PicSize16CIF,
	} pic_size;						/* in */
} SM_VIDMPRX_CODEC_RFC3984_PARMS;

Description

Configures an RFC 3984 de-packetiser, as defined in IETF RFC 3984, to the VidMP[rx] setting the payload type mapping to payload_type.

The de-packetiser accepts RTP packets as input, and composes Audio Video Format (AVF) frames as output, which the VidMP[rx] makes available via its datafeed.

It is possible to change the payload type mapping of a de-packetiser whilst a VidMP[rx] remains valid by specifying a new payload type mapping for a given de-packetiser. This supersedes any previous mappings that were in effect for that de-packetiser.

If the call completes successfully, RTP packets arriving at the VidMP[rx] with a payload type that matches a mapped type will be decoded using this de-packetiser.

If the de-packetiser is given the payload type -1 the de-packetiser is no longer valid for this RTP session, unless it is subsequently reconfigured.

On starting to receive RTP packets, a newly configured de-packetiser will not emit any AVF frames until it is reasonably certain that the first valid and complete H.264 Intra (I-) Frame, including one or more Sequence/Picture Parameter Set pairs, has been received. Waiting for an I-Frame attempts to ensure that the video, when later rendered, starts cleanly and without the picture disruption which may occur were the rendering decoder to attempt to decode Predicted (P-) Frames without an I-Frame as reference. A Parameter Set pair is required because no frames can be decoded without one.

Each I-Frame in the output AVF stream will include the latest received Parameter Set pair(s).

Fields

vidmprx (Deprecated)

The VidMP[rx] to which to add the de-packetiser

payload_type (Deprecated)

The payload type identifer to use with this de-packetiser (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the de-packetiser preventing its use.

pic_size (Deprecated)

The size of the picture which will be received. If a value of 0 is supplied, the QCIF size is assumed.

One of these values:

kSMRFC3984PicSizeSubQCIF: Received picture size will be sub-QCIF.
kSMRFC3984PicSizeQCIF: Received picture size will be QCIF.
kSMRFC3984PicSizeCIF: Received picture size will be CIF.
kSMRFC3984PicSize4CIF: Received picture size will be 4CIF.
kSMRFC3984PicSize16CIF: Received picture size will be 16CIF.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_config_codec_rfc4629

This function is deprecated.

Prototype Definition

int sm_vidmprx_config_codec_rfc4629(struct sm_vidmprx_codec_rfc4629_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_codec_rfc4629_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT h263_profile;					/* in */
	tSM_INT h263_level;					/* in */
} SM_VIDMPRX_CODEC_RFC4629_PARMS;

Description

Configures an RFC 4629 de-packetiser, as defined in IETF RFC 4629, to the VidMP[rx] setting the payload type mapping to payload_type.

The de-packetiser accepts RTP packets as input, and composes Audio Video Format (AVF) frames as output, which the VidMP[rx] makes available via its datafeed.

If the call completes successfully, RTP packets arriving at the VidMP[rx] with a payload type that matches a mapped type will be decoded using this de-packetiser.

If the de-packetiser is given the payload type -1 the de-packetiser is no longer valid for this RTP session, unless it is subsequently reconfigured.

On starting to receive RTP packets, a newly configured de-packetiser will not emit any AVF frames until it is reasonably certain that the first valid and complete H.263 Intra (I-) Frame has been received. Waiting for an I-Frame attempts to ensure that the video, when later rendered, starts cleanly and without the picture disruption which will occur were the rendering decoder to attempt to decode Predicted (P-) Frames without an I-Frame as reference.

Fields

vidmprx (Deprecated): The VidMP[rx] to which to add the de-packetiser
payload_type (Deprecated): The payload type identifer to use with this de-packetiser (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the de-packetiser preventing its use.
h263_profile (Deprecated): The H.263 profile value with which the de-packetiser should populate the outgoing data stream. This should be set to a value between 0 and 10, inclusive. Values outside this range will be limited to the range. For further information please see the ITU-T H.263 (01/2005) specification, Annex X.
h263_level (Deprecated): The H.263 level value with which the de-packetiser should populate the outgoing data stream. If this value is set to 0, a default level of 10 will be used. This should be set to a value between 0 and 100, inclusive. Values outside this range will be limited to the range. For further information please see the ITU-T H.263 (01/2005) specification, Annex X.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_config_dataloss

This function is deprecated.

Prototype Definition

int sm_vidmprx_config_dataloss(struct sm_vidmprx_dataloss_parms *datalossp)

Parameters

*datalossp

a structure of the following type:

typedef struct sm_vidmprx_dataloss_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSM_INT loss_threshold;					/* in */
} SM_VIDMPRX_DATALOSS_PARMS;

Description

Configures the data loss threshold for a VidMP[rx]. When the VidMP[rx] is running, sm_vidmprx_status(), indicates whether or not data is currently being received. If no valid data is available for at least the data loss threshold since the last valid data, the status indicates that data is not being received. The status changes to indicate that data is being received when a valid data packet is received.

Packets which are discarded (for example, duplicates or those which fail authentication) are not considered valid data.

A data loss threshold of zero disables the reporting of data loss.

The VidMP[rx] event is signalled when the first data packet is received, any time subsequently when the data loss threshold is reached, and any time when data arrives after data loss. When a VidMP[rx] is first configured, it is already experiencing data loss (because there has obviously been no data for the data loss period, since there has never been data), so the VidMP[rx] event is not signalled. If an application wants to have a data loss timeout to guard against no data ever being received, it needs to implement its own timer.

Fields

vidmprx (Deprecated): The VidMP[rx] to be configured
loss_threshold (Deprecated): The threshold to use (in mS).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_config_jitter

This function is deprecated.

Prototype Definition

int sm_vidmprx_config_jitter(struct sm_vidmprx_jitter_parms *jitterp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_jitter_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSM_UT32 max_delay_ms;					/* in */
	tSM_UT32 initial_delay_ms;				/* in */
} SM_VIDMPRX_JITTER_PARMS;

Description

Allows an application to confgure the jitter buffer belonging to a VidMP[rx]. Default values are used for the jitter buffer when a VidMP[rx] is created, so explicit configuration may not be necesary. Reconfiguration of the jitter buffer may result in audible artifacts in the audio stream during reconfiguration.

Fields

vidmprx (Deprecated): The VidMP[rx] to be configured
max_delay_ms (Deprecated): Maximum allowable length for the jitter buffer in milliseconds. The default is 100.
initial_delay_ms (Deprecated): Initial amount of audio the jitter buffer should accumulate at startup. The default is 50.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_config_unhandled_payload_reporting

This function is deprecated.

Prototype Definition

int sm_vidmprx_config_unhandled_payload_reporting(struct sm_vidmprx_unhandled_payload_reporting_parms *pp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_unhandled_payload_reporting_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSM_INT delay;						/* in */
} SM_VIDMPRX_UNHANDLED_PAYLOAD_REPORTING_PARMS;

Description

Configures a VidMP[rx] to report when packets arrive with a payload type it is not configured to handle. The delay prevents repeat notifications from being sent too often. A zero delay will cause every packet with an unhandled payload type to be reported. A negative delay disables reporting of unhandled payload types.

Fields

vidmprx (Deprecated): The VidMP[rx] to be configured
delay (Deprecated): The minimum delay between reports of unhandled payload types (in ms).

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_create

This function is deprecated.

Prototype Definition

int sm_vidmprx_create(struct sm_vidmprx_create_parms *vidmprxp)

Parameters

*vidmprxp

a structure of the following type:

typedef struct sm_vidmprx_create_parms {
	tSMVidMPrxId vidmprx;					/* out */
	tSMModuleId module;					/* in */
	enum kSMVidMPrxType {
		kSMVidMPrxTypeIPv4,
		kSMVidMPrxTypeIPv6,
	} type;							/* in */
	struct in_addr address;					/* in */
	struct in6_addr ipv6_address;				/* in */
} SM_VIDMPRX_CREATE_PARMS;

Description

Allocates, on a specific module, a new VidMP[rx] to receive incoming RTP data. If the call completes successfully, the parameter vidmprx will be set to the identifier for that vidmprx.

A VidMP[rx] is automatically allocated a port number for incoming RTP data, this information may be obtained by calling sm_vidmprx_get_ports() or by waiting for sm_vidmprx_status() to return the port information. Any RTP data arriving at the VidMP[rx] will be interpreted based on the codec configuration. The VidMP[rx] will discard any incoming packets that do not match it's current configuration settings.

This requires the module vmprx to have been downloaded.

Fields

vidmprx (Deprecated)

The newly created VidMP[rx].

module (Deprecated)

A value obtained from sm_open_module() which indicates the module where the VidMP[rx] is to be allocated.

type (Deprecated)

One of these values:

kSMVidMPrxTypeIPv4: The VidMP[rx] is to receive IPv4 packets
kSMVidMPrxTypeIPv6: The VidMP[rx] is to receive IPv6 packets

address (Deprecated)

The address on which this VidMP[rx] is to listen if type is kSMVidMPrxTypeIPv4.

ipv6_address (Deprecated)

The address on which this VidMP[rx] is to listen if type is kSMVidMPrxTypeIPv6.

Returns

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

ERR_SM_DEVERR - device error
ERR_SM_NO_RESOURCES - if insufficient resources exist to create the VidMP[rx]

Prosody RTP processing: API: sm_vidmprx_destroy

This function is deprecated.

Prototype Definition

int sm_vidmprx_destroy(tSMVidMPrxId vidmprx)

Parameters

vidmprx: A tSMVidMPrxId that has been prevously created by a call to sm_vidmprx_create().

Description

Destroys vidmprx and invalidates the tSMVidMPrxId. Normally, a VidMP[rx] will only be destroyed when it is in the stopped state. If the VidMP[rx] is not in the stopped state, it will be implicitly stopped. It is an error to refer to a VidMP[rx] once it has been destroyed.

If a call to sm_vidmprx_create() completes successfully, sm_vidmprx_stop() should be used to stop to the VidMP[rx] and move it into the stopped state.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_get_datafeed

This function is deprecated.

Prototype Definition

int sm_vidmprx_get_datafeed(struct sm_vidmprx_datafeed_parms *datafeedp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_datafeed_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSMDatafeedId datafeed;					/* out */
} SM_VIDMPRX_DATAFEED_PARMS;

Description

Request a datafeed identifier from a VidMP[rx]. This identifer can subsequently be used in a call to any of the *_datafeed_connect() functions to connect the output from the VidMP[rx] to a destination. It is valid until the VidMP[rx] is destroyed. Datafeed connections can only be made between objects allocated on the same tSMModuleId.

Requires the module datafeed to have been downloaded.

Fields

vidmprx (Deprecated): The VidMP[rx] from which to obtain a datafeed
datafeed (Deprecated): The datafeed object associated with the VidMP[rx]

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_get_event

This function is deprecated.

Prototype Definition

int sm_vidmprx_get_event(struct sm_vidmprx_event_parms *eventp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_event_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSMEventId event;					/* out */
} SM_VIDMPRX_EVENT_PARMS;

Description

If the call completes successfully event will hold the tSMEventId belonging to vidmprx. The tSMEventId is valid until the VidMP[rx] is destroyed using sm_vidmprx_destroy(). This event will be signalled when a status change occurs on the VidMP[rx]. When the event is signalled the user must call sm_vidmprx_status() to discover the nature of the status change.

Fields

vidmprx (Deprecated): The VidMP[rx]
event (Deprecated): The event identifier

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_get_ports

This function is deprecated.

Prototype Definition

int sm_vidmprx_get_ports(struct sm_vidmprx_port_parms *portp)

Parameters

*portp

a structure of the following type:

typedef struct sm_vidmprx_port_parms {
	tSMVidMPrxId vidmprx;					/* in */
	int RTP_port;						/* out */
	int RTCP_port;						/* out */
	struct in_addr address;					/* out */
	struct in6_addr ipv6_address;				/* out */
	tSM_UT32 nowait;					/* in */
} SM_VIDMPRX_PORT_PARMS;

Description

Retrieves the RTP and RTCP port numbers which have been allocated by this VidMP[rx] and on which it is listening.

If the call completes successfully, RTP_port will contain the port number where RTP packets should be directed for this VidMP[rx]. Similarly, RTCP_port will contain the port number where RTCP packets should be directed.

Fields

vidmprx (Deprecated): The VidMP[rx] to be interrogated
RTP_port (Deprecated): The UDP port number on which this VidMP[rx] is listening for RTP
RTCP_port (Deprecated): The UDP port number on which this VidMP[rx] is listening for RTCP
address (Deprecated): The address on which this VidMP[rx] is listening if this is a IPv4 VidMP[rx].
ipv6_address (Deprecated): The address on which this VidMP[rx] is listening if this is a IPv6 VidMP[rx].
nowait (Deprecated): Selects blocking or non-blocking mode for this API call. In non-blocking mode the API call may return without the requested information. It is recommended that users wait for sm_vidmprx_status() to inform the application that the port and address information is available, rather than using this API call. If the nowait flag is clear, the API call will block until the desired information is available, otherwise the API call will return immediately.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_ice_stun_change_role

This function is deprecated.

Prototype Definition

int sm_vidmprx_ice_stun_change_role(struct sm_vidmprx_ice_stun_change_role_parms *rolep)

Parameters

*rolep

a structure of the following type:

typedef struct sm_vidmprx_ice_stun_change_role_parms {
	tSMVidMPrxId vidmprx;					/* in */
	enum kSMICERole local_role;				/* in */
} SM_VIDMPRX_ICE_STUN_CHANGE_ROLE_PARMS;

Description

Changes the role of ICE compatible STUN on the VidMP[rx].

Note: the role can only be changed when in either the controlled or controlling role and it can only be changed to the controlling or controlled role.

This requires the module icestun to have been downloaded.

Fields

vidmprx (Deprecated)

A VidMP[rx] running ICE compatible STUN.

local_role (Deprecated)

The new role of the local ICE agent. Note: changing to kSMICERoleNone or kSMICERoleLite is not permitted.

One of these values:

kSMICERoleNone: The VidMP[rx] does not handle STUN packets.
kSMICERoleLite: The local ICE agent is an ice-lite agent.
kSMICERoleControlled: The local ICE agent is controlled.
kSMICERoleControlling: The local ICE agent is controlling.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_ice_stun_config

This function is deprecated.

Prototype Definition

int sm_vidmprx_ice_stun_config(struct sm_vidmprx_ice_stun_config_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_ice_stun_config_parms {
	tSMVidMPrxId vidmprx;					/* in */
	enum kSMICERole {
		kSMICERoleNone,
		kSMICERoleLite,
		kSMICERoleControlled,
		kSMICERoleControlling,
	} local_role;						/* in */
	char *local_ice_ufrag;					/* in */
	tSM_UT32 local_ice_ufrag_length;			/* in */
	char *local_ice_pwd;					/* in */
	tSM_UT32 local_ice_pwd_length;				/* in */
	tSM_UT64 role_tiebreaker;				/* in */
} SM_VIDMPRX_ICE_STUN_CONFIG_PARMS;

Description

Enables or disables ICE compatible STUN on the VidMP[rx]. See IETF RFC 5245 and IETF RFC 5389 for more details.

This requires the module icestun to have been downloaded.

Fields

vidmprx (Deprecated)

The VidMP[rx] being configured.

local_role (Deprecated)

The role of the local ICE agent.

One of these values:

kSMICERoleNone: The VidMP[rx] does not handle STUN packets.
kSMICERoleLite: The local ICE agent is an ice-lite agent.
kSMICERoleControlled: The local ICE agent is controlled.
kSMICERoleControlling: The local ICE agent is controlling.

local_ice_ufrag (Deprecated)

The local ICE username fragment.

local_ice_ufrag_length (Deprecated)

The length of the local ICE username fragment.

local_ice_pwd (Deprecated)

The local ICE password.

local_ice_pwd_length (Deprecated)

The length of the local ICE password.

role_tiebreaker (Deprecated)

The ICE role tiebreaker value.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_ice_stun_remote_credentials

This function is deprecated.

Prototype Definition

int sm_vidmprx_ice_stun_remote_credentials(struct sm_vidmprx_ice_stun_remote_credentials_parms *credentialsp)

Parameters

*credentialsp

a structure of the following type:

typedef struct sm_vidmprx_ice_stun_remote_credentials_parms {
	tSMVidMPrxId vidmprx;					/* in */
	char *remote_ice_ufrag;					/* in */
	tSM_UT32 remote_ice_ufrag_length;			/* in */
	char *remote_ice_pwd;					/* in */
	tSM_UT32 remote_ice_pwd_length;				/* in */
} SM_VIDMPRX_ICE_STUN_REMOTE_CREDENTIALS_PARMS;

Description

Sets the remote credentials.

This requires the module icestun to have been downloaded.

Fields

vidmprx (Deprecated): A VidMP[rx] running ICE compatible STUN.
remote_ice_ufrag (Deprecated): The remote ICE username fragment.
remote_ice_ufrag_length (Deprecated): The length of the remote ICE username fragment.
remote_ice_pwd (Deprecated): The remote ICE password.
remote_ice_pwd_length (Deprecated): The length of the remote ICE password.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_ice_stun_send_bind_request

This function is deprecated.

Prototype Definition

int sm_vidmprx_ice_stun_send_bind_request(struct sm_vidmprx_ice_stun_send_bind_request_parms *requestp)

Parameters

*requestp

a structure of the following type:

typedef struct sm_vidmprx_ice_stun_send_bind_request_parms {
	tSMVidMPrxId vidmprx;					/* in */
	int use_RTCP_port;					/* in */
	char transaction_id[12];				/* in */
	union {
		SOCKADDR_IN ipv4;				/* in */
		SOCKADDR_IN6 ipv6;				/* in */
	} destination;						/* in */
	tSM_UT32 priority;					/* in */
	tSM_INT use_candidate;					/* in */
} SM_VIDMPRX_ICE_STUN_SEND_BIND_REQUEST_PARMS;

Description

Sends a STUN bind request.

This requires the module icestun to have been downloaded.

Fields

vidmprx (Deprecated)

A VidMP[rx] running ICE compatible STUN.

use_RTCP_port (Deprecated)

Which port to use as the source for the request. When non-zero, use the RTCP port. Otherwise, the RTP port is used

transaction_id (Deprecated)

The transaction ID to use, in the same byte order as the packet.

destination (Deprecated)

ipv4: The destination on the bind request when the VidMP[rx] is an IPv4 endpoint.
ipv6: The destination on the bind request when the VidMP[rx] is an IPv6 endpoint.

priority (Deprecated)

The priority to assign to a learned peer reflexive address.

use_candidate (Deprecated)

An indicator of whether to include the USE-CANDIDATE attribute.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_status

This function is deprecated.

Prototype Definition

int sm_vidmprx_status(struct sm_vidmprx_status_parms *statusp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_status_parms {
	tSMVidMPrxId vidmprx;					/* in */
	enum kSMVidMPrxStatus {
		kSMVidMPrxStatusRunning,
		kSMVidMPrxStatusStopped,
		kSMVidMPrxStatusGotPorts,
		kSMVidMPrxStatusNewSSRC,
		kSMVidMPrxStatusUnhandledPayload,
		kSMVidMPrxStatusInternalError,
		kSMVidMPrxStatusGotPortsIPv6,
		kSMVidMPrxStatusNewSSRCIPv6,
		kSMVidMPrxStatusSTUNBindRequest,
		kSMVidMPrxStatusSTUNBindResponse,
	} status;						/* out */
	union {
		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 num_errors;				/* out */
		} internal_error;				/* 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 kSMVidMPrxSTUNResult {
				kSMVidMPrxSTUNResultSuccess,
				kSMVidMPrxSTUNResultError,
				kSMVidMPrxSTUNResultInvalid,
				kSMVidMPrxSTUNResultTimeout,
			} 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 */
	} u;							/* out */
} SM_VIDMPRX_STATUS_PARMS;

Description

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

When the VidMP[rx] event, obtained from sm_vidmprx_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 VidMP[rx].

Fields

vidmprx (Deprecated)

The VidMP[rx] to interrogate

status (Deprecated)

One of these values:

kSMVidMPrxStatusRunning: The VidMP[rx] is running normally.
kSMVidMPrxStatusStopped: Indicates that the VidMP[rx] has stopped processing RTP and that it is safe to destroy
kSMVidMPrxStatusGotPorts: Indicates that IPv4 port information is available. In addition to being reported with this status, this information can be retrieved with sm_vidmprx_get_ports() at any time until the VidMP[x] is stopped.
kSMVidMPrxStatusNewSSRC: Indicates that a new SSRC value from an IPv4 endpoint is being used.
kSMVidMPrxStatusUnhandledPayload: Indicates that a packet was received with a payload type that could not be handled
kSMVidMPrxStatusInternalError: Indicates that the VidMP[rx] encountered one or more internal errors when processing the incoming packet stream. These errors will result in the media stream output from the VidMP[rx] missing some data. Note that such errors are not fatal - the VidMP[rx] continues to run. These status reports are throttled in order to maintain a sensibly low rate of reporting even in the event of a high rate of errors.
kSMVidMPrxStatusGotPortsIPv6: 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.
kSMVidMPrxStatusNewSSRCIPv6: Indicates that a new SSRC value from and IPv6 endpoint is being used.
kSMVidMPrxStatusSTUNBindRequest: Indicates that a STUN bind request has been received.
kSMVidMPrxStatusSTUNBindResponse: Indicates that a STUN bind response has been received.

u (Deprecated)

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

ports

This field is only valid if the status is kSMVidMPrxStatusGotPorts

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

run

This field is only valid if the status is kSMVidMPrxStatusRunning

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

This field is only valid if the status is kSMVidMPrxStatusNewSSRC

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 kSMVidMPrxStatusUnhandledPayload

type: The payload type identifier from the RTP packet

internal_error

This field is only valid if the status is kSMVidMPrxStatusInternalError

num_errors: The number of internal errors encountered by the VidMP[rx] covered by this status report.

ports_ipv6

This field is only valid if the status is kSMVidMPrxStatusGotPortsIPv6.

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

ssrc_ipv6

This field is only valid if the status is kSMVidMPrxStatusNewSSRCIPv6.

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 kSMVidMPrxStatusSTUNBindRequest

The port the STUN bind request was received on.

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

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

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.

remote_is_controlling

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.

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 kSMVidMPrxStatusSTUNBindResult

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:

kSMVidMPrxSTUNResultSuccess: A valid success response was received.
kSMVidMPrxSTUNResultError: A valid error response was received.
kSMVidMPrxSTUNResultInvalid: A invalid response was received.
kSMVidMPrxSTUNResultTimeout: No response was received.

error_code

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

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.

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

local_was_controlling

The reflexive port.

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.

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 VidMP[rx]

Prosody RTP processing: API: sm_vidmprx_stop

This function is deprecated.

Prototype Definition

int sm_vidmprx_stop(struct sm_vidmprx_stop_parms *stopp)

Parameters

a structure of the following type:

typedef struct sm_vidmprx_stop_parms {
	tSMVidMPrxId vidmprx;					/* in */
} SM_VIDMPRX_STOP_PARMS;

Description

Requests that a VidMP[rx] stops executing. The user will be notified that a VidMP[rx] has terminated by a final status, kSMVidMPrxStatusStopped, from sm_vidmprx_status(). Once the stopped status notification has been received the VidMP[rx] can be destroyed using sm_vidmprx_destroy().

Once the VidMP[rx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_vidmprx_destroy() is called.

Fields

vidmprx (Deprecated): A tSMVidMPrxId that has been previously created by a call to sm_vidmprx_create().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmprx_sync_media

This function is deprecated.

Prototype Definition

int sm_vidmprx_sync_media(struct sm_vidmprx_sync_media_parms *syncmediap)

Parameters

*syncmediap

a structure of the following type:

typedef struct sm_vidmprx_sync_media_parms {
	tSMVidMPrxId vidmprx;					/* in */
	tSMVMPrxId vmprx;					/* in */
} SM_VIDMPRX_SYNC_MEDIA_PARMS;

Description

Attempts to provide synchronisation between the media streams from a VidMP[rx] and a VMP[rx]. This is designed to be used when the two streams originated from the same source. There is no guarantee that synchronisation can be achieved, even for streams originating from the same source.

Fields

vidmprx (Deprecated): A tSMVidMPrxId that has been previously created by a call to sm_vidmprx_create().
vmprx (Deprecated): The tSMVMPrxId that corresponds to the stream with which to synchronise

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_config

This function is deprecated.

Prototype Definition

int sm_vidmptx_config(struct sm_vidmptx_config_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_config_parms {
	tSMVidMPtxId vidmptx;					/* in */
	SOCKADDR_IN destination_rtp;				/* in */
	SOCKADDR_IN source_rtp;					/* in */
	int TOS_RTP;						/* in */
	SOCKADDR_IN destination_rtcp;				/* in */
	SOCKADDR_IN source_rtcp;				/* in */
	int TOS_RTCP;						/* in */
} SM_VIDMPTX_CONFIG_PARMS;

Description

Configures a VidMP[tx] to send RTP and RTCP data to a device with the specified IP address and port numbers.

If the call completes successfully RTP data generated by the vidmptx will be sent to the address and port as specified in destination_rtp. Any associated RTCP data will be delivered to the address and port specified by destination_rtcp. Specifying the source_rtp instructs the VidMP[tx] to use the given IP address and port for outgoing RTP data. Specifying the source_rtcp instructs the VidMP[tx] to use the given IP address and port for outgoing RTCP data.

This requires the module vidmptx to have been downloaded.

Fields

vidmptx (Deprecated): The VidMP[tx] to configure
destination_rtp (Deprecated): The SOCKADDR_IN structure specifying the destination IP address and port for the RTP stream. A struct SOCKADDR_IN must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
source_rtp (Deprecated): The SOCKADDR_IN structure allows you to specify the source IP address and port for the RTP stream. A struct SOCKADDR_IN must be configured with an address family. The IP address may be specified, or the value INADDR_ANY may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order. The structure must be correctly cast such that an IP V4 address is specified.
TOS_RTP (Deprecated): The Type Of Service (TOS) indicator to be sent with RTP data
destination_rtcp (Deprecated): The SOCKADDR_IN structure specifying the destination IP address and port for the RTCP stream. A struct SOCKADDR_IN must be configured with an address family, an IP address and a port. Note that most operating systems define this structure such that fields are in network bytes order. The structure must be correctly cast such that an IP V4 address is specified.
source_rtcp (Deprecated): The SOCKADDR_IN structure allows you to specify the source IP address and port for the RTCP stream. A struct SOCKADDR_IN must be configured with an address family. The IP address may be specified, or the value INADDR_ANY may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network bytes order. The structure must be correctly cast such that an IP V4 address is specified.
TOS_RTCP (Deprecated): The Type Of Service (TOS) indicator to be sent with RTCP data

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_config_codec_rfc3984

This function is deprecated.

Prototype Definition

int sm_vidmptx_config_codec_rfc3984(struct sm_vidmptx_codec_rfc3984_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_codec_rfc3984_parms {
	tSMVidMPtxId vidmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT deaggregate;					/* in */
} SM_VIDMPTX_CODEC_RFC3984_PARMS;

Description

Configures an RFC 3984 packetiser, as defined in IETF RFC 3984, to the VidMP[tx] setting the payload type mapping to payload_type.

The packetiser accepts Audio Video Format (AVF) frames from the VidMP[tx] incoming datafeed as input, and composes RTP packets as output.

A newly configured packetiser will not emit any RTP packets until it receives an H.264 I-Frame in the incoming AVF stream. Waiting for an I-Frame attempts to ensure that the video, when rendered by the remote endpoint, starts cleanly and without the picture disruption which will occur were the rendering decoder to attempt to decode P-Frames (Predicted) without an I-Frame as reference.

The packetiser will emit H.264 parameter sets over RTP whenever received in the incoming AVF stream. In practice, this means it will emit parameter sets every I-frame. Although the parameter sets are unlikely to change often, transmitting them with each I-frame allows more robustness against packet loss, the ability for a remote endpoint to start decoding on any I-frame (i.e. mid-stream) and appears to be the norm amongst videophones.

Fields

vidmptx (Deprecated): The VidMP[tx] to which to add the packetiser
payload_type (Deprecated): The payload type identifer to use with this packetiser (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the packetiser preventing its use.
deaggregate (Deprecated): Allows behaviour with aggregation packets to be modified. If this parameter is set to 0, each aggregation packet received as input is transmitted as a whole. Otherwise, each such packet is split and one packet transmitted for each H.264 NALU. Setting this to a value other than 0 should not be necessary when transmitting to an endpoint which is properly RFC3984 compliant.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_config_codec_rfc4629

This function is deprecated.

Prototype Definition

int sm_vidmptx_config_codec_rfc4629(struct sm_vidmptx_codec_rfc4629_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_codec_rfc4629_parms {
	tSMVidMPtxId vidmptx;					/* in */
	tSM_INT payload_type;					/* in */
	tSM_INT rem_ext_pic_hdr;				/* in */
} SM_VIDMPTX_CODEC_RFC4629_PARMS;

Description

Configures an RFC 4629 packetiser, as defined in IETF RFC 4629, to the VidMP[tx] setting the payload type mapping to payload_type.

The packetiser accepts Audio Video Format (AVF) frames from the VidMP[tx] incoming datafeed as input, and composes RTP packets as output.

A newly configured packetiser will not emit any RTP packets until it receives an H.263 I-Frame in the incoming AVF stream. Waiting for an I-Frame attempts to ensure that the video, when rendered by the remote endpoint, starts cleanly and without the picture disruption which will occur were the rendering decoder to attempt to decode Predicted (P-) Frames without an I-Frame as reference.

Fields

vidmptx (Deprecated): The VidMP[tx] to which to add the packetiser
payload_type (Deprecated): The payload type identifer to use with this packetiser (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the packetiser preventing its use.
rem_ext_pic_hdr (Deprecated): Allows handling of the extra picture header to be modified. If set to 0, each packet containing an extra picture header is transmitted as a whole. Otherwise, each such packet is transmitted with the extra picture header removed. See IETF RFC 4629 section 5.1. This behaviour allows interworking with non-conformant endpoints which require a zero length extra picture header.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_config_ipv6

This function is deprecated.

Prototype Definition

int sm_vidmptx_config_ipv6(struct sm_vidmptx_config_ipv6_parms *configp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_config_ipv6_parms {
	tSMVidMPtxId vidmptx;					/* in */
	SOCKADDR_IN6 destination_rtp;				/* in */
	SOCKADDR_IN6 source_rtp;				/* in */
	SOCKADDR_IN6 destination_rtcp;				/* in */
	SOCKADDR_IN6 source_rtcp;				/* in */
} SM_VIDMPTX_CONFIG_IPV6_PARMS;

Description

Configures a VidMP[tx] to send RTP and RTCP data to a device with the specified IPv6 address and port numbers.

If the call completes successfully RTP data generated by the vidmptx will be sent to the address and port as specified in destination_rtp. Any associated RTCP data will be delivered to the address and port specified by destination_rtcp. Specifying the source_rtp instructs the VidMP[tx] to use the given IPv6 address and port for outgoing RTP data. Specifying the source_rtcp instructs the VidMP[tx] to use the given IPv6 address and port for outgoing RTCP data.

This requires the module vidmptx to have been downloaded.

Fields

vidmptx (Deprecated): The VidMP[tx] to configure
destination_rtp (Deprecated): The SOCKADDR_IN6 structure specifying the destination IP address and port for the RTP stream. A struct SOCKADDR_IN6 must be configured with an address family, an IPv6 address and a port. Note that most operating systems define this structure such that fields are in network byte order.
source_rtp (Deprecated): The SOCKADDR_IN6 structure allows you to specify the source IP address and port for the RTP stream. A struct SOCKADDR_IN6 must be configured with an address family. The IP address may be specified, or a value equivalent to in6addr_any may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network byte order.
destination_rtcp (Deprecated): The SOCKADDR_IN6 structure specifying the destination IP address and port for the RTCP stream. A struct SOCKADDR_IN6 must be configured with an address family, an IPv6 address and a port. Note that most operating systems define this structure such that fields are in network bytes order.
source_rtcp (Deprecated): The SOCKADDR_IN6 structure allows you to specify the source IP address and port for the RTCP stream. A struct SOCKADDR_IN6 must be configured with an address family. The IP address may be specified, or a value equivalent to in6addr_any may be used to indicate that any suitable address may be used. The port number may be specified, or the value zero may be used to indicate that a suitable port number is to be automatically allocated and used. Note that most operating systems define this structure such that fields are in network bytes order.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_create

This function is deprecated.

Prototype Definition

int sm_vidmptx_create(struct sm_vidmptx_create_parms *vidmptxp)

Parameters

*vidmptxp

a structure of the following type:

typedef struct sm_vidmptx_create_parms {
	tSMVidMPtxId vidmptx;					/* out */
	tSMModuleId module;					/* in */
} SM_VIDMPTX_CREATE_PARMS;

Description

Allocates, on a specific module, a new VidMP[tx] to transmit RTP data to a remote device.

If the call completes successfully, the parameter vidmptx will be set to the identifier for that vidmptx.

This requires the module vmptx to have been downloaded.

Fields

vidmptx (Deprecated): The newly created VidMP[tx].
module (Deprecated): A value obtained from sm_open_module() which indicates the module where the VidMP[tx] is to be allocated.

Returns

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

ERR_SM_DEVERR - device error
ERR_SM_NO_RESOURCES - if insufficient resources exist to create the VidMP[tx]

Prosody RTP processing: API: sm_vidmptx_datafeed_connect

This function is deprecated.

Prototype Definition

int sm_vidmptx_datafeed_connect(struct sm_vidmptx_datafeed_connect_parms *datafeedp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_datafeed_connect_parms {
	tSMDatafeedId data_source;				/* in */
	tSMVidMPtxId vidmptx;					/* in */
} SM_VIDMPTX_DATAFEED_CONNECT_PARMS;

Description

Connects a datafeed to a VidMP[tx]. The data_source must be a datafeed obtained a call to any of the *_get_datafeed() functions. The VidMP[tx] vidmptx will receive any data that is generated by the output task from which data_source was derived.

To disconnect a VidMP[tx] from a datafeed, specify kSMNullDatafeedId as the tSMDatafeedId in data_source

Requires the module datafeed to have been downloaded.

Fields

data_source (Deprecated): The datafeed acting as a source of data
vidmptx (Deprecated): The VidMP[tx] that will receive the data

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_destroy

This function is deprecated.

Prototype Definition

int sm_vidmptx_destroy(tSMVidMPtxId vidmptx)

Parameters

vidmptx: A tSMVidMPtxId that has been prevously created by a call to sm_vidmptx_create().

Description

Destroys vidmptx and invalidates the tSMVidMPtxId. Normally, a VidMP[tx] will only be destroyed when it is in the stopped state. If the VidMP[tx] is not in the stopped state, it will be implicitly stopped. It is an error to refer to a VidMP[tx] once it has been destroyed.

If a call to sm_vidmptx_create() completes successfully, sm_vidmptx_stop() should be used to stop to the VidMP[tx] and move it into the stopped state.

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_get_event

This function is deprecated.

Prototype Definition

int sm_vidmptx_get_event(struct sm_vidmptx_event_parms *eventp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_event_parms {
	tSMVidMPtxId vidmptx;					/* in */
	tSMEventId event;					/* out */
} SM_VIDMPTX_EVENT_PARMS;

Description

If the call completes successfully event will hold the tSMEventId belonging to vidmptx. The tSMEventId is valid until the VidMP[tx] is destroyed using sm_vidmptx_destroy(). This event will be signalled when a status change occurs on the VidMP[tx]. When the event is signalled the user must call sm_vidmptx_status() to discover the nature of the status change.

Fields

vidmptx (Deprecated): The VidMP[tx]
event (Deprecated): The event identifier

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vidmptx_status

This function is deprecated.

Prototype Definition

int sm_vidmptx_status(struct sm_vidmptx_status_parms *statusp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_status_parms {
	tSMVidMPtxId vidmptx;					/* in */
	enum kSMVidMPtxStatus {
		kSMVidMPtxStatusRunning,
		kSMVidMPtxStatusStopped,
		kSMVidMPtxStatusSSRC,
		kSMVidMPtxStatusInternalError,
	} status;						/* out */
	union {
		struct {
			int ssrc;				/* out */
		} ssrc;						/* out */
		struct {
			int num_errors;				/* out */
		} internal_error;				/* out */
	} u;							/* out */
} SM_VIDMPTX_STATUS_PARMS;

Description

Returns the current status of the VidMP[tx] or an error to indicate that a problem occurred during start-up.

When the event, obtained from sm_vidmptx_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 VidMP[tx].

Fields

vidmptx (Deprecated)

The VidMP[tx] to interrogate

status (Deprecated)

One of these values:

kSMVidMPtxStatusRunning: Indicates that there is nothing significant to report
kSMVidMPtxStatusStopped: Indicates that the VidMP[tx] has stopped transmitting RTP and that it is safe to destroy
kSMVidMPtxStatusSSRC: Indicates that the SSRC value has been chosen. The value is given in the ssrc field.
kSMVidMPtxStatusInternalError: Indicates that the VidMP[tx] encountered one or more internal errors when processing the incoming AVF stream. These errors will result in the media packet stream output from the VidMP[tx] missing some data. Note that such errors are not fatal - the VidMP[tx] continues to run. These status reports are throttled in order to maintain a sensibly low rate of reporting even in the event of a high rate of errors.

u (Deprecated)

Additional information relating to the current status of the VidMP[tx]

This field is only valid if the status is kSMVidMPtxStatusSSRC.

ssrc: The SSRC value chosen.

internal_error

This field is only valid if the status is kSMVidMPtxStatusInternalError

num_errors: The number of internal errors encountered by the VidMP[tx] covered by this status report.

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 VidMP[tx]

Prosody RTP processing: API: sm_vidmptx_stop

This function is deprecated.

Prototype Definition

int sm_vidmptx_stop(struct sm_vidmptx_stop_parms *stopp)

Parameters

a structure of the following type:

typedef struct sm_vidmptx_stop_parms {
	tSMVidMPtxId vidmptx;					/* in */
} SM_VIDMPTX_STOP_PARMS;

Description

Requests that a VidMP[tx] stops executing. The user will be notified that a VidMP[tx] has terminated by a final status, kSMVidMPtxStatusStopped, from sm_vidmptx_status(). Once the stopped status notification has been received the VidMP[tx] can be destroyed using sm_vidmptx_destroy().

Once the VidMP[tx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_vidmptx_destroy() is called.

Fields

vidmptx (Deprecated): A tSMVidMPtxId that has been previously created by a call to sm_vidmptx_create().

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmprx_config_codec

This function is deprecated.

Prototype Definition

int sm_vmprx_config_codec(struct sm_vmprx_codec_parms *codecp)

Parameters

a structure of the following type:

typedef struct sm_vmprx_codec_parms {
	tSMVMPrxId vmprx;					/* in */
	enum kSMCodecType {
		kSMCodecTypeAlaw,
		kSMCodecTypeMulaw,
		kSMCodecTypeG729AB,
		kSMCodecTypeRFC2833,
		kSMCodecTypeComfortNoise,
	} codec;							/* in */
	tSM_INT payload_type;					/* in */
	enum kSMPLCMode plc_mode;				/* in */
} SM_VMPRX_CODEC_PARMS;

Description

This function is deprecated because it will not be updated to add any new codecs or new features for the codecs it covers. The codecs it covers can also be configured using sm_vmprx_config_codec_alaw(), sm_vmprx_config_codec_comfort_noise(), sm_vmprx_config_codec_g729ab(), sm_vmprx_config_codec_mulaw(), and sm_vmprx_config_codec_rfc2833() and new codecs will be added by adding new functions for each codec.

Configures the specified codec to the VMP[rx] setting the payload type mapping to payload_type.

If the call completes successfully, RTP packets arriving at the VMP[rx] with a payload type that matches a mapped type will be decoded using the selected codec.

If a codec is given the payload type -1 the codec is no longer valid for this RTP session, unless it is subsequently reconfigured.

Fields

vmprx (Deprecated)

The VMP[rx] to which to add the codec

codec (Deprecated)

The codec to be configured

One of these values:

kSMCodecTypeAlaw: G711 A-law codec.
kSMCodecTypeMulaw: G711 Mu-law codec.
kSMCodecTypeG729AB: G729 AB codec.
kSMCodecTypeRFC2833: RFC 2833 tones.
kSMCodecTypeComfortNoise: Comfort noise generation.

payload_type (Deprecated)

The payload type identifer for the selected codec (see IETF RFC 3550 section 13). Supplying a value of -1 will remove any payload type configuration from the specified codec.

plc_mode (Deprecated)

Enables or disables PLC (packet loss concealment) as appropriate for the configured codec

One of these values:

kSMPLCModeDisabled: PLC Disabled
kSMPLCModeEnabled: PLC Enabled

Returns

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

ERR_SM_DEVERR - device error

Prosody RTP processing: API: sm_vmptx_config_codec

This function is deprecated.

Prototype Definition

int sm_vmptx_config_codec(struct sm_vmptx_codec_parms *codecp)

Parameters