DTMF dialstring interpreter: telepathy-glib API Reference Manual

DTMF dialstring interpreter

DTMF dialstring interpreter — Converts a dialstring into a timed sequence of events

Functions

TpDTMFPlayer *	tp_dtmf_player_new ()
gboolean	tp_dtmf_player_play ()
void	tp_dtmf_player_cancel ()
gboolean	tp_dtmf_player_is_active ()

Signals

void	finished	Run Last
void	started-tone	Run Last
void	stopped-tone	Run Last
void	tones-deferred	Run Last

Types and Values

struct

TpDTMFPlayer

Object Hierarchy

    GObject
    ╰── TpDTMFPlayer

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

Telepathy offers two APIs for DTMF events: user interfaces can either call the StartTone and StopTone methods (appropriate if the user is pressing hardware or on-screen buttons in real time), or call MultipleTones or set InitialTones (appropriate if a stored dialstring is in use).

TpDTMFPlayer provides common code for connection managers that need to turn MultipleTones or InitialTones received from a UI into a sequence of start and stop events for the underlying protocol.

Functions

tp_dtmf_player_new ()

TpDTMFPlayer *
tp_dtmf_player_new (void);

Returns

a new DTMF interpreter.

[transfer full]

Since: 0.13.3

tp_dtmf_player_play ()

gboolean
tp_dtmf_player_play (TpDTMFPlayer *self,
                     const gchar *tones,
                     guint tone_ms,
                     guint gap_ms,
                     guint pause_ms,
                     GError **error);

Start to play a sequence of tones, by emitting the “started-tone” and “stopped-tone” signals.

If tp_dtmf_player_is_active() would return TRUE, this method raises TP_ERROR_SERVICE_BUSY and does not play anything, and the previous sequence continues to play.

The recognised characters are 0-9, A-D,

and * (which play the corresponding DTMF event), P, X and comma (which

each pause for pause_ms milliseconds), and W (which stops interpretation of the string and emits “tones-deferred” with the rest of the string). The corresponding lower-case letters are also allowed. If tones contains any other characters, this method raises TP_ERROR_INVALID_ARGUMENT and does not play anything.

Parameters

self	a DTMF interpreter
tones	a sequence of tones or other events
tone_ms	length of a tone (0-9, A-D, # or *) in milliseconds, which must be positive; typically 250
gap_ms	length of the gap between two tones, which must be positive; typically 100
pause_ms	length of the pause produced by P, X or comma, which must be positive; typically 3000
error	used to raise an error

Returns

TRUE on success, FALSE (setting error ) on failure

Since: 0.13.3

tp_dtmf_player_cancel ()

void
tp_dtmf_player_cancel (TpDTMFPlayer *self);

If tones were being played, stop the current tone (if any), stop playing subsequent tones, and emit “finished”.

Otherwise, do nothing.

Parameters

self

a DTMF interpreter

Since: 0.13.3

tp_dtmf_player_is_active ()

gboolean
tp_dtmf_player_is_active (TpDTMFPlayer *self);

Parameters

self

a DTMF interpreter

Returns

TRUE if a sequence of tones is currently playing

Since: 0.13.3

Types and Values

struct TpDTMFPlayer

struct TpDTMFPlayer;

An object to convert a string of characters representing DTMF tones into timed start and stop events.

Typically, a connection manager should instantiate one TpDTMFPlayer for each StreamedMedia or Call channel that supports DTMF.

The “started-tone” and “stopped-tone” signals should be connected to some way to play a tone, either directly or by emitting signals from the StreamHandler interface.

The “tones-deferred” signal should trigger emission of TonesDeferred.

The “finished” signal indicates that the current sequence of tones has finished.

Since: 0.13.3

Signal Details

The `“finished”` signal

void
user_function (TpDTMFPlayer *self,
               gboolean      cancelled,
               gpointer      user_data)

Emitted when playback stops, either because the end of the sequence was reached, tp_dtmf_player_cancel() was called, or a 'W' or 'w' character was encountered.

Parameters

self	the TpDTMFPlayer
cancelled	`TRUE` if playback was cancelled with `tp_dtmf_player_cancel()`
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 0.13.3

The `“started-tone”` signal

void
user_function (TpDTMFPlayer *self,
               guint         event,
               gpointer      user_data)

Emitted at the beginning of each tone.

Parameters

self	the TpDTMFPlayer
event	a `G_TYPE_UINT` representing the tone being played
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“stopped-tone”` signal

void
user_function (TpDTMFPlayer *self,
               gpointer      user_data)

Emitted at the end of each tone.

Parameters

self	the TpDTMFPlayer
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 0.13.3

The `“tones-deferred”` signal

void
user_function (TpDTMFPlayer *self,
               gchar        *tones,
               gpointer      user_data)

Emitted just before “finished” if a 'W' or 'w' character is encountered before the end of a dial string. The connection manager is expected to wait for the user to confirm, then call tp_dtmf_player_play() again, using this signal's argument as the new dial string.

Parameters

self	the TpDTMFPlayer
tones	the remaining tones, starting from just after the 'W' or 'w'
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 0.13.3