|  |  |  | telepathy-glib API Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
| DTMF dialstring interpreterDTMF dialstring interpreter — Converts a dialstring into a timed sequence of events | 
#include <telepathy-glib/telepathy-glib.h> struct TpDTMFPlayer; TpDTMFPlayer * tp_dtmf_player_new (void); gboolean tp_dtmf_player_play (TpDTMFPlayer *self,const gchar *tones,guint tone_ms,guint gap_ms,guint pause_ms,GError **error); void tp_dtmf_player_cancel (TpDTMFPlayer *self); gboolean tp_dtmf_player_is_active (TpDTMFPlayer *self);
"finished" :Run Last"started-tone" :Run Last"stopped-tone" :Run Last"tones-deferred" :Run Last
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.
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
TpDTMFPlayer *      tp_dtmf_player_new                  (void);
| Returns : | a new DTMF interpreter. [transfer full] | 
Since 0.13.3
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.
| 
 | a DTMF interpreter | 
| 
 | a sequence of tones or other events | 
| 
 | length of a tone (0-9, A-D, # or *) in milliseconds, which must be positive; typically 250 | 
| 
 | length of the gap between two tones, which must be positive; typically 100 | 
| 
 | length of the pause produced by P, X or comma, which must be positive; typically 3000 | 
| 
 | used to raise an error | 
| Returns : | TRUEon success,FALSE(settingerror) on failure | 
Since 0.13.3
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.
| 
 | a DTMF interpreter | 
Since 0.13.3
gboolean            tp_dtmf_player_is_active            (TpDTMFPlayer *self);
| 
 | a DTMF interpreter | 
| Returns : | TRUEif a sequence of tones is currently playing | 
Since 0.13.3
"finished" signalvoid                user_function                      (TpDTMFPlayer *self,
                                                        gboolean      cancelled,
                                                        gpointer      user_data)      : Run Last
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.
| 
 | the TpDTMFPlayer | 
| 
 | TRUEif playback was cancelled withtp_dtmf_player_cancel() | 
| 
 | user data set when the signal handler was connected. | 
Since 0.13.3
"started-tone" signalvoid                user_function                      (TpDTMFPlayer *self,
                                                        guint         event,
                                                        gpointer      user_data)      : Run Last
Emitted at the beginning of each tone.
| 
 | the TpDTMFPlayer | 
| 
 | a G_TYPE_UINTrepresenting the tone being played | 
| 
 | user data set when the signal handler was connected. | 
"stopped-tone" signalvoid                user_function                      (TpDTMFPlayer *self,
                                                        gpointer      user_data)      : Run Last
Emitted at the end of each tone.
| 
 | the TpDTMFPlayer | 
| 
 | user data set when the signal handler was connected. | 
Since 0.13.3
"tones-deferred" signalvoid                user_function                      (TpDTMFPlayer *self,
                                                        gchar        *tones,
                                                        gpointer      user_data)      : Run Last
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.
| 
 | the TpDTMFPlayer | 
| 
 | the remaining tones, starting from just after the 'W' or 'w' | 
| 
 | user data set when the signal handler was connected. | 
Since 0.13.3