Channel Call interfaces

Channel Call interfaces — client-side wrappers for call channels

Functions

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"> <p>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>.</p> <p>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>.</p> <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> <p>This method should be called exactly once per Call, by whatever client (user interface) is handling the channel.</p> <p>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.</p>

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 &quot;audio&quot;, &quot;video&quot; 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 &quot;audio&quot; but a content of the same name already exists, a sensible suffix such as &quot; (1)&quot; is appended to name the new content &quot;audio (1)&quot;. A further content with the name &quot;audio&quot; would then be named &quot;audio (2)&quot;.</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"> <p>Notifies the CM that the local user is already in a call, so this call has been put in a call-waiting style queue.</p> <p>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.</p> <p>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.</p>

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"> <p>Indicate that the local user has been alerted about the incoming call.</p> <p>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.</p> <p>In all other states, this method SHOULD fail with the error NotAvailable.</p>

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"> <p>Emitted when the state of the call as a whole changes.</p> <p>This signal is emitted for any change in the properties corresponding to its arguments, even if the other properties referenced remain unchanged.</p>

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"> <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> is added to the call.</p>

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"> <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> is removed from the call.</p>

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