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() |
| 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.
0 if call completed successfully, otherwise a standard error such as:
This function is part of the Prosody RTP processing API.