TpClient

## TpClient TpClient — proxy object for a client of the ChannelDispatcher |

## Synopsis

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

    struct              TpClient;
    struct              TpClientClass;
    void                tp_client_init_known_interfaces     (void);

    void                (*tp_cli_client_observer_callback_for_observe_channels)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_client_observer_call_observe_channels
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Account,
                                                             const gchar *in_Connection,
                                                             const GPtrArray *in_Channels,
                                                             const gchar *in_Dispatch_Operation,
                                                             const GPtrArray *in_Requests_Satisfied,
                                                             GHashTable *in_Observer_Info,
                                                             tp_cli_client_observer_callback_for_observe_channels callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

    void                (*tp_cli_client_handler_callback_for_handle_channels)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_client_handler_call_handle_channels
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Account,
                                                             const gchar *in_Connection,
                                                             const GPtrArray *in_Channels,
                                                             const GPtrArray *in_Requests_Satisfied,
                                                             guint64 in_User_Action_Time,
                                                             GHashTable *in_Handler_Info,
                                                             tp_cli_client_handler_callback_for_handle_channels callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_client_interface_requests_callback_for_add_request)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_client_interface_requests_call_add_request
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Request,
                                                             GHashTable *in_Properties,
                                                             tp_cli_client_interface_requests_callback_for_add_request callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_client_interface_requests_callback_for_remove_request)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_client_interface_requests_call_remove_request
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Request,
                                                             const gchar *in_Error,
                                                             const gchar *in_Message,
                                                             tp_cli_client_interface_requests_callback_for_remove_request callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

    void                (*tp_cli_client_approver_callback_for_add_dispatch_operation)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_client_approver_call_add_dispatch_operation
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const GPtrArray *in_Channels,
                                                             const gchar *in_DispatchOperation,
                                                             GHashTable *in_Properties,
                                                             tp_cli_client_approver_callback_for_add_dispatch_operation callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpClient

## Description

Each client to which the ChannelDispatcher can send channels must implement the Client interface. This object represents such a client, and is mainly useful in the implementation of the ChannelDispatcher itself.

## Details

### struct TpClient

    struct TpClient;

Each client to which the ChannelDispatcher can send channels must implement the Client interface. This object represents such a client, and is mainly useful in the implementation of the ChannelDispatcher itself.

This proxy is usable but very incomplete: accessors for D-Bus properties will be added in a later version of telepathy-glib, along with a mechanism similar to `tp_connection_call_when_ready()`.

Many operations performed on a Client are done via D-Bus properties. Until convenience methods for this are implemented, use of the generic `tp_cli_dbus_properties_call_get_all()` and `tp_cli_dbus_properties_call_set()` methods is recommended.

Since 0.7.32

### struct TpClientClass

    struct TpClientClass {
    };

The class of a TpClient.

### tp_client_init_known_interfaces ()

    void                tp_client_init_known_interfaces     (void);

Ensure that the known interfaces for TpClient 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_CLIENT`.

Since 0.7.32

### tp_cli_client_observer_callback_for_observe_channels ()

    void                (*tp_cli_client_observer_callback_for_observe_channels)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

    TpProxyPendingCall * tp_cli_client_observer_call_observe_channels
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Account,
                                                             const gchar *in_Connection,
                                                             const GPtrArray *in_Channels,
                                                             const gchar *in_Dispatch_Operation,
                                                             const GPtrArray *in_Requests_Satisfied,
                                                             GHashTable *in_Observer_Info,
                                                             tp_cli_client_observer_callback_for_observe_channels callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a ObserveChannels method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when channels in which the observer has registered an interest are announced in a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> signal.</p> <p>If the same NewChannels signal announces some channels that match the filter, and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.</p> <p>If the channel dispatcher will split up the channels from a single NewChannels signal and dispatch them separately (for instance because no installed Handler can handle all of them), it will call ObserveChannels several times.</p> <p>The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).</p> <tp:rationale> <p>The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets ObserveChannels, text channel handler gets <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> channel handler starts up faster and acknowledges messages, logger never sees those messages.</p> </tp:rationale> <p>The channel dispatcher SHOULD NOT change its behaviour based on whether this method succeeds or fails: there are no defined D-Bus errors for this method, and if it fails, this only indicates that an Observer is somehow broken.</p> <tp:rationale> <p>The expected error response in the channel dispatcher is to log a warning, and otherwise continue as though this method had succeeded.</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="org.freedesktop.Telepathy">Account</tp:dbus-ref> with which the channels are associated. The well-known bus name to use is that of the <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
`in_Connection` : | Used to pass an 'in' argument: The <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> with which the channels are associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'.
`in_Channels` : | Used to pass an 'in' argument: The <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s and their properties. Their well-known bus names are all the same as that of the Connection.
`in_Dispatch_Operation` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The path to the <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> for these channels, or the special value '/' if there is no ChannelDispatchOperation (because the channels were requested, not incoming).</p> <p>If the Observer calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned from <tp:member-ref>ObserveChannels</tp:member-ref>.</p> <tp:rationale> <p>This allows an Observer to <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> a set of channels without having to match up calls to this method with calls to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p> </tp:rationale>
`in_Requests_Satisfied` : | Used to pass an 'in' argument: The <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>s satisfied by these channels. <tp:rationale> If the same process is an Observer and a Handler, it can be useful to be given this information as soon as possible (it will also be passed to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler.HandleChannels</tp:dbus-ref>). </tp:rationale>
`in_Observer_Info` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about these channels. Currently defined keys are:</p> <dl> <dt><code>recovering</code> - b</dt> <dd><code>True</code> if ObserveChannels was called for an existing channel (due to the <tp:member-ref>Recover</tp:member-ref> property being <code>True</code>); <code>False</code> or omitted otherwise. <tp:rationale> This allows observers to distinguish between new channels (the normal case), and existing channels that were given to the observer in order to catch up on previous events (perhaps after a previous instance of the same observer crashed). </tp:rationale> </dd> <dt><code>request-properties</code> - a{oa{sv}}</dt> <dd>A map from <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> paths listed in <var>Requests_Satisfied</var> to <tp:type>Qualified_Property_Value_Map</tp:type>s containing namespaced immutable properties of each request.</dd> </dl> <p>All defined keys for this dictionary are optional; observers MAY safely ignore any entry in this dictionary.</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_client_handler_callback_for_handle_channels ()

    void                (*tp_cli_client_handler_callback_for_handle_channels)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

    TpProxyPendingCall * tp_cli_client_handler_call_handle_channels
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Account,
                                                             const gchar *in_Connection,
                                                             const GPtrArray *in_Channels,
                                                             const GPtrArray *in_Requests_Satisfied,
                                                             guint64 in_User_Action_Time,
                                                             GHashTable *in_Handler_Info,
                                                             tp_cli_client_handler_callback_for_handle_channels callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a HandleChannels method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when this client should handle these channels, or when this client should present channels that it is already handling to the user (e.g. bring them into the foreground).</p> <tp:rationale> <p>Clients are expected to know what channels they're already handling, and which channel object path corresponds to which window or tab. This can easily be done using a hash table keyed by channels' object paths.</p> </tp:rationale> <p>This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY attempt to dispatch the channels to another handler, or close the channels.</p> <p>If closing the channels, it is RECOMMENDED that the channel dispatcher attempts to close the channels using <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, but resorts to calling <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> (if available) or ignoring the channel (if not) if the same handler repeatedly fails to handle channels.</p> <p>After HandleChannels returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.</p> <tp:rationale> <p>If a process has multiple Client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling should remain unaffected.</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="org.freedesktop.Telepathy">Account</tp:dbus-ref> with which the channels are associated. The well-known bus name to use is that of the <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
`in_Connection` : | Used to pass an 'in' argument: The Connection with which the channels are associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'.
`in_Channels` : | Used to pass an 'in' argument: The channels and their immutable properties. Their well-known bus name is the same as that of the Connection.
`in_Requests_Satisfied` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The requests satisfied by these channels.</p> <tp:rationale> <p>If the handler implements Requests, this tells it that these channels match previous <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> calls that it may have received.</p> <p>There can be more than one, if they were EnsureChannel requests.</p> </tp:rationale>
`in_User_Action_Time` : | Used to pass an 'in' argument: The time at which user action occurred, or 0 if this channel is to be handled for some reason not involving user action. Handlers SHOULD use this for focus-stealing prevention, if applicable. This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> but is unsigned for historical reasons.
`in_Handler_Info` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about these channels. Currently defined keys are:</p> <dl> <dt><code>request-properties</code> - a{oa{sv}}</dt> <dd>A map from <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> paths listed in <var>Requests_Satisfied</var> to <tp:type>Qualified_Property_Value_Map</tp:type>s containing namespaced immutable properties of each request.</dd> </dl> <p>When more keys are defined for this dictionary, all will be optional; handlers MAY safely ignore any entry in this dictionary.</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_client_interface_requests_callback_for_add_request ()

    void                (*tp_cli_client_interface_requests_callback_for_add_request)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

    TpProxyPendingCall * tp_cli_client_interface_requests_call_add_request
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Request,
                                                             GHashTable *in_Properties,
                                                             tp_cli_client_interface_requests_callback_for_add_request callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a AddRequest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the ChannelDispatcher to indicate that channels have been requested, and that if the request is successful, they will probably be handled by this Handler. The ChannelDispatcher SHOULD only call this method on one handler per request.</p> <tp:rationale> <p>This allows the UI to start preparing to handle the channels in advance (e.g. render a window with an &quot;in progress&quot; message), improving perceived responsiveness.</p> <p>The use of &quot;probably&quot; is because you can't necessarily tell from a channel request which handler will handle particular channels. A reasonable heuristic would be to match the request against the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>, and respect the preferred handler (if any).</p> </tp:rationale> <p>If the request succeeds and is given to the expected Handler, the Requests_Satisfied parameter to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> can be used to match the channel to a previous AddRequest call.</p> <tp:rationale> <p>This lets the UI direct the channels to the window that it already opened.</p> </tp:rationale> <p>If the request fails, the expected handler is notified by the channel dispatcher calling its <tp:member-ref>RemoveRequest</tp:member-ref> method.</p> <tp:rationale> <p>This lets the UI close the window or display the error.</p> </tp:rationale> <p>The channel dispatcher SHOULD remember which handler was notified, and if the channel request succeeds, it SHOULD dispatch the channels to the expected handler, unless the channels do not match that handler's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>. If the channels are not dispatched to the expected handler, the handler that was expected is notified by the channel dispatcher calling its <tp:member-ref>RemoveRequest</tp:member-ref> method with the NotYours error.</p> <tp:rationale> <p>Expected handling is for the UI to close the window it previously opened.</p> </tp:rationale> <p>Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.</p> <tp:rationale> <p>Calls to this method are merely a notification.</p> </tp:rationale>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_Request` : | Used to pass an 'in' argument: The <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which MUST have been returned by <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> before this method is called. <tp:rationale> See those methods for the rationale of this ordering. </tp:rationale>
`in_Properties` : | Used to pass an 'in' argument: <p>Some of the properties of the ChannelRequest. To avoid race conditions, this dictionary MUST NOT include properties whose values could subsequently change. It SHOULD include as many properties as possible, given that constraint.</p> <p>In particular, the properties <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>, <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref> MUST be included, and <tp:dbus-ref namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> MUST be included if implemented.</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_client_interface_requests_callback_for_remove_request ()

    void                (*tp_cli_client_interface_requests_callback_for_remove_request)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

    TpProxyPendingCall * tp_cli_client_interface_requests_call_remove_request
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_Request,
                                                             const gchar *in_Error,
                                                             const gchar *in_Message,
                                                             tp_cli_client_interface_requests_callback_for_remove_request callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RemoveRequest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the ChannelDispatcher to indicate that a request previously passed to <tp:member-ref>AddRequest</tp:member-ref> has failed and should be disregarded.</p> <p>Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.</p> <tp:rationale> <p>Calls to this method are merely a notification.</p> </tp:rationale>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_Request` : | Used to pass an 'in' argument: The request that failed.
`in_Error` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of the D-Bus error with which the request failed.</p> <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>, this indicates that the request succeeded, but all the resulting channels were given to some other handler.</p>
`in_Message` : | Used to pass an 'in' argument: Any message supplied with the D-Bus error.
`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_client_approver_callback_for_add_dispatch_operation ()

    void                (*tp_cli_client_approver_callback_for_add_dispatch_operation)
                                                            (TpClient *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

    TpProxyPendingCall * tp_cli_client_approver_call_add_dispatch_operation
                                                            (TpClient *proxy,
                                                             gint timeout_ms,
                                                             const GPtrArray *in_Channels,
                                                             const gchar *in_DispatchOperation,
                                                             GHashTable *in_Properties,
                                                             tp_cli_client_approver_callback_for_add_dispatch_operation callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a AddDispatchOperation method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when a ChannelDispatchOperation in which the approver has registered an interest is created, or when the approver starts up while such channel dispatch operations already exist.</p> <p>The channel dispatcher SHOULD call this method on all approvers at the same time. If an approver returns an error from this method, the approver is assumed to be faulty.</p> <p>If no approvers return from this method successfully (including situations where there are no matching approvers at all), the channel dispatcher SHOULD consider this to be an error, and recover by dispatching the channel to the most preferred handler.</p> <tp:rationale> Processes that aren't approvers (or don't at least ensure that there is some approver) probably shouldn't be making connections anyway, so there should always be at least one approver running. </tp:rationale>

`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 initial value of the <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Channels</tp:dbus-ref> property, containing the <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s to be dispatched and their properties.</p> <tp:rationale> <p>This can't be signalled to the approver through the Properties parameter of this method, because Channels is not an immutable property.</p> </tp:rationale> <p>This argument always contains all of the channels in the channel dispatch operation, even if not all of them actually match the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p> <tp:rationale> <p>This seems the least bad way to handle such a situation; see the discussion on <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug 21090</a>.</p> </tp:rationale> <p>The actual channels to be dispatched may reduce as channels are closed: this is signalled by <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>. </p> <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>. (if desired) before returning from AddDispatchOperation, since those signals are guaranteed not to be emitted until after all AddDispatchOperation calls have returned (with success or failure) or timed out.</p>
`in_DispatchOperation` : | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> to be processed.</p>
`in_Properties` : | Used to pass an 'in' argument: <p>Properties of the channel dispatch operation. The keys MUST be fully qualified D-Bus property names. This MUST NOT include properties that could change, SHOULD include as many properties as possible given that constraint, and MUST include at least the <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>, <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref> properties.</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.