Media channels

Media channels — client-side wrappers for the Streamed Media channel type, and the Call State, DTMF and Media Signalling interfaces

Synopsis

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

TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_start_tone
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Stream_ID,
                                                         guchar in_Event,
                                                         tp_cli_channel_interface_dtmf_callback_for_start_tone callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_stop_tone
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Stream_ID,
                                                         tp_cli_channel_interface_dtmf_callback_for_stop_tone callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_dtmf_callback_for_start_tone)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_dtmf_callback_for_stop_tone)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_multiple_tones
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Tones,
                                                         tp_cli_channel_interface_dtmf_callback_for_multiple_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_dtmf_callback_for_multiple_tones)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_sending_tones
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_sending_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_interface_dtmf_signal_callback_sending_tones)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_Tones,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_stopped_tones
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_stopped_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_interface_dtmf_signal_callback_stopped_tones)
                                                        (TpChannel *proxy,
                                                         gboolean arg_Cancelled,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_tones_deferred
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_tones_deferred callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_interface_dtmf_signal_callback_tones_deferred)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_Tones,
                                                         gpointer user_data,
                                                         GObject *weak_object);

void                (*tp_cli_channel_interface_hold_callback_for_get_hold_state)
                                                        (TpChannel *proxy,
                                                         guint out_HoldState,
                                                         guint out_Reason,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_hold_call_get_hold_state
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_interface_hold_callback_for_get_hold_state callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_hold_callback_for_request_hold)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_hold_call_request_hold
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         gboolean in_Hold,
                                                         tp_cli_channel_interface_hold_callback_for_request_hold callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_hold_signal_callback_hold_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_HoldState,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_interface_hold_connect_to_hold_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_hold_signal_callback_hold_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Description

This section documents the auto-generated C wrappers for the Streamed Media channel type, and the DTMF and Media Signalling interfaces which are optionally supported by channels of this type.

Streamed Media channels represent real-time audio or video streaming, including voice over IP, webcams, and telephony.

Channels of type Streamed Media may support the Media Signalling interface. If not, the connection manager is assumed to be presenting the media streams to the user automatically (for instance, in a connection manager like gnome-phone-manager or telepathy-snom that remotely controls a telephone, the phone's own speaker and microphone will probably be used directly).

If Media Signalling is supported, the Telepathy client is responsible for actually streaming the media, using the Media Signalling interface to provide signalling (connection managers might implement this interface in terms of Jingle or SDP, for instance). The Telepathy project suggests that client authors use the Farsight library for this; the glue between Media Signalling and Farsight is currently done in telepathy-stream-engine, an additional D-Bus service, but it will be provided as a library in future.

Channels of type Streamed Media may also support the DTMF and CallState interfaces.

Details

tp_cli_channel_interface_dtmf_call_start_tone ()

TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_start_tone
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Stream_ID,
                                                         guchar in_Event,
                                                         tp_cli_channel_interface_dtmf_callback_for_start_tone callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a StartTone method call.

<p>Start sending a DTMF tone to all eligible streams in the channel. Where possible, the tone will continue until <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols, it may only be possible to send events with a predetermined length. In this case, the implementation MAY emit a fixed-length tone, and the StopTone method call SHOULD return NotAvailable.</p> <tp:rationale> The client may wish to control the exact duration and timing of the tones sent as a result of user's interaction with the dialpad, thus starting and stopping the tone sending explicitly. </tp:rationale> <p>Tone overlaping or queueing is not supported, so this method can only be called if no DTMF tones are already being played.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Stream_ID :

Used to pass an 'in' argument: This argument is included for backwards compatibility and MUST be ignored by the implementations - the tone SHOULD be sent to all eligible streams in the channel.

in_Event :

Used to pass an 'in' argument: A numeric event code from the DTMF_Event enum.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_dtmf_call_stop_tone ()

TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_stop_tone
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Stream_ID,
                                                         tp_cli_channel_interface_dtmf_callback_for_stop_tone callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a StopTone method call.

Stop sending any DTMF tones which have been started using the <tp:member-ref>StartTone</tp:member-ref> or <tp:member-ref>MultipleTones</tp:member-ref> methods. If there is no current tone, this method will do nothing. If MultipleTones was used, the client should not assume the sending has stopped immediately; instead, the client should wait for the StoppedTones signal. <tp:rationale> On some protocols it might be impossible to cancel queued tones immediately. </tp:rationale>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Stream_ID :

Used to pass an 'in' argument: This argument is included for backwards compatibility and MUST be ignored by the implementations - the sending SHOULD be stoped in all eligible streams in the channel.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_dtmf_callback_for_start_tone ()

void                (*tp_cli_channel_interface_dtmf_callback_for_start_tone)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a StartTone method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_dtmf_callback_for_stop_tone ()

void                (*tp_cli_channel_interface_dtmf_callback_for_stop_tone)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a StopTone method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_dtmf_call_multiple_tones ()

TpProxyPendingCall * tp_cli_channel_interface_dtmf_call_multiple_tones
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Tones,
                                                         tp_cli_channel_interface_dtmf_callback_for_multiple_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a MultipleTones method call.

<p>Send multiple DTMF events to all eligible streams in the channel. Each tone will be played for an implementation-defined number of milliseconds (typically 250ms), followed by a gap before the next tone is played (typically 100ms). The duration and gap are defined by the protocol or connection manager.</p> <tp:rationale> <p>In cases where the client knows in advance the tone sequence it wants to send, it's easier to use this method than manually start and stop each tone in the sequence.</p> <p>The tone and gap lengths may need to vary for interoperability, according to the protocol and other implementations' ability to recognise tones. At the time of writing, GStreamer uses a minimum of 250ms tones and 100ms gaps when playing in-band DTMF in the normal audio stream, or 70ms tones and 50ms gaps when encoding DTMF as <code>audio/telephone-event</code>.</p> </tp:rationale> <p>Tone overlaping or queueing is not supported, so this method can only be called if no DTMF tones are already being played.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Tones :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A string representation of one or more DTMF events. Implementations of this method MUST support all of the following characters in this string:</p> <ul> <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#' correspond to the members of <tp:type>DTMF_Event</tp:type></li> <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an implementation-defined pause, typically for 3 seconds</li> <li>'w' or 'W' waits for the user to continue, by stopping interpretation of the string, and if there is more to be played, emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal with the rest of the string as its argument: see that signal for details</li> </ul>

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_dtmf_callback_for_multiple_tones ()

void                (*tp_cli_channel_interface_dtmf_callback_for_multiple_tones)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a MultipleTones method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_dtmf_connect_to_sending_tones ()

TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_sending_tones
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_sending_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SendingTones.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>DTMF tone(s)are being sent to all eligible streams in the channel. The signal is provided to indicating the fact that the streams are currently being used to send one or more DTMF tones, so any other media input is not getting through to the audio stream. It also serves as a cue for the <tp:member-ref>StopTone</tp:member-ref> method.</p>

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_interface_dtmf_signal_callback_sending_tones ()

void                (*tp_cli_channel_interface_dtmf_signal_callback_sending_tones)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_Tones,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal SendingTones.

proxy :

The proxy on which tp_cli_channel_interface_dtmf_connect_to_sending_tones() was called

arg_Tones :

DTMF string (one or more events) that is to be played.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_interface_dtmf_connect_to_stopped_tones ()

TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_stopped_tones
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_stopped_tones callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal StoppedTones.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>DTMF tones have finished playing on streams in this channel.</p>

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_interface_dtmf_signal_callback_stopped_tones ()

void                (*tp_cli_channel_interface_dtmf_signal_callback_stopped_tones)
                                                        (TpChannel *proxy,
                                                         gboolean arg_Cancelled,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal StoppedTones.

proxy :

The proxy on which tp_cli_channel_interface_dtmf_connect_to_stopped_tones() was called

arg_Cancelled :

True if the DTMF tones were actively cancelled via <tp:member-ref>StopTone</tp:member-ref>.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_interface_dtmf_connect_to_tones_deferred ()

TpProxySignalConnection * tp_cli_channel_interface_dtmf_connect_to_tones_deferred
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_dtmf_signal_callback_tones_deferred callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal TonesDeferred.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when 'w' or 'W', indicating &quot;wait for the user to continue&quot;, is encountered while playing a DTMF string queued by <tp:member-ref>MultipleTones</tp:member-ref> or <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events after the 'w', which have not yet been played, are placed in the <tp:member-ref>DeferredTones</tp:member-ref> property and copied into this signal's argument.</p> <p>When the channel handler is ready to continue, it MAY pass the value of <tp:member-ref>DeferredTones</tp:member-ref> to <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending. Alternatively, it MAY ignore the deferred tones, or even play different tones instead. Any deferred tones are discarded the next time a tone is played.</p> <p>This signal SHOULD NOT be emitted if there is nothing left to play, i.e. if the 'w' was the last character in the DTMF string.</p>

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_interface_dtmf_signal_callback_tones_deferred ()

void                (*tp_cli_channel_interface_dtmf_signal_callback_tones_deferred)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_Tones,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal TonesDeferred.

proxy :

The proxy on which tp_cli_channel_interface_dtmf_connect_to_tones_deferred() was called

arg_Tones :

The new non-empty value of <tp:member-ref>DeferredTones</tp:member-ref>.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_interface_hold_callback_for_get_hold_state ()

void                (*tp_cli_channel_interface_hold_callback_for_get_hold_state)
                                                        (TpChannel *proxy,
                                                         guint out_HoldState,
                                                         guint out_Reason,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a GetHoldState method call succeeds or fails.

proxy :

the proxy on which the call was made

out_HoldState :

Used to return an 'out' argument if error is NULL: The state of the channel (TpLocalHoldState)

out_Reason :

Used to return an 'out' argument if error is NULL: The reason why the channel is in that state (TpLocalHoldStateReason)

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_hold_call_get_hold_state ()

TpProxyPendingCall * tp_cli_channel_interface_hold_call_get_hold_state
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_interface_hold_callback_for_get_hold_state callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a GetHoldState method call.

Return whether the local user has placed the channel on hold.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_hold_callback_for_request_hold ()

void                (*tp_cli_channel_interface_hold_callback_for_request_hold)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a RequestHold method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_hold_call_request_hold ()

TpProxyPendingCall * tp_cli_channel_interface_hold_call_request_hold
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         gboolean in_Hold,
                                                         tp_cli_channel_interface_hold_callback_for_request_hold callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a RequestHold method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the channel be put on hold (be instructed not to send any media streams to you) or be taken off hold.</p> <p>If the connection manager can immediately tell that the requested state change could not possibly succeed, this method SHOULD return the NotAvailable error. If the requested state is the same as the current state, this method SHOULD return successfully without doing anything.</p> <p>Otherwise, this method SHOULD immediately set the hold state to Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold (as appropriate), emitting <tp:member-ref>HoldStateChanged</tp:member-ref> if this is a change, and return successfully.</p> <p>The eventual success or failure of the request is indicated by a subsequent HoldStateChanged signal, changing the hold state to Local_Hold_State_Held or Local_Hold_State_Unheld.</p> <p>If the channel has multiple streams, and the connection manager succeeds in changing the hold state of one stream but fails to change the hold state of another, it SHOULD attempt to revert all streams to their previous hold states.</p> <p>The following state transitions SHOULD be used, where appropriate:</p> <ul> <li>Successful hold: (Unheld, any reason) → (Pending_Hold, Requested) → (Held, Requested) </li> <li>Successful unhold: (Held, any reason) → (Pending_Unhold, Requested) → (Unheld, Requested) </li> <li>Attempting to unhold fails at the first attempt to acquire a resource: (Held, any reason) → (Pending_Unhold, Requested) → (Held, Resource_Not_Available) </li> <li>Attempting to unhold acquires one resource, but fails to acquire a second, and takes time to release the first: (Held, any reason) → (Pending_Unhold, Requested) → (Pending_Hold, Resource_Not_Available) → (Held, Resource_Not_Available) </li> </ul>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Hold :

Used to pass an 'in' argument: A boolean indicating whether or not the channel should be on hold

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_hold_signal_callback_hold_state_changed ()

void                (*tp_cli_channel_interface_hold_signal_callback_hold_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_HoldState,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal HoldStateChanged.

proxy :

The proxy on which tp_cli_channel_interface_hold_connect_to_hold_state_changed() was called

arg_HoldState :

The state of the channel (TpLocalHoldState)

arg_Reason :

The reason for the state change (TpLocalHoldStateReason)

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_interface_hold_connect_to_hold_state_changed ()

TpProxySignalConnection * tp_cli_channel_interface_hold_connect_to_hold_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_hold_signal_callback_hold_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal HoldStateChanged.

Emitted to indicate that the hold state has changed for this channel. This may occur as a consequence of you requesting a change with <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a result of a request from another process.

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

See Also

channel-group, TpChannel