## DTMF dialstring interpreter

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

## Synopsis

    #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);

## Object Hierarchy

      GObject
       +----TpDTMFPlayer

## Signals

      "finished"                                       : Run Last
      "started-tone"                                   : Run Last
      "stopped-tone"                                   : Run Last
      "tones-deferred"                                 : Run Last

## 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.

## Details

### 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

### 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.

`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.

`self` : | a DTMF interpreter

Since 0.13.3

### tp_dtmf_player_is_active ()

    gboolean            tp_dtmf_player_is_active            (TpDTMFPlayer *self);

`self` : | a DTMF interpreter
Returns : | `TRUE` if a sequence of tones is currently playing

Since 0.13.3

## Signal Details

### The `"finished"` signal

    void                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.

`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.

Since 0.13.3

### The `"started-tone"` signal

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

Emitted at the beginning of each tone.

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

### The `"stopped-tone"` signal

    void                user_function                      (TpDTMFPlayer *self,
                                                            gpointer      user_data)      : Run Last

Emitted at the end of each tone.

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

Since 0.13.3

### The `"tones-deferred"` signal

    void                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.

`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.

Since 0.13.3