Channel Call interfaces: telepathy-glib API Reference Manual

Channel Call interfaces

Channel Call interfaces — client-side wrappers for call channels

Functions

TpProxyPendingCall *	tp_cli_channel_type_call_call_accept ()
TpProxyPendingCall *	tp_cli_channel_type_call_call_add_content ()
TpProxyPendingCall *	tp_cli_channel_type_call_call_hangup ()
TpProxyPendingCall *	tp_cli_channel_type_call_call_set_queued ()
TpProxyPendingCall *	tp_cli_channel_type_call_call_set_ringing ()
void	(*tp_cli_channel_type_call_callback_for_accept) ()
void	(*tp_cli_channel_type_call_callback_for_add_content) ()
void	(*tp_cli_channel_type_call_callback_for_hangup) ()
void	(*tp_cli_channel_type_call_callback_for_set_queued) ()
void	(*tp_cli_channel_type_call_callback_for_set_ringing) ()
TpProxySignalConnection *	tp_cli_channel_type_call_connect_to_call_members_changed ()
TpProxySignalConnection *	tp_cli_channel_type_call_connect_to_call_state_changed ()
TpProxySignalConnection *	tp_cli_channel_type_call_connect_to_content_added ()
TpProxySignalConnection *	tp_cli_channel_type_call_connect_to_content_removed ()
void	(*tp_cli_channel_type_call_signal_callback_call_members_changed) ()
void	(*tp_cli_channel_type_call_signal_callback_call_state_changed) ()
void	(*tp_cli_channel_type_call_signal_callback_content_added) ()
void	(*tp_cli_channel_type_call_signal_callback_content_removed) ()

Includes

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

Description

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

Functions

tp_cli_channel_type_call_call_accept ()

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

Start a Accept method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> For incoming calls in state <tp:value-ref type="Call_State">Initialised</tp:value-ref>, accept the incoming call. This changes the <tp:member-ref>CallState</tp:member-ref> to <tp:value-ref type="Call_State">Accepted</tp:value-ref>. For outgoing calls in state <tp:value-ref type="Call_State">Pending_Initiator</tp:value-ref>, actually call the remote contact; this changes the <tp:member-ref>CallState</tp:member-ref> to <tp:value-ref type="Call_State">Initialising</tp:value-ref>. Otherwise, this method SHOULD fail with the error NotAvailable. This method should be called exactly once per Call, by whatever client (user interface) is handling the channel. When this method is called, for each <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> whose <tp:dbus-ref namespace="ofdT.Call1.Content">Disposition</tp:dbus-ref> is <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref>, any streams where the <tp:dbus-ref namespace="ofdT.Call1.Stream">LocalSendingState</tp:dbus-ref> is <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> will be moved to <tp:value-ref type="Sending_State">Sending</tp:value-ref> as if <tp:dbus-ref namespace="ofdT.Call1.Stream">SetSending</tp:dbus-ref>(True) had been called.

Parameters

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

TpProxyPendingCall *
tp_cli_channel_type_call_call_add_content
                               (TpChannel *proxy,
                                gint timeout_ms,
                                const gchar *in_Content_Name,
                                guint in_Content_Type,
                                guint in_InitialDirection,
                                tp_cli_channel_type_call_callback_for_add_content callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a AddContent method call.

Request that a new <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> of type Content_Type is added to the Call1. Handlers should check the value of the <tp:member-ref>MutableContents</tp:member-ref> property before trying to add another content as it might not be allowed.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Content_Name	Used to pass an 'in' argument: <p>The suggested name of the content to add.</p> <tp:rationale> The content name property should be meaningful, so should be given a name which is significant to the user. The name could be a localized "audio", "video" or perhaps include some string identifying the source, such as a webcam identifier. </tp:rationale> <p>If there is already a content with the same name as this property then a sensible suffix should be added. For example, if this argument is "audio" but a content of the same name already exists, a sensible suffix such as " (1)" is appended to name the new content "audio (1)". A further content with the name "audio" would then be named "audio (2)".</p>
in_Content_Type	Used to pass an 'in' argument: The media stream type of the content to be added to the call. (TpMediaStreamType)
in_InitialDirection	Used to pass an 'in' argument: The requested initial direction of the new content. (TpMediaStreamDirection)
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_type_call_call_hangup ()

TpProxyPendingCall *
tp_cli_channel_type_call_call_hangup (TpChannel *proxy,
                                      gint timeout_ms,
                                      guint in_Reason,
                                      const gchar *in_Detailed_Hangup_Reason,
                                      const gchar *in_Message,
                                      tp_cli_channel_type_call_callback_for_hangup callback,
                                      gpointer user_data,
                                      GDestroyNotify destroy,
                                      GObject *weak_object);

Start a Hangup method call.

Request that the call is ended. All contents will be removed from the Call so that the <tp:member-ref>Contents</tp:member-ref> property will be the empty list.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Reason	Used to pass an 'in' argument: A generic hangup reason. (TpCallStateChangeReason)
in_Detailed_Hangup_Reason	Used to pass an 'in' argument: A more specific reason for the call hangup, if one is available, or an empty string otherwise.
in_Message	Used to pass an 'in' argument: A human-readable message to be sent to the remote contact(s). <tp:rationale> XMPP Jingle allows calls to be terminated with a human-readable message. </tp:rationale>
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_type_call_call_set_queued ()

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

Start a SetQueued method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Notifies the CM that the local user is already in a call, so this call has been put in a call-waiting style queue. This method is only useful if the channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> property is False, and the <tp:member-ref>CallState</tp:member-ref> is <tp:value-ref type="Call_State">Initialising</tp:value-ref> or <tp:value-ref type="Call_State">Initialised</tp:value-ref>. Calling this method SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref>, and notify the remote contact that the call is in a queue (if the protocol supports this); repeated calls to this method SHOULD succeed, but have no further effect. Locally_Queued is a little like Locally_Held, but applies to calls that have not been Accepted (the Locally_Queued flag should be unset by the CM when Accept is called). It should also be set in response to the state of the world, rather than in response to user action.

Parameters

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

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

Start a SetRinging method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Indicate that the local user has been alerted about the incoming call. This method is only useful if the channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> property is False, and the <tp:member-ref>CallState</tp:member-ref> is <tp:value-ref type="Call_State">Initialised</tp:value-ref> (an incoming call is ready and waiting for the user to be notified). Calling this method SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit <tp:value-ref type="Call_Flags">Locally_Ringing</tp:value-ref>, and notify the remote contact that the local user has been alerted (if the protocol supports this); repeated calls to this method SHOULD succeed, but have no further effect. In all other states, this method SHOULD fail with the error NotAvailable.

Parameters

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

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

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

Parameters

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

void
(*tp_cli_channel_type_call_callback_for_add_content)
                               (TpChannel *proxy,
                                const gchar *out_Content,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Content	Used to return an 'out' argument if `error` is `NULL`: Path to the newly-created <tp:dbus-ref namespace="org.freedesktop.Telepathy">Call1.Content</tp:dbus-ref> object.
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_channel_type_call_callback_for_hangup ()

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

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

Parameters

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

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

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

Parameters

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

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

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

Parameters

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

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

Connect a handler to the signal CallMembersChanged.

Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property changes in any way, either because contacts have been added to the call, contacts have been removed from the call, or contacts' flags have changed.

Parameters

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

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

Connect a handler to the signal CallStateChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Emitted when the state of the call as a whole changes. This signal is emitted for any change in the properties corresponding to its arguments, even if the other properties referenced remain unchanged.

Parameters

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

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

Connect a handler to the signal ContentAdded.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Emitted when a new <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> is added to the call.

Parameters

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

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

Connect a handler to the signal ContentRemoved.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Emitted when a <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> is removed from the call.

Parameters

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

void
(*tp_cli_channel_type_call_signal_callback_call_members_changed)
                               (TpChannel *proxy,
                                GHashTable *arg_Flags_Changed,
                                GHashTable *arg_Identifiers,
                                const GArray *arg_Removed,
                                const GValueArray *arg_Reason,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal CallMembersChanged.

Parameters

proxy	The proxy on which `tp_cli_channel_type_call_connect_to_call_members_changed()` was called
arg_Flags_Changed	A map from members of the call to their new call member flags, including at least the members who have been added to <tp:member-ref>CallMembers</tp:member-ref>, and the members whose flags have changed.
arg_Identifiers	<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The identifiers of the contacts in the <var>Flags_Changed</var> map.
arg_Removed	A list of members who have left the call, i.e. keys to be removed from <tp:member-ref>CallMembers</tp:member-ref>.
arg_Reason	A structured reason for the change.
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_channel_type_call_signal_callback_call_state_changed ()

void
(*tp_cli_channel_type_call_signal_callback_call_state_changed)
                               (TpChannel *proxy,
                                guint arg_Call_State,
                                guint arg_Call_Flags,
                                const GValueArray *arg_Call_State_Reason,
                                GHashTable *arg_Call_State_Details,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal CallStateChanged.

Parameters

proxy	The proxy on which `tp_cli_channel_type_call_connect_to_call_state_changed()` was called
arg_Call_State	The new value of the <tp:member-ref>CallState</tp:member-ref> property. (TpCallState)
arg_Call_Flags	The new value of the <tp:member-ref>CallFlags</tp:member-ref> property. (TpCallFlags)
arg_Call_State_Reason	The new value of the <tp:member-ref>CallStateReason</tp:member-ref> property.
arg_Call_State_Details	The new value of the <tp:member-ref>CallStateDetails</tp:member-ref> property.
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_channel_type_call_signal_callback_content_added ()

void
(*tp_cli_channel_type_call_signal_callback_content_added)
                               (TpChannel *proxy,
                                const gchar *arg_Content,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal ContentAdded.

Parameters

proxy	The proxy on which `tp_cli_channel_type_call_connect_to_content_added()` was called
arg_Content	Path to the newly-created <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> object.
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_channel_type_call_signal_callback_content_removed ()

void
(*tp_cli_channel_type_call_signal_callback_content_removed)
                               (TpChannel *proxy,
                                const gchar *arg_Content,
                                const GValueArray *arg_Reason,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal ContentRemoved.

Parameters

proxy	The proxy on which `tp_cli_channel_type_call_connect_to_content_removed()` was called
arg_Content	The <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> which was removed.
arg_Reason	Why the content was removed.
user_data	User-supplied data
weak_object	User-supplied weakly referenced object