Channel interface

Channel interface — client-side wrappers for Channel core functionality

Synopsis

#include <telepathy-glib/cli-channel.h>

TpProxyPendingCall * tp_cli_channel_call_close          (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_callback_for_close callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_callback_for_close)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_connect_to_closed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_signal_callback_closed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_signal_callback_closed)
                                                        (TpChannel *proxy,
                                                         gpointer user_data,
                                                         GObject *weak_object);

TpProxyPendingCall * tp_cli_channel_interface_destroyable_call_destroy
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_interface_destroyable_callback_for_destroy callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_destroyable_callback_for_destroy)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

This section documents the auto-generated C wrappers for the Channel D-Bus interface. These are not generally useful (the TpChannel object provides a more convenient API for them).

Details

tp_cli_channel_call_close ()

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

Start a Close method call.

Request that the channel be closed. This is not the case until the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and depending on the connection manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed.

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

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

Signature of the callback called when a Close 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_connect_to_closed ()

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

Connect a handler to the signal Closed.

Emitted when the channel has been closed. Method calls on the channel are no longer valid after this signal has been emitted, and the connection manager may then remove the object from the bus at any point.

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

void                (*tp_cli_channel_signal_callback_closed)
                                                        (TpChannel *proxy,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal Closed.

proxy :

The proxy on which tp_cli_channel_connect_to_closed() was called

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_interface_destroyable_call_destroy ()

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

Start a Destroy method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Close the channel abruptly, possibly with loss of data. The connection manager MUST NOT re-create the channel unless/until more events occur.</p> <tp:rationale> <p>The main motivating situation for this method is that when a Text channel with pending messages is closed with Close, it comes back as an incoming channel (to avoid a race between Close and an incoming message). If Destroy is called on a Text channel, the CM should delete all pending messages and close the channel, and the channel shouldn't be re-created until/unless another message arrives.</p> </tp:rationale> <p>Most clients SHOULD call <tp:dbus-ref namespace="im.telepathy1">Channel.Close</tp:dbus-ref> instead. However, if a client explicitly intends to destroy the channel with possible loss of data, it SHOULD call this method if this interface is supported (according to the <tp:dbus-ref namespace="im.telepathy1">Channel.Interfaces</tp:dbus-ref> property), falling back to Close if not.</p> <p>In particular, channel dispatchers SHOULD use this method if available when terminating channels that cannot be handled correctly (for instance, if no handler has been installed for a channel type, or if the handler crashes repeatedly).</p> <p>Connection managers do not need to implement this interface on channels where Close and Destroy would be equivalent.</p> <tp:rationale> <p>Callers need to be able to fall back to Close in any case.</p> </tp:rationale>

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

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

Signature of the callback called when a Destroy 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

See Also

TpChannel