TpChannelDispatcher: telepathy-glib API Reference Manual

TpChannelDispatcher

TpChannelDispatcher — proxy object for the Telepathy channel dispatcher

Functions

TpChannelDispatcher *	tp_channel_dispatcher_new ()
void	tp_channel_dispatcher_init_known_interfaces ()
void	(*tp_cli_channel_dispatcher_callback_for_create_channel) ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_create_channel ()
void	(*tp_cli_channel_dispatcher_callback_for_create_channel_with_hints) ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_create_channel_with_hints ()
void	(*tp_cli_channel_dispatcher_callback_for_ensure_channel) ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_ensure_channel ()
void	(*tp_cli_channel_dispatcher_callback_for_ensure_channel_with_hints) ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_ensure_channel_with_hints ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_delegate_channels ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_call_present_channel ()
void	(*tp_cli_channel_dispatcher_callback_for_delegate_channels) ()
void	(*tp_cli_channel_dispatcher_callback_for_present_channel) ()
TpProxyPendingCall *	tp_cli_channel_dispatcher_interface_messages1_call_send_message ()
void	(*tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message) ()
void	(*tp_cli_channel_dispatcher_interface_operation_list_signal_callback_dispatch_operation_finished) ()
TpProxySignalConnection *	tp_cli_channel_dispatcher_interface_operation_list_connect_to_dispatch_operation_finished ()
void	(*tp_cli_channel_dispatcher_interface_operation_list_signal_callback_new_dispatch_operation) ()
TpProxySignalConnection *	tp_cli_channel_dispatcher_interface_operation_list_connect_to_new_dispatch_operation ()

Types and Values

struct	TpChannelDispatcher
struct	TpChannelDispatcherClass

Object Hierarchy

    GObject
    ╰── TpProxy
        ╰── TpChannelDispatcher

Includes

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

Description

The TpChannelDispatcher object can be used to communicate with any implementation of the Telepathy ChannelDispatcher service to request new channels.

Functions

tp_channel_dispatcher_new ()

TpChannelDispatcher *
tp_channel_dispatcher_new (TpDBusDaemon *bus_daemon);

Convenience function to create a new channel dispatcher proxy.

Parameters

bus_daemon

Proxy for the D-Bus daemon

Returns

a new reference to a channel dispatcher proxy

tp_channel_dispatcher_init_known_interfaces ()

void
tp_channel_dispatcher_init_known_interfaces
                               (void);

Ensure that the known interfaces for TpChannelDispatcher have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument TP_TYPE_CHANNEL_DISPATCHER.

Since: 0.7.32

tp_cli_channel_dispatcher_callback_for_create_channel ()

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

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

Parameters

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="org.freedesktop.Telepathy">ChannelRequest</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_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,
                                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"> Equivalent to calling <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty <var>Hints</var> parameter.

Parameters

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="org.freedesktop.Telepathy">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.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</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>CreateChannelWithHints</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>org.freedesktop.Telepathy.Client.</code>) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannelWithHints</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_create_channel_with_hints ()

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

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

Parameters

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="org.freedesktop.Telepathy">ChannelRequest</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_dispatcher_call_create_channel_with_hints ()

TpProxyPendingCall *
tp_cli_channel_dispatcher_call_create_channel_with_hints
                               (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_with_hints callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a CreateChannelWithHints method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Start a request to create a channel. This initially just creates a <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure. <tp:rationale> 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. 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. </tp:rationale> If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error. <tp:rationale> This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense". It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed. </tp:rationale>

Parameters

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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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>org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="ofdT.ChannelRequest">Hints</tp:dbus-ref> property.</p> <tp:rationale> <p>See the Hints 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,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

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="org.freedesktop.Telepathy">ChannelRequest</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_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,
                                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"> Equivalent to calling <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty <var>Hints</var> parameter.

Parameters

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="org.freedesktop.Telepathy">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.</p> <p>This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</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>CreateChannelWithHints</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>org.freedesktop.Telepathy.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>EnsureChannelWithHints</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_ensure_channel_with_hints ()

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

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

Parameters

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="org.freedesktop.Telepathy">ChannelRequest</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_dispatcher_call_ensure_channel_with_hints ()

TpProxyPendingCall *
tp_cli_channel_dispatcher_call_ensure_channel_with_hints
                               (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_with_hints callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a EnsureChannelWithHints method call.

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

Parameters

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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="org.freedesktop.Telepathy">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>CreateChannelWithHints</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>org.freedesktop.Telepathy.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>CreateChannelWithHints</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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="ofdT.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"> Called by a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> to redispatch a bunch of channels it is currently handling. For each <var>Channel</var> in <var>Channels</var>, if another <tp:dbus-ref namespace="ofdT.Client">Handler</tp:dbus-ref> can be found, <tp:dbus-ref namespace="ofdT.Client.Handler">HandleChannels</tp:dbus-ref> will be called on it until a <tp:dbus-ref namespace="ofdT.Client">Handler</tp:dbus-ref> accepts it. This method returns once all the <var>Channels</var> have either been accepted or rejected by Handlers. If this method fails, the original <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> is still handling the channels.

Parameters

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="org.freedesktop.Telepathy.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>CreateChannelWithHints</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>org.freedesktop.Telepathy.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>CreateChannelWithHints</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"> Equivalent of calling <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> with a <var>Requested_Properties</var> which would result in ensuring <var>Channel</var>. If <var>Channel</var> is handled, its handler will be asked to present it the user (e.g. bring it into the foreground).

Parameters

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>EnsureChannelWithHints</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.

Parameters

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="ofdT.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.

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

TpProxyPendingCall *
tp_cli_channel_dispatcher_interface_messages1_call_send_message
                               (TpChannelDispatcher *proxy,
                                gint timeout_ms,
                                const gchar *in_Account,
                                const gchar *in_Target_ID,
                                const GPtrArray *in_Message,
                                guint in_Flags,
                                tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a SendMessage method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Submit a message to the server for sending, like the <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> method. If the <var>Account</var> is connected and a Text channel to the <var>Target_ID</var> already exists, this method is equivalent to sending the same message via that channel. Otherwise, this method creates a channel (connecting the Account if appropriate), sends the desired message, and closes the channel as if via <tp:dbus-ref namespace="ofdT">Channel.Close</tp:dbus-ref>, without acknowledging any messages received on that channel during that time. If any messages are received on that channel before it is closed, a correct connection manager implementation will reopen the channel when it is closed, resulting in those "rescued" messages being processed by the system's normal <tp:dbus-ref namespace="ofdT.Client">Handler</tp:dbus-ref> for text channels. In particular, this deals with the situation where a successful or failed delivery report is received before the channel is closed. <tp:rationale> Expecting a trivial client (perhaps a send-only IRC bot, or a simple SMS-sending API) to go through all those steps to send a message seems somewhat unreasonable. Having this as a method in the ChannelDispatcher lets it take some short-cuts if required, and centralizes the implementation to reduce the risk of mistakes that cause message loss. </tp:rationale> The ChannelDispatcher SHOULD support this method for any connection manager that would accept channel requests of this form: <pre> { …<tp:dbus-ref namespace="ofdT">Channel.ChannelType</tp:dbus-ref>: …<tp:dbus-ref namespace="ofdT">Channel.Type.Text</tp:dbus-ref>, …<tp:dbus-ref namespace="ofdT">Channel.TargetHandleType</tp:dbus-ref>: <tp:value-ref type="Handle_Type">Contact</tp:value-ref>, …<tp:dbus-ref namespace="ofdT">Channel.TargetID</tp:dbus-ref>: <var>Target_ID</var> }</pre> However, if the connection manager provides additional APIs (such as a way to open "send-only" channels), the ChannelDispatcher MAY use those: it is not required to use those exact request parameters. This method may raise any error that would be raised by the <tp:dbus-ref namespace="ofdT.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> or <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> methods, or signalled by the <tp:dbus-ref namespace="ofdT.ChannelRequest">Failed</tp:dbus-ref> signal.

Parameters

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="ofdT">Account</tp:dbus-ref> through which to communicate.
in_Target_ID	Used to pass an 'in' argument: The contact to send the message to.
in_Message	Used to pass an 'in' argument: The parts of the message, the same as for <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
in_Flags	Used to pass an 'in' argument: Flags influencing how to send the message, the same as for <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
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_interface_messages1_callback_for_send_message ()

void
(*tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message)
                               (TpChannelDispatcher *proxy,
                                const gchar *out_Token,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Token	Used to return an 'out' argument if `error` is `NULL`: An opaque token equivalent to the one returned by <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>.
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_list_signal_callback_dispatch_operation_finished ()

void
(*tp_cli_channel_dispatcher_interface_operation_list_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.

Parameters

proxy	The proxy on which `tp_cli_channel_dispatcher_interface_operation_list_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_list_connect_to_dispatch_operation_finished ()

TpProxySignalConnection *
tp_cli_channel_dispatcher_interface_operation_list_connect_to_dispatch_operation_finished
                               (TpChannelDispatcher *proxy,
                                tp_cli_channel_dispatcher_interface_operation_list_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="org.freedesktop.Telepathy">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>

Parameters

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

void
(*tp_cli_channel_dispatcher_interface_operation_list_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.

Parameters

proxy	The proxy on which `tp_cli_channel_dispatcher_interface_operation_list_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_list_connect_to_new_dispatch_operation ()

TpProxySignalConnection *
tp_cli_channel_dispatcher_interface_operation_list_connect_to_new_dispatch_operation
                               (TpChannelDispatcher *proxy,
                                tp_cli_channel_dispatcher_interface_operation_list_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"> Emitted when a dispatch operation is added to <tp:member-ref>DispatchOperations</tp:member-ref>.

Parameters

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.

Types and Values

struct TpChannelDispatcher

struct TpChannelDispatcher;

The Channel Dispatcher's main D-Bus API is used to request channels, which is done by calling tp_cli_channel_dispatcher_call_create_channel() or tp_cli_channel_dispatcher_call_ensure_channel() as appropriate.

The Telepathy Channel Dispatcher is also responsible for responding to new channels and launching client processes to handle them. However, clients that can work with incoming channels do not have to call methods on the channel dispatcher: instead, they must register with the channel dispatcher passively, by taking a bus name starting with TP_CLIENT_BUS_NAME_BASE and implementing the TpSvcClient interface. See the Telepathy D-Bus Interface Specification for details.

This proxy is usable but incomplete: convenience methods will be added in a later version of telepathy-glib, along with a mechanism similar to tp_connection_call_when_ready().

Since: 0.7.32

struct TpChannelDispatcherClass

struct TpChannelDispatcherClass {
};

The class of a TpChannelDispatcher.