## TpChannelRequest

TpChannelRequest — proxy object for a request to the Telepathy channel dispatcher

## Synopsis

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

                        TpChannelRequest;
                        TpChannelRequestClass;
    TpChannelRequest *  tp_channel_request_new              (TpDBusDaemon *bus_daemon,
                                                             const gchar *object_path,
                                                             GHashTable *immutable_properties,
                                                             GError **error);
    void                tp_channel_request_init_known_interfaces
                                                            (void);

    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,
                                                             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);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpChannelRequest

## Signals

      "succeeded"                                      : Run Last / Has Details

## Description

Requesting a channel from the channel dispatcher can take some time, so an object is created in the channel dispatcher to represent each request. Objects of the TpChannelRequest class provide access to one of those objects.

## Details

### TpChannelRequest

    typedef struct _TpChannelRequest TpChannelRequest;

Requesting a channel from the channel dispatcher can take some time, so an object is created in the channel dispatcher to represent each request. This proxy represents one of those objects.

Any client can call `tp_cli_channel_request_call_cancel()` at any time to attempt to cancel the request.

On success, the "succeeded" signal will be emitted. Immediately after that, the "invalidated" signal will be emitted, with the domain `TP_DBUS_ERRORS` and the error code `TP_DBUS_ERROR_OBJECT_REMOVED` (this is not an error condition, it merely indicates that the channel request no longer exists).

On failure, the "invalidated" signal will be emitted with some other suitable error, usually from the `TP_ERRORS` domain.

If the channel dispatcher crashes or exits, the "invalidated" signal will be emitted with the domain `TP_DBUS_ERRORS` and the error code `TP_DBUS_ERROR_NAME_OWNER_LOST`.

This proxy is usable but incomplete: accessors for the Account, UserActionTime, PreferredHandler, Requests and Interfaces properties will be added in a later version of telepathy-glib, along with a mechanism similar to `tp_connection_call_when_ready()`.

Until suitable convenience methods are implemented, the generic `tp_cli_dbus_properties_call_get_all()` method can be used to get those properties.

Since 0.7.32

### TpChannelRequestClass

    typedef struct {
    } TpChannelRequestClass;

The class of a TpChannelRequest.

### tp_channel_request_new ()

    TpChannelRequest *  tp_channel_request_new              (TpDBusDaemon *bus_daemon,
                                                             const gchar *object_path,
                                                             GHashTable *immutable_properties,
                                                             GError **error);

Convenience function to create a new channel request proxy.

If the channel request was newly created, the client making the request is responsible for calling `tp_cli_channel_request_call_proceed()` when it is ready for the channel request to proceed.

The `immutable_properties` argument is not yet used.

`bus_daemon` : | Proxy for the D-Bus daemon
`object_path` : | The non-NULL object path of this channel request
`immutable_properties` : | As many as are known of the immutable D-Bus properties of this channel request, or `NULL` if none are known
`error` : | Used to raise an error if `NULL` is returned
Returns : | a new reference to an channel request proxy, or `NULL` if `object_path` is not syntactically valid or the channel dispatcher is not running

### tp_channel_request_init_known_interfaces ()

    void                tp_channel_request_init_known_interfaces
                                                            (void);

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

Since 0.7.32

### 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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.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>org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, or an error generated to represent failure to establish the <tp:dbus-ref namespace="org.freedesktop.Telepathy">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,
                                                             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
`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>

`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.

## Signal Details

### The `"succeeded"` signal

    void                user_function                      (TpChannelRequest *self,
                                                            gpointer          user_data)      : Run Last / Has Details

Emitted when the channel request succeeds.

`self` : | the channel request proxy
`user_data` : | user data set when the signal handler was connected.

## See Also

TpChannelDispatcher