ChannelDispatcher interface

ChannelDispatcher interface — client-side wrappers for ChannelDispatcher core functionality

Synopsis

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

void                (*tp_cli_channel_dispatcher_callback_for_create_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Request,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatcher_call_create_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         GHashTable *in_Requested_Properties,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         GHashTable *in_Hints,
                                                         tp_cli_channel_dispatcher_callback_for_create_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatcher_callback_for_ensure_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Request,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatcher_call_ensure_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         GHashTable *in_Requested_Properties,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         GHashTable *in_Hints,
                                                         tp_cli_channel_dispatcher_callback_for_ensure_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatcher_call_delegate_channels
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const GPtrArray *in_Channels,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         tp_cli_channel_dispatcher_callback_for_delegate_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatcher_call_present_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Channel,
                                                         gint64 in_User_Action_Time,
                                                         tp_cli_channel_dispatcher_callback_for_present_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatcher_callback_for_delegate_channels)
                                                        (TpChannelDispatcher *proxy,
                                                         const GPtrArray *out_Delegated,
                                                         GHashTable *out_Not_Delegated,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatcher_callback_for_present_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

void                (*tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_dispatch_operation_finished)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *arg_Dispatch_Operation,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_dispatcher_interface_operation_list1_connect_to_dispatch_operation_finished
                                                        (TpChannelDispatcher *proxy,
                                                         tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_dispatch_operation_finished callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_new_dispatch_operation)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *arg_Dispatch_Operation,
                                                         GHashTable *arg_Properties,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_dispatcher_interface_operation_list1_connect_to_new_dispatch_operation
                                                        (TpChannelDispatcher *proxy,
                                                         tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_new_dispatch_operation callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

void                (*tp_cli_channel_request_callback_for_cancel)
                                                        (TpChannelRequest *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_request_call_cancel (TpChannelRequest *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_request_callback_for_cancel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_request_callback_for_proceed)
                                                        (TpChannelRequest *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_request_call_proceed
                                                        (TpChannelRequest *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_request_callback_for_proceed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_request_signal_callback_failed)
                                                        (TpChannelRequest *proxy,
                                                         const gchar *arg_Error,
                                                         const gchar *arg_Message,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_request_connect_to_failed
                                                        (TpChannelRequest *proxy,
                                                         tp_cli_channel_request_signal_callback_failed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_request_signal_callback_succeeded)
                                                        (TpChannelRequest *proxy,
                                                         const gchar *arg_Connection,
                                                         GHashTable *arg_Connection_Properties,
                                                         const gchar *arg_Channel,
                                                         GHashTable *arg_Channel_Properties,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_request_connect_to_succeeded
                                                        (TpChannelRequest *proxy,
                                                         tp_cli_channel_request_signal_callback_succeeded callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

void                (*tp_cli_channel_dispatch_operation_callback_for_claim)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_claim
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_dispatch_operation_callback_for_claim callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatch_operation_callback_for_handle_with)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_handle_with
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Handler,
                                                         tp_cli_channel_dispatch_operation_callback_for_handle_with callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatch_operation_callback_for_handle_with_time)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_handle_with_time
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Handler,
                                                         gint64 in_UserActionTime,
                                                         tp_cli_channel_dispatch_operation_callback_for_handle_with_time callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatch_operation_signal_callback_channel_lost)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const gchar *arg_Channel,
                                                         const gchar *arg_Error,
                                                         const gchar *arg_Message,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_dispatch_operation_connect_to_channel_lost
                                                        (TpChannelDispatchOperation *proxy,
                                                         tp_cli_channel_dispatch_operation_signal_callback_channel_lost callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_channel_dispatch_operation_signal_callback_finished)
                                                        (TpChannelDispatchOperation *proxy,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_dispatch_operation_connect_to_finished
                                                        (TpChannelDispatchOperation *proxy,
                                                         tp_cli_channel_dispatch_operation_signal_callback_finished callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Description

This section documents the auto-generated C wrappers for the ChannelDispatcher D-Bus interface.

Details

tp_cli_channel_dispatcher_callback_for_create_channel ()

void                (*tp_cli_channel_dispatcher_callback_for_create_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Request,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Request :

Used to return an 'out' argument if error is NULL: A <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref> object.

out_Properties :

Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Immutable properties of the channel request object.</p>

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_dispatcher_call_create_channel ()

TpProxyPendingCall * tp_cli_channel_dispatcher_call_create_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         GHashTable *in_Requested_Properties,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         GHashTable *in_Hints,
                                                         tp_cli_channel_dispatcher_callback_for_create_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a CreateChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to create a channel. This initially just creates a <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure.</p> <tp:rationale> <p>The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.</p> <p>This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.</p> </tp:rationale> <p>If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.</p> <tp:rationale> <p>This means there's only one code path for errors, apart from InvalidArgument for &quot;that request makes no sense&quot;.</p> <p>It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

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

in_Account :

Used to pass an 'in' argument: The <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref> for which the new channel is to be created.

in_Requested_Properties :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. </p> <p>Certain properties will not necessarily make sense in this dictionary: for instance, <tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> to the desired account.</p>

in_User_Action_Time :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. The <tp:dbus-ref namespace="im.telepathy.v1.ChannelRequest">UserActionTime</tp:dbus-ref> property will be set to this value, and it will eventually be passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>.</p>

in_Preferred_Handler :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Either the well-known bus name (starting with <code>im.telepathy.v1.Client.</code>) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler—irrespective of whether that handler's <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandlerChannelFilter</tp:dbus-ref> matches the channel—and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler.</p> <tp:rationale> <p>This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.</p> <p>This is partly so the channel dispatcher can call <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.</p> <p>The filter should be disregarded for ease of use of this interface: clients will usually use this argument to request channels be sent to themself, and this should trump the filter not matching. This also allows a client to become the handler for a channel produced by one of its own requests, while not being a candidate to handle other channels of that type.</p> </tp:rationale> <p>If this is a well-known bus name and the handler has the Requests interface, the channel dispatcher SHOULD call <tp:dbus-ref namespace="im.telepathy.v1.Client.Interface.Requests">AddRequest</tp:dbus-ref> on that Handler after this method has returned.</p> <tp:rationale> <p>This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.</p> </tp:rationale> <p>This is copied to the ChannelRequest that is returned, as the <tp:dbus-ref namespace="im.telepathy.v1.ChannelRequest">PreferredHandler</tp:dbus-ref> property.</p>

in_Hints :

Used to pass an 'in' argument: <p>Additional information about the channel request, which will be used as the value for the resulting request's <tp:dbus-ref namespace="imt1.ChannelRequest">Hints</tp:dbus-ref> property.</p> <tp:rationale> <p>See the <tp:dbus-ref namespace="imt1.ChannelRequest">Hints</tp:dbus-ref> property's documentation for rationale.</p> </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_dispatcher_callback_for_ensure_channel ()

void                (*tp_cli_channel_dispatcher_callback_for_ensure_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Request,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Request :

Used to return an 'out' argument if error is NULL: A <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref> object.

out_Properties :

Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Immutable properties of the channel request object.</p>

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_dispatcher_call_ensure_channel ()

TpProxyPendingCall * tp_cli_channel_dispatcher_call_ensure_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         GHashTable *in_Requested_Properties,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         GHashTable *in_Hints,
                                                         tp_cli_channel_dispatcher_callback_for_ensure_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a EnsureChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure.</p> <p>If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.</p> <tp:rationale> <p>The rationale is as for <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatcher">CreateChannel</tp:dbus-ref>.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

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

in_Account :

Used to pass an 'in' argument: The <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref> for which the new channel is to be created.

in_Requested_Properties :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. </p> <p>Certain properties will not necessarily make sense in this dictionary: for instance, <tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> to the desired account.</p>

in_User_Action_Time :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>

in_Preferred_Handler :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Either the well-known bus name (starting with <code>im.telepathy.v1.Client.</code>) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>, except as noted here.</p> <p>If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler, and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler. If the requested channel already exists (that is, <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> returns <code>Yours=False</code>) then the channel dispatcher SHOULD re-dispatch the channel to its existing handler, and MUST NOT dispatch it to this client (unless it is the existing handler); the request is still deemed to have succeeded in this case.</p> <tp:rationale> <p>An address book application, for example, might call <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatcher">EnsureChannel</tp:dbus-ref> to ensure that a text channel with a particular contact is displayed to the user; it does not care whether a new channel was made. An IM client might call <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatcher">EnsureChannel</tp:dbus-ref> in response to the user double-clicking an entry in the contact list, with itself as the <code>Preferred_Handler</code>; if the user already has a conversation with that contact in another application, they would expect the existing window to be presented, rather than their double-click leading to an error message. So the request should succeed, even if its <code>Preferred_Handler</code> is not used.</p> </tp:rationale>

in_Hints :

Used to pass an 'in' argument: Additional information about the channel request, which will be used as the value for the resulting request's <tp:dbus-ref namespace="imt1.ChannelRequest">Hints</tp:dbus-ref> property.

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

TpProxyPendingCall * tp_cli_channel_dispatcher_call_delegate_channels
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const GPtrArray *in_Channels,
                                                         gint64 in_User_Action_Time,
                                                         const gchar *in_Preferred_Handler,
                                                         tp_cli_channel_dispatcher_callback_for_delegate_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a DelegateChannels method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by a <tp:dbus-ref namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref> to redispatch a bunch of channels it is currently handling.</p> <p>For each <var>Channel</var> in <var>Channels</var>, if another <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref> can be found, <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref> will be called on it until a <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref> accepts it.</p> <p>This method returns once all the <var>Channels</var> have either been accepted or rejected by Handlers.</p> <p>If this method fails, the original <tp:dbus-ref namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref> is still handling the channels.</p>

proxy :

the TpProxy

timeout_ms :

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

in_Channels :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The list of channels to redispatch. The caller has to be the current <tp:dbus-ref namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref> of all of these channels </p>

in_User_Action_Time :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channels delegation is for some reason not involving user action.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>

in_Preferred_Handler :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Either the well-known bus name (starting with <code>im.telepathy.v1.Client.</code>) of the preferred new handler for these channels, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>

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

TpProxyPendingCall * tp_cli_channel_dispatcher_call_present_channel
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Channel,
                                                         gint64 in_User_Action_Time,
                                                         tp_cli_channel_dispatcher_callback_for_present_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a PresentChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Equivalent of calling <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatcher">EnsureChannel</tp:dbus-ref> with a <var>Requested_Properties</var> which would result in ensuring <var>Channel</var>.</p> <p>If <var>Channel</var> is handled, its handler will be asked to present it the user (e.g. bring it into the foreground).</p>

proxy :

the TpProxy

timeout_ms :

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

in_Channel :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The channel to present.</p>

in_User_Action_Time :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>EnsureChannel</tp:member-ref>.</p>

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

void                (*tp_cli_channel_dispatcher_callback_for_delegate_channels)
                                                        (TpChannelDispatcher *proxy,
                                                         const GPtrArray *out_Delegated,
                                                         GHashTable *out_Not_Delegated,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Delegated :

Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The list of channels which have been delegated; the caller is no longer handling these channels.</p> <p>The client should remove these channels from its <tp:dbus-ref namespace="imt1.Client.Handler">HandledChannels</tp:dbus-ref> property.</p>

out_Not_Delegated :

Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The list of channels which have NOT been delegated; the caller is still handling these channels.</p>

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_dispatcher_callback_for_present_channel ()

void                (*tp_cli_channel_dispatcher_callback_for_present_channel)
                                                        (TpChannelDispatcher *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

void                (*tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_dispatch_operation_finished)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *arg_Dispatch_Operation,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal DispatchOperationFinished.

proxy :

The proxy on which tp_cli_channel_dispatcher_interface_operation_list1_connect_to_dispatch_operation_finished() was called

arg_Dispatch_Operation :

The dispatch operation that was closed.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_dispatcher_interface_operation_list1_connect_to_dispatch_operation_finished ()

TpProxySignalConnection * tp_cli_channel_dispatcher_interface_operation_list1_connect_to_dispatch_operation_finished
                                                        (TpChannelDispatcher *proxy,
                                                         tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_dispatch_operation_finished callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal DispatchOperationFinished.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Emitted when a dispatch operation finishes (i.e. exactly once per emission of <tp:dbus-ref namespace="im.telepathy.v1">ChannelDispatchOperation.Finished</tp:dbus-ref>). <tp:rationale> Strictly speaking this is redundant with ChannelDispatchOperation.Finished, but it provides full change-notification for the <tp:member-ref>DispatchOperations</tp:member-ref> property. </tp:rationale>

proxy :

A TpChannelDispatcher 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_dispatcher_interface_operation_list1_signal_callback_new_dispatch_operation ()

void                (*tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_new_dispatch_operation)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *arg_Dispatch_Operation,
                                                         GHashTable *arg_Properties,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal NewDispatchOperation.

proxy :

The proxy on which tp_cli_channel_dispatcher_interface_operation_list1_connect_to_new_dispatch_operation() was called

arg_Dispatch_Operation :

The dispatch operation that was created.

arg_Properties :

The same properties that would appear in the Properties member of <tp:type>Dispatch_Operation_Details</tp:type>.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_dispatcher_interface_operation_list1_connect_to_new_dispatch_operation ()

TpProxySignalConnection * tp_cli_channel_dispatcher_interface_operation_list1_connect_to_new_dispatch_operation
                                                        (TpChannelDispatcher *proxy,
                                                         tp_cli_channel_dispatcher_interface_operation_list1_signal_callback_new_dispatch_operation callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal NewDispatchOperation.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when a dispatch operation is added to <tp:member-ref>DispatchOperations</tp:member-ref>.</p>

proxy :

A TpChannelDispatcher 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_request_callback_for_cancel ()

void                (*tp_cli_channel_request_callback_for_cancel)
                                                        (TpChannelRequest *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

TpProxyPendingCall * tp_cli_channel_request_call_cancel (TpChannelRequest *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_request_callback_for_cancel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Cancel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Cancel the channel request. The precise effect depends on the current progress of the request.</p> <p>If the connection manager has not already been asked to create a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted immediately, and the channel request is removed.</p> <p>If the connection manager has already been asked to create a channel but has not produced one yet (e.g. if <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> has been called, but has not yet returned), then the ChannelDispatcher will remember that the request has been cancelled. When the channel appears, it will be closed (if it was newly created and can be closed), and will not be dispatched to a handler.</p> <p>If the connection manager has already returned a channel, but the channel has not yet been dispatched to a handler then the channel dispatcher will not dispatch that channel to a handler. If the channel was newly created for this request, the channel dispatcher will close it with <tp:dbus-ref namespace="im.telepathy.v1.Channel">Close</tp:dbus-ref>; otherwise, the channel dispatcher will ignore it. In either case, <tp:member-ref>Failed</tp:member-ref> will be emitted when processing has been completed.</p> <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to this method, the error SHOULD be <code>im.telepathy.v1.Error.Cancelled</code>.</p> <p>If the channel has already been dispatched to a handler, then it's too late to call this method, and the channel request will no longer exist.</p>

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

void                (*tp_cli_channel_request_callback_for_proceed)
                                                        (TpChannelRequest *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

TpProxyPendingCall * tp_cli_channel_request_call_proceed
                                                        (TpChannelRequest *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_request_callback_for_proceed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Proceed method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Proceed with the channel request.</p> <tp:rationale> <p>The client that created this object calls this method when it has connected signal handlers for <tp:member-ref>Succeeded</tp:member-ref> and <tp:member-ref>Failed</tp:member-ref>.</p> </tp:rationale> <p>Clients other than the client which created the ChannelRequest MUST NOT call this method.</p> <p>This method SHOULD return immediately; on success, the request might still fail, but this will be indicated asynchronously by the <tp:member-ref>Failed</tp:member-ref> signal.</p> <p>Proceed cannot fail, unless clients have got the life-cycle of a ChannelRequest seriously wrong (e.g. a client calls this method twice, or a client that did not create the ChannelRequest calls this method). If it fails, clients SHOULD assume that the whole ChannelRequest has become useless.</p>

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

void                (*tp_cli_channel_request_signal_callback_failed)
                                                        (TpChannelRequest *proxy,
                                                         const gchar *arg_Error,
                                                         const gchar *arg_Message,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal Failed.

proxy :

The proxy on which tp_cli_channel_request_connect_to_failed() was called

arg_Error :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of a D-Bus error. This can come from various sources, including the error raised by <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, or an error generated to represent failure to establish the <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>.</p>

arg_Message :

If the first argument of the D-Bus error message was a string, that string. Otherwise, an empty string.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_request_connect_to_failed ()

TpProxySignalConnection * tp_cli_channel_request_connect_to_failed
                                                        (TpChannelRequest *proxy,
                                                         tp_cli_channel_request_signal_callback_failed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal Failed.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The channel request has failed. It is no longer present, and further methods must not be called on it.</p>

proxy :

A TpChannelRequest 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_request_signal_callback_succeeded ()

void                (*tp_cli_channel_request_signal_callback_succeeded)
                                                        (TpChannelRequest *proxy,
                                                         const gchar *arg_Connection,
                                                         GHashTable *arg_Connection_Properties,
                                                         const gchar *arg_Channel,
                                                         GHashTable *arg_Channel_Properties,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal Succeeded.

proxy :

The proxy on which tp_cli_channel_request_connect_to_succeeded() was called

arg_Connection :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The Connection owning the channel.</p>

arg_Connection_Properties :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A subset of the Connection's properties, currently unused. This parameter may be used in future.</p>

arg_Channel :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The channel which has been created.</p>

arg_Channel_Properties :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The same immutable properties of the Channel that would appear in a <tp:dbus-ref namespace="imt1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> signal.</p>

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_request_connect_to_succeeded ()

TpProxySignalConnection * tp_cli_channel_request_connect_to_succeeded
                                                        (TpChannelRequest *proxy,
                                                         tp_cli_channel_request_signal_callback_succeeded callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal Succeeded.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The channel request has succeeded. It is no longer present, and further methods must not be called on it.</p> <p>This signal MUST be emitted before the <tp:member-ref>Succeeded</tp:member-ref> signal.</p>

proxy :

A TpChannelRequest 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_dispatch_operation_callback_for_claim ()

void                (*tp_cli_channel_dispatch_operation_callback_for_claim)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_claim
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_dispatch_operation_callback_for_claim callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Claim method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by an approver to claim channels for handling internally. If this method is called successfully, the process calling this method becomes the handler for the channel, but <em>does not</em> have the <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> method called on it.</p> <p>Clients that call Claim on channels but do not immediately close them SHOULD implement the Handler interface and its <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandledChannels</tp:dbus-ref> property.</p> <p>Approvers wishing to reject channels MUST call this method to claim ownership of them, and MUST NOT call <tp:dbus-ref namespace="im.telepathy.v1.Channel">Close</tp:dbus-ref> on the channels unless/until this method returns successfully.</p> <tp:rationale> <p>The channel dispatcher can't know how best to close arbitrary channel types, so it leaves it up to the approver to do so. For instance, for Text channels it is necessary to acknowledge any messages that have already been displayed to the user first - ideally, the approver would display and then acknowledge the messages - or to call <tp:dbus-ref namespace="im.telepathy.v1">Channel.Interface.Destroyable1.Destroy</tp:dbus-ref> if the destructive behaviour of that method is desired.</p> <p>Similarly, an Approver for <tp:dbus-ref namespace="imt1.Channel.Type">Call1</tp:dbus-ref> channels can close the channel with a reason (e.g. &quot;busy&quot;) if desired. The channel dispatcher, which is designed to have no specific knowledge of particular channel types, can't do that.</p> </tp:rationale> <p>If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting <tp:member-ref>Finished</tp:member-ref>, in the same way as for <tp:member-ref>HandleWith</tp:member-ref>.</p> <p>This method may fail because the dispatch operation has already been completed. Again, see HandleWith for more details. The approver MUST NOT attempt to interact with the channels further in this case.</p> <p>(FIXME: list some other possible errors)</p>

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

void                (*tp_cli_channel_dispatch_operation_callback_for_handle_with)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_handle_with
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Handler,
                                                         tp_cli_channel_dispatch_operation_callback_for_handle_with callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a HandleWith method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by an approver to accept a channel bundle and request that the given handler be used to handle it.</p> <p>If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting <tp:member-ref>Finished</tp:member-ref>.</p> <p>However, this method may fail because the dispatch has already been completed and the object has already gone. If this occurs, it indicates that another approver has asked for the bundle to be handled by a particular handler. The approver MUST NOT attempt to interact with the channels further in this case, unless it is separately invoked as the handler.</p> <p>Approvers which are also channel handlers SHOULD use <tp:member-ref>Claim</tp:member-ref> instead of HandleWith to request that they can handle a channel bundle themselves.</p> <p>(FIXME: list some possible errors)</p> <p>If the channel handler raises an error from <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>, this method MAY respond by raising that same error, even if it is not specifically documented here.</p>

proxy :

the TpProxy

timeout_ms :

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

in_Handler :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The well-known bus name (starting with <code>im.telepathy.v1.Client.</code>) of the channel handler that should handle the channel, or the empty string if the client has no preferred channel handler.</p>

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

void                (*tp_cli_channel_dispatch_operation_callback_for_handle_with_time)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

TpProxyPendingCall * tp_cli_channel_dispatch_operation_call_handle_with_time
                                                        (TpChannelDispatchOperation *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Handler,
                                                         gint64 in_UserActionTime,
                                                         tp_cli_channel_dispatch_operation_callback_for_handle_with_time callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a HandleWithTime method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the approver to pass an user action time. This timestamp will be passed to the Handler when <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> is called.</p>

proxy :

the TpProxy

timeout_ms :

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

in_Handler :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The well-known bus name (starting with <code>im.telepathy.v1.Client.</code>) of the channel handler that should handle the channel, or the empty string if the client has no preferred channel handler.</p>

in_UserActionTime :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred.</p>

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

void                (*tp_cli_channel_dispatch_operation_signal_callback_channel_lost)
                                                        (TpChannelDispatchOperation *proxy,
                                                         const gchar *arg_Channel,
                                                         const gchar *arg_Error,
                                                         const gchar *arg_Message,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal ChannelLost.

proxy :

The proxy on which tp_cli_channel_dispatch_operation_connect_to_channel_lost() was called

arg_Channel :

The <tp:dbus-ref namespace="im.telepathy.v1">Channel</tp:dbus-ref> that closed.

arg_Error :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of a D-Bus error indicating why the channel closed. If no better reason can be found, <code>im.telepathy.v1.Error.NotAvailable</code> MAY be used as a fallback; this means that this error SHOULD NOT be given any more specific meaning.</p>

arg_Message :

A string associated with the D-Bus error.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_dispatch_operation_connect_to_channel_lost ()

TpProxySignalConnection * tp_cli_channel_dispatch_operation_connect_to_channel_lost
                                                        (TpChannelDispatchOperation *proxy,
                                                         tp_cli_channel_dispatch_operation_signal_callback_channel_lost callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal ChannelLost.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel has closed before it could be claimed or handled. If this is emitted for the last remaining channel in a channel dispatch operation, it MUST immediately be followed by <tp:member-ref>Finished</tp:member-ref>.</p> <p>This signal MUST NOT be emitted until all Approvers that were invoked have returned (successfully or with an error) from their <tp:dbus-ref namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref> method.</p> <tp:rationale> <p>This means that Approvers can connect to the ChannelLost signal in a race-free way. Non-approver processes that discover a channel dispatch operation in some way (such as observers) will have to follow the usual &quot;connect to signals then recover state&quot; model - first connect to ChannelLost and <tp:member-ref>Finished</tp:member-ref>, then download <tp:member-ref>Channels</tp:member-ref> (and on error, perhaps assume that the operation has already Finished).</p> </tp:rationale>

proxy :

A TpChannelDispatchOperation 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_dispatch_operation_signal_callback_finished ()

void                (*tp_cli_channel_dispatch_operation_signal_callback_finished)
                                                        (TpChannelDispatchOperation *proxy,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal Finished.

proxy :

The proxy on which tp_cli_channel_dispatch_operation_connect_to_finished() was called

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_dispatch_operation_connect_to_finished ()

TpProxySignalConnection * tp_cli_channel_dispatch_operation_connect_to_finished
                                                        (TpChannelDispatchOperation *proxy,
                                                         tp_cli_channel_dispatch_operation_signal_callback_finished callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal Finished.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when this dispatch operation finishes. The dispatch operation is no longer present and further methods must not be called on it.</p> <p>Approvers that have a user interface SHOULD stop notifying the user about the channels in response to this signal; they MAY assume that on errors, they would have received <tp:member-ref>ChannelLost</tp:member-ref> first.</p> <p>Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths in a way that avoids immediate re-use.</p> <tp:rationale> <p>Otherwise, clients might accidentally call <tp:member-ref>HandleWith</tp:member-ref> or <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation instead of the one they intended to handle.</p> </tp:rationale> <p>This signal MUST NOT be emitted until all Approvers that were invoked have returned (successfully or with an error) from their <tp:dbus-ref namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref> method.</p> <tp:rationale> <p>This means that Approvers can connect to the ChannelLost signal in a race-free way. Non-approver processes that discover a channel dispatch operation in some way (such as observers) will have to follow the usual &quot;connect to signals then recover state&quot; model - first connect to <tp:member-ref>ChannelLost</tp:member-ref> and Finished, then download <tp:member-ref>Channels</tp:member-ref> (and on error, perhaps assume that the operation has already Finished).</p> </tp:rationale>

proxy :

A TpChannelDispatchOperation 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

TpChannelDispatcher