Telephone events (RFC2833)

Name

Telephone events (RFC2833) -- 

Synopsis


#include <telephonyevents.h>


struct      telephone_event;
int         rtp_session_telephone_events_supported
                                            (RtpSession *session);
mblk_t*     rtp_session_create_telephone_event_packet
                                            (RtpSession *session,
                                             int start);
int         rtp_session_add_telephone_event (RtpSession *session,
                                             mblk_t *packet,
                                             uint8_t event,
                                             int end,
                                             uint8_t volume,
                                             uint16_t duration);
int         rtp_session_read_telephone_event
                                            (RtpSession *session,
                                             mblk_t *packet,
                                             telephone_event_t **tab);
int         rtp_session_send_dtmf           (RtpSession *session,
                                             char dtmf,
                                             uint32_t userts);

Description

Details

struct telephone_event

struct telephone_event {
#ifdef ORTP_BIGENDIAN
	uint32_t event:8;
	uint32_t E:1;
	uint32_t R:1;
	uint32_t volume:6;
	uint32_t duration:16;
#else
	uint32_t event:8;
	uint32_t volume:6;
	uint32_t R:1;
	uint32_t E:1;
	uint32_t duration:16;
#endif
};


rtp_session_telephone_events_supported ()

int         rtp_session_telephone_events_supported
                                            (RtpSession *session);

Tells whether telephony events payload type is supported within the context of the rtp session.

session :

a rtp session

Returns :

the payload type number used for telephony events if found, -1 if not found.


rtp_session_create_telephone_event_packet ()

mblk_t*     rtp_session_create_telephone_event_packet
                                            (RtpSession *session,
                                             int start);

Allocates a new rtp packet to be used to add named telephony events. The application can use then rtp_session_add_telephone_event() to add named events to the packet. Finally the packet has to be sent with rtp_session_sendm_with_ts().

session :

a rtp session.

start :

boolean to indicate if the marker bit should be set.

Returns :

a message block containing the rtp packet if successfull, NULL if the rtp session cannot support telephony event (because the rtp profile it is bound to does not include a telephony event payload type).


rtp_session_add_telephone_event ()

int         rtp_session_add_telephone_event (RtpSession *session,
                                             mblk_t *packet,
                                             uint8_t event,
                                             int end,
                                             uint8_t volume,
                                             uint16_t duration);

Adds a named telephony event to a rtp packet previously allocated using rtp_session_create_telephone_event_packet().

session :

a rtp session.

packet :

a rtp packet as a mblk_t

event :

the event type as described in rfc2833, ie one of the TEV_ macros.

end :

boolean to indicate if the end bit should be set. (end of tone)

volume :

the volume of the telephony tone, as described in rfc2833

duration :

the duration of the telephony tone, in timestamp unit.

Returns :

0 on success.


rtp_session_read_telephone_event ()

int         rtp_session_read_telephone_event
                                            (RtpSession *session,
                                             mblk_t *packet,
                                             telephone_event_t **tab);

Reads telephony events from a rtp packet. *tab points to the beginning of the event buffer.

session :

a rtp session from which telephony events are received.

packet :

a rtp packet as a mblk_t.

tab :

the address of a pointer.

Returns :

the number of events in the packet if successfull, 0 if the packet did not contain telephony events.


rtp_session_send_dtmf ()

int         rtp_session_send_dtmf           (RtpSession *session,
                                             char dtmf,
                                             uint32_t userts);

This functions creates telephony events packets for dtmf and sends them. It uses rtp_session_create_telephone_event_packet() and rtp_session_add_telephone_event() to create them and finally rtp_session_sendm_with_ts() to send them.

session :

a rtp session

dtmf :

a character meaning the dtmf (ex: '1', '#' , '9' ...)

userts :

the timestamp

Returns :

0 if successfull, -1 if the session cannot support telephony events or if the dtmf given as argument is not valid.