oRTP Reference Manual
<<< Previous Page | Home | Up |

# Telephone events (RFC2833)

## Name

Telephone events (RFC2833) --

## Synopsis

    #include <telephonyevents.h>

    struct      telephone_event;
    gint        rtp_session_telephone_events_supported
                                                (RtpSession *session);
    mblk_t*     rtp_session_create_telephone_event_packet
                                                (RtpSession *session,
                                                 int start);
    gint        rtp_session_add_telephone_event (RtpSession *session,
                                                 mblk_t *packet,
                                                 guchar event,
                                                 gint end,
                                                 guchar volume,
                                                 guint16 duration);
    gint        rtp_session_read_telephone_event
                                                (RtpSession *session,
                                                 mblk_t *packet,
                                                 telephone_event_t **tab);
    gint        rtp_session_send_dtmf           (RtpSession *session,
                                                 gchar dtmf,
                                                 guint32 userts);

## Description

## Details

### struct telephone_event

    struct telephone_event
    {
    #ifdef WORDS_BIGENDIAN
    	guchar event;
    	guchar E:1;
    	guchar R:1;
    	guchar volume:6;
    	guint16 duration;
    #else
    	guint16 duration;
    	guchar R:1;
    	guchar E:1;
    	guchar volume:6;
    	guchar event;
    #endif
    };

### rtp_session_telephone_events_supported ()

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

    gint        rtp_session_add_telephone_event (RtpSession *session,
                                                 mblk_t *packet,
                                                 guchar event,
                                                 gint end,
                                                 guchar volume,
                                                 guint16 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 ()

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

    gint        rtp_session_send_dtmf           (RtpSession *session,
                                                 gchar dtmf,
                                                 guint32 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.

<<< Previous Page | Home | Up |
Multiplexing sessions (in a one thread design) |