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