The following functions are provided by the Prosody RTP processing API:
| API call | W | Description |
|---|---|---|
| sm_rtcphand_config_bandwidth() | P | Configure bandwidth for a RTCP handler to use |
| sm_rtcphand_config_reports() | P | Configure local reporting by an RTCP handler |
| sm_rtcphand_config_sdes() | P | Configure an RTCP SDES item |
| sm_rtcphand_create() | P | Create RTCP handler |
| sm_rtcphand_destroy() | P | Destroy a previously allocated RTCP handler |
| sm_rtcphand_get_data() | P | Get data from an RTCP handler |
| sm_rtcphand_get_event() | P | Obtain an event for a RTCP handler |
| sm_rtcphand_request_statistics() | P | Provoke an RTCP handler into providing statistics |
| sm_rtcphand_status() | P | Determine RTCP handler status |
| sm_vmprx_config_authentication_hmac_sha1() | T | Configure a VMP[rx] to use HMAC-SHA1 authentication |
| sm_vmprx_config_authentication_null() | T | Configure a VMP[rx] to use no authentication |
| sm_vmprx_config_codec() | T | Configure a codec for a VMP[rx] |
| sm_vmprx_config_codec_alaw() | T | Configure an A-law codec for a VMP[rx] |
| sm_vmprx_config_codec_amrnb() | T | Configure an AMR-NB codec for a VMP[rx] |
| sm_vmprx_config_codec_comfort_noise() | T | Configure an RFC 3389 comfort noise codec for a VMP[rx] |
| sm_vmprx_config_codec_evrc() | T | Configure an EVRC codec for a VMP[rx] |
| sm_vmprx_config_codec_g723_1() | T | Configure a G.723.1 codec for a VMP[rx] |
| sm_vmprx_config_codec_g726() | T | Configure a G.726 codec for a VMP[rx] |
| sm_vmprx_config_codec_g728() | T | Configure a G.728 codec for a VMP[rx] |
| sm_vmprx_config_codec_g729ab() | T | Configure a G.729 AB codec for a VMP[rx] |
| sm_vmprx_config_codec_g729i() | T | Configure a G.729 I codec for a VMP[rx] |
| sm_vmprx_config_codec_gsmefr() | T | Configure a GSM-EFR codec for a VMP[rx] |
| sm_vmprx_config_codec_gsmfr() | T | Configure a GSM-FR codec for a VMP[rx] |
| sm_vmprx_config_codec_ilbc() | T | Configure an iLBC codec for a VMP[rx] |
| sm_vmprx_config_codec_melpe() | P | Configure a MELPe codec for a VMP[rx] |
| sm_vmprx_config_codec_mulaw() | T | Configure an mu-law codec for a VMP[rx] |
| sm_vmprx_config_codec_rfc2833() | T | Configure an RFC2833 codec for a VMP[rx] |
| sm_vmprx_config_codec_rfc4040() | T | Configure an RFC4040 codec for a VMP[rx] |
| sm_vmprx_config_codec_smv() | P | Configure an SMV codec for a VMP[rx] |
| sm_vmprx_config_dataloss() | T | Configure data loss threshold for a VMP[rx] |
| sm_vmprx_config_encryption_aes_cm() | T | Configure a VMP[rx] to use AES-CM encryption |
| sm_vmprx_config_encryption_aes_f8() | T | Configure a VMP[rx] to use AES-f8 encryption |
| sm_vmprx_config_encryption_null() | T | Configure a VMP[rx] to use no encryption |
| sm_vmprx_config_jitter() | T | Configure the jitter buffer belonging to a VMP[rx] |
| sm_vmprx_config_tones() | T | Configure tone handling for a VMP[rx] |
| sm_vmprx_create() | T | Create a VMP[rx] endpoint |
| sm_vmprx_destroy() | T | Destroy a previously allocated VMP[rx] |
| sm_vmprx_get_datafeed() | T | Obtain a datafeed from a VMP[rx] |
| sm_vmprx_get_event() | T | Obtain an event for a VMP[rx] |
| sm_vmprx_get_ports() | T | Get the RTP and RTCP port information from a VMP[rx] |
| sm_vmprx_set_rtcphand() | P | Configures the RTCP handler which handles RTCP for the VMP[rx] |
| sm_vmprx_status() | T | Determine VMP[rx] status |
| sm_vmprx_stop() | T | Instructs a VMP[rx] to stop processing RTP |
| sm_vmptx_config() | T | Configure the basic options for a VMP[tx] |
| sm_vmptx_config_authentication_hmac_sha1() | T | Configure a VMP[tx] to use HMAC-SHA1 authentication |
| sm_vmptx_config_authentication_null() | T | Configure a VMP[tx] to use no authentication |
| sm_vmptx_config_codec() | T | Configure a codec for a VMP[tx] |
| sm_vmptx_config_codec_alaw() | T | Configure an A-law codec for a VMP[tx] |
| sm_vmptx_config_codec_amrnb() | T | Configure a VMP[tx] to use AMR-NB |
| sm_vmptx_config_codec_amrnb_mode() | T | Set the mode of an AMR-NB codec for a VMP[tx] |
| sm_vmptx_config_codec_comfort_noise() | T | Configure RFC 3389 comfort noise codec for a VMP[tx] |
| sm_vmptx_config_codec_evrc() | T | Configure a VMP[tx] to use EVRC |
| sm_vmptx_config_codec_g723_1() | T | Configure a VMP[tx] to use G.723.1 |
| sm_vmptx_config_codec_g726() | T | Configure a VMP[tx] to use G.726 |
| sm_vmptx_config_codec_g728() | T | Configure a VMP[tx] to use G.728 |
| sm_vmptx_config_codec_g729ab() | T | Configure G.729 AB codec for a VMP[tx] |
| sm_vmptx_config_codec_g729i() | T | Configure G.729 I codec for a VMP[tx] |
| sm_vmptx_config_codec_gsmefr() | T | Configure a VMP[tx] to use GSM-EFR |
| sm_vmptx_config_codec_gsmfr() | T | Configure a VMP[tx] to use GSM-FR |
| sm_vmptx_config_codec_ilbc() | T | Configure a VMP[tx] to use iLBC |
| sm_vmptx_config_codec_melpe() | P | Configure a MELPe codec for a VMP[tx] |
| sm_vmptx_config_codec_mulaw() | T | Configure an mu-law codec for a VMP[tx] |
| sm_vmptx_config_codec_rfc2833() | T | Configure RFC 2833 codec for a VMP[tx] |
| sm_vmptx_config_codec_rfc4040() | T | Configure RFC 4040 codec for a VMP[tx] |
| sm_vmptx_config_codec_smv() | P | Configure a VMP[tx] to use SMV |
| sm_vmptx_config_encryption_aes_cm() | T | Configure a VMP[tx] to use AES-CM encryption |
| sm_vmptx_config_encryption_aes_f8() | T | Configure a VMP[tx] to use AES-f8 encryption |
| sm_vmptx_config_encryption_null() | T | Configure a VMP[tx] to use no encryption |
| sm_vmptx_config_tones() | T | Configure tone handling for a VMP[tx] |
| sm_vmptx_create() | T | Create a VMP[tx] endpoint |
| sm_vmptx_create_toneset() | T | Configure a set of tones for use with RFC 2833 generation. |
| sm_vmptx_datafeed_connect() | T | Connect a VMP[tx] to a datafeed |
| sm_vmptx_destroy() | T | Destroy a previously allocated VMP[tx] |
| sm_vmptx_destroy_toneset() | T | Destroy a toneset |
| sm_vmptx_generate_tones() | T | Generate rfc2833 tones using a VMP[tx] |
| sm_vmptx_get_event() | T | Obtain an event for a VMP[tx] |
| sm_vmptx_set_csrc() | P | Configures the CSRC list sent by the VMP[tx] |
| sm_vmptx_set_rtcphand() | P | Configures the RTCP handler which handles RTCP for the VMP[tx] |
| sm_vmptx_status() | T | Determine VMP[tx] status |
| sm_vmptx_stop() | T | Instructs a VMP[tx] to stop sending RTP |
Key to W column:
| P | Preliminary documentation - this functionality is under development. It could be changed or withdrawn, and may not be implemented in this release |
|---|---|
| T | Only in Prosody version 2 (TiNG) |
This document is also available as separate pages for each function.
This function is only in Preliminary Documentation.
int sm_rtcphand_config_bandwidth(struct sm_rtcphand_config_bandwidth_parms *rvp)
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;
Configures the RTCP bandwidth.
rtcp_bw specified in
IETF RFC 3550.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_config_reports(struct sm_rtcphand_config_reports_parms *rvp)
typedef struct sm_rtcphand_config_reports_parms {
tSMRTCPHandId rtcphand; /* in */
tSM_INT reports; /* in */
} SM_RTCPHAND_CONFIG_REPORTS_PARMS;
Configures the reports to be locally generated by RTCP. The reports are collected using sm_rtcphand_get_data().
N indicating that report type N is to
be generated. The type numbers are the same as for
sm_rtcphand_get_data().
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_config_sdes(struct sm_rtcphand_config_sdes_parms *rvp)
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;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_create(struct sm_rtcphand_create_parms *rtcphandp)
typedef struct sm_rtcphand_create_parms {
tSMRTCPHandId rtcphand; /* out */
tSMModuleId module; /* in */
} SM_RTCPHAND_CREATE_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_destroy(tSMRTCPHandId rtcphand)
Destroys rtcphand and invalidates the tSMRTCPHandId.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_get_data(struct sm_rtcphand_get_data_parms *datap)
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;
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:
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() |
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_get_event(struct sm_rtcphand_event_parms *eventp)
typedef struct sm_rtcphand_event_parms {
tSMRTCPHandId rtcphand; /* in */
tSMEventId event; /* out */
} SM_RTCPHAND_EVENT_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_request_statistics(struct sm_rtcphand_request_statistics_parms *rrsp)
typedef struct sm_rtcphand_request_statistics_parms {
tSMRTCPHandId rtcphand; /* in */
tSM_INT statcode; /* in */
} SM_RTCPHAND_REQUEST_STATISTICS_PARMS;
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()
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_rtcphand_status(struct sm_rtcphand_status_parms *statusp)
typedef struct sm_rtcphand_status_parms {
tSMRTCPHandId rtcphand; /* in */
enum kSMRTCPHandStatus {
kSMRTCPHandStatusRunning,
} status; /* out */
} SM_RTCPHAND_STATUS_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_authentication_hmac_sha1(struct sm_vmprx_config_authentication_hmac_sha1_parms *pp)
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;
Configures a VMP[rx] to use HMAC-SHA1 authentication, as defined in IETF RFC 3711.
This requires the module securertp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_authentication_null(struct sm_vmprx_config_authentication_null_parms *pp)
typedef struct sm_vmprx_config_authentication_null_parms {
tSMVMPrxId vmprx; /* in */
} SM_VMPRX_CONFIG_AUTHENTICATION_NULL_PARMS;
Disables any authentication which may have been in use by a VMP[rx].
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec(struct sm_vmprx_codec_parms *codecp)
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 {
kSMPLCModeDisabled,
kSMPLCModeEnabled,
} plc_mode; /* in */
} SM_VMPRX_CODEC_PARMS;
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_g726(), 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.
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 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.
-1 will remove any payload type configuration from the
specified codec.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_alaw(struct sm_vmprx_codec_alaw_parms *codecp)
typedef struct sm_vmprx_codec_alaw_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT payload_type; /* in */
enum kSMPLCMode plc_mode; /* in */
} SM_VMPRX_CODEC_ALAW_PARMS;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_amrnb(struct sm_vmprx_codec_amrnb_parms *codecp)
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 */
} SM_VMPRX_CODEC_AMRNB_PARMS;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_comfort_noise(struct sm_vmprx_codec_comfort_noise_parms *codecp)
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;
Configures a comfort noise 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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_evrc(struct sm_vmprx_codec_evrc_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_g723_1(struct sm_vmprx_codec_g723_1_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_g726(struct sm_vmprx_codec_g726_parms *codecp)
typedef struct sm_vmprx_codec_g726_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT payload_type; /* in */
tSM_INT bits; /* in */
enum kSMPLCMode plc_mode; /* in */
} SM_VMPRX_CODEC_G726_PARMS;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_g728(struct sm_vmprx_codec_g728_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_g729ab(struct sm_vmprx_codec_g729ab_parms *codecp)
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;
Configures an G.729 AB 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.
This requires the module g729ab to have been downloaded.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_g729i(struct sm_vmprx_codec_g729i_parms *codecp)
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;
Configures an G.729 I 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.
This requires the module g729i to have been downloaded.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_gsmefr(struct sm_vmprx_codec_gsmefr_parms *codecp)
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;
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.
This requires the module gsm-efr to have been downloaded.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_gsmfr(struct sm_vmprx_codec_gsmfr_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_ilbc(struct sm_vmprx_codec_ilbc_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_vmprx_config_codec_melpe(struct sm_vmprx_codec_melpe_parms *codecp)
typedef struct sm_vmprx_codec_melpe_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT payload_type; /* in */
} SM_VMPRX_CODEC_MELPE_PARMS;
Configures a melpe 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.
This requires the module melpe to have been downloaded.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_mulaw(struct sm_vmprx_codec_mulaw_parms *codecp)
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;
Configures a mu-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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_rfc2833(struct sm_vmprx_codec_rfc2833_parms *codecp)
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;
Configures an IETF RFC 2833 codec on 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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_codec_rfc4040(struct sm_vmprx_codec_rfc4040_parms *codecp)
typedef struct sm_vmprx_codec_rfc4040_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT payload_type; /* in */
} SM_VMPRX_CODEC_RFC4040_PARMS;
Configures an IETF RFC 4040 codec on 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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_vmprx_config_codec_smv(struct sm_vmprx_codec_smv_parms *codecp)
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;
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.
-1 will remove any payload type configuration from the
codec preventing its use.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_dataloss(struct sm_vmprx_dataloss_parms *codecp)
typedef struct sm_vmprx_dataloss_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT loss_threshold; /* in */
} SM_VMPRX_DATALOSS_PARMS;
Configures the data loss threshold for a VMP[rx]. When the VMP[rx] s 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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_encryption_aes_cm(struct sm_vmprx_config_encryption_aes_cm_parms *pp)
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;
Configures a VMP[rx] to use AES-CM encryption, as defined in IETF RFC 3711.
This requires the module securertp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_encryption_aes_f8(struct sm_vmprx_config_encryption_aes_f8_parms *pp)
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;
Configures a VMP[rx] to use AES-f8 encryption, as defined in IETF RFC 3711.
This requires the module rtcp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_encryption_null(struct sm_vmprx_config_encryption_null_parms *pp)
typedef struct sm_vmprx_config_encryption_null_parms {
tSMVMPrxId vmprx; /* in */
} SM_VMPRX_CONFIG_ENCRYPTION_NULL_PARMS;
Disables any encryption which may have been in use by a VMP[rx].
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_jitter(struct sm_vmprx_jitter_parms *jitterp)
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;
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..
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_config_tones(struct sm_vmprx_tone_parms *tonep)
typedef struct sm_vmprx_tone_parms {
tSMVMPrxId vmprx; /* in */
tSM_INT regen_tones; /* in */
tSM_INT detect_tones; /* in */
} SM_VMPRX_TONE_PARMS;
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.
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.
This requires the module vtdet to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_create(struct sm_vmprx_create_parms *vmprxp)
typedef struct sm_vmprx_create_parms {
tSMVMPrxId vmprx; /* out */
tSMModuleId module; /* in */
struct in_addr address; /* in */
} SM_VMPRX_CREATE_PARMS;
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 a port number for incoming RTP data, this information may be obtained by calling sm_vmprx_get_ports() or 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 cofiguration supplied by sm_vmprx_config_codec(). 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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_destroy(tSMVMPrxId vmprx)
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_get_datafeed(struct sm_vmprx_datafeed_parms *datafeedp)
typedef struct sm_vmprx_datafeed_parms {
tSMVMPrxId vmprx; /* in */
tSMDatafeedId datafeed; /* out */
} SM_VMPRX_DATAFEED_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_get_event(struct sm_vmprx_event_parms *eventp)
typedef struct sm_vmprx_event_parms {
tSMVMPrxId vmprx; /* in */
tSMEventId event; /* out */
} SM_VMPRX_EVENT_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_get_ports(struct sm_vmprx_port_parms *portp)
typedef struct sm_vmprx_port_parms {
tSMVMPrxId vmprx; /* in */
int RTP_port; /* out */
int RTCP_port; /* out */
struct in_addr address; /* out */
tSM_UT32 nowait; /* in */
} SM_VMPRX_PORT_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Preliminary Documentation.
int sm_vmprx_set_rtcphand(struct sm_vmprx_set_rtcphand_parms *rvp)
typedef struct sm_vmprx_set_rtcphand_parms {
tSMVMPrxId vmprx; /* in */
tSMRTCPHandId rtcphand; /* in */
} SM_VMPRX_SET_RTCPHAND_PARMS;
Configures the RTCP handler which handles RTCP for the VMP[rx]
kSMNullRTCPHandId,
means that no RTCP handler is to be used.
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_status(struct sm_vmprx_status_parms *statusp)
typedef struct sm_vmprx_status_parms {
tSMVMPrxId vmprx; /* in */
enum kSMVMPrxStatus {
kSMVMPrxStatusRunning,
kSMVMPrxStatusStopped,
kSMVMPrxStatusDetectTone,
kSMVMPrxStatusEndTone,
kSMVMPrxStatusGotPorts,
kSMVMPrxStatusNewSSRC,
} 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 */
} u; /* out */
} SM_VMPRX_STATUS_PARMS;
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].
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmprx_stop(struct sm_vmprx_stop_parms *stopp)
typedef struct sm_vmprx_stop_parms {
tSMVMPrxId vmprx; /* in */
} SM_VMPRX_STOP_PARMS;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmptx_config(struct sm_vmptx_config_parms *configp)
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;
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.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmptx_config_authentication_hmac_sha1(struct sm_vmptx_config_authentication_hmac_sha1_parms *pp)
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;
Configures a VMP[tx] to use HMAC-SHA1 authentication, as defined in IETF RFC 3711.
This requires the module securertp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmptx_config_authentication_null(struct sm_vmptx_config_authentication_null_parms *pp)
typedef struct sm_vmptx_config_authentication_null_parms {
tSMVMPtxId vmptx; /* in */
} SM_VMPTX_CONFIG_AUTHENTICATION_NULL_PARMS;
Disables any authentication which may have been in use by a VMP[tx].
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_vmptx_config_codec(struct sm_vmptx_codec_parms *codecp)
typedef struct sm_vmptx_codec_parms {
tSMVMPtxId vmptx; /* in */
enum kSMCodecType codec; /* in */
tSM_INT payload_type; /* in */
enum kSMVMPTxVADMode {
kSMVMPTxVADModeDisabled,
kSMVMPTxVADModeEnabled,
kSMVMPTxVADModeComfortNoise,
} VADMode; /* in *