## TpAccountChannelRequest

TpAccountChannelRequest — Object used to request a channel from a TpAccount

## Synopsis

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

                        TpAccountChannelRequest;
    TpAccountChannelRequest * tp_account_channel_request_new
                                                            (TpAccount *account,
                                                             GHashTable *request,
                                                             gint64 user_action_time);
    TpAccountChannelRequest * tp_account_channel_request_new_vardict
                                                            (TpAccount *account,
                                                             GVariant *request,
                                                             gint64 user_action_time);
    GHashTable *        tp_account_channel_request_get_request
                                                            (TpAccountChannelRequest *self);
    GVariant *          tp_account_channel_request_dup_request
                                                            (TpAccountChannelRequest *self);
    gint64              tp_account_channel_request_get_user_action_time
                                                            (TpAccountChannelRequest *self);
    TpAccount *         tp_account_channel_request_get_account
                                                            (TpAccountChannelRequest *self);
    void                tp_account_channel_request_set_target_contact
                                                            (TpAccountChannelRequest *self,
                                                             TpContact *contact);
    void                tp_account_channel_request_set_target_id
                                                            (TpAccountChannelRequest *self,
                                                             TpHandleType handle_type,
                                                             const gchar *identifier);
    void                tp_account_channel_request_set_request_property
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *name,
                                                             GVariant *value);
    TpAccountChannelRequest * tp_account_channel_request_new_text
                                                            (TpAccount *account,
                                                             gint64 user_action_time);
    TpAccountChannelRequest * tp_account_channel_request_new_audio_call
                                                            (TpAccount *account,
                                                             gint64 user_action_time);
    TpAccountChannelRequest * tp_account_channel_request_new_audio_video_call
                                                            (TpAccount *account,
                                                             gint64 user_action_time);
    TpAccountChannelRequest * tp_account_channel_request_new_file_transfer
                                                            (TpAccount *account,
                                                             const gchar *filename,
                                                             const gchar *mime_type,
                                                             guint64 size,
                                                             gint64 user_action_time);
    void                tp_account_channel_request_set_file_transfer_description
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *description);
    void                tp_account_channel_request_set_file_transfer_initial_offset
                                                            (TpAccountChannelRequest *self,
                                                             guint64 offset);
    void                tp_account_channel_request_set_file_transfer_timestamp
                                                            (TpAccountChannelRequest *self,
                                                             guint64 timestamp);
    void                tp_account_channel_request_set_file_transfer_uri
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *uri);
    void                tp_account_channel_request_create_and_handle_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpChannel *         tp_account_channel_request_create_and_handle_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             TpHandleChannelsContext **context,
                                                             GError **error);
    void                tp_account_channel_request_ensure_and_handle_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpChannel *         tp_account_channel_request_ensure_and_handle_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             TpHandleChannelsContext **context,
                                                             GError **error);
    void                tp_account_channel_request_create_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_account_channel_request_create_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_account_channel_request_ensure_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_account_channel_request_ensure_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_account_channel_request_create_and_observe_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpChannel *         tp_account_channel_request_create_and_observe_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_account_channel_request_ensure_and_observe_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpChannel *         tp_account_channel_request_ensure_and_observe_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_account_channel_request_set_channel_factory
                                                            (TpAccountChannelRequest *self,
                                                             TpClientChannelFactory *factory);
    TpChannelRequest *  tp_account_channel_request_get_channel_request
                                                            (TpAccountChannelRequest *self);
    void                tp_account_channel_request_set_hint (TpAccountChannelRequest *self,
                                                             const gchar *key,
                                                             GVariant *value);
    void                tp_account_channel_request_set_hints
                                                            (TpAccountChannelRequest *self,
                                                             GHashTable *hints);
    void                tp_account_channel_request_set_delegate_to_preferred_handler
                                                            (TpAccountChannelRequest *self,
                                                             gboolean delegate);
    void                (*TpAccountChannelRequestDelegatedChannelCb)
                                                            (TpAccountChannelRequest *request,
                                                             TpChannel *channel,
                                                             gpointer user_data);
    void                tp_account_channel_request_set_delegated_channel_callback
                                                            (TpAccountChannelRequest *self,
                                                             TpAccountChannelRequestDelegatedChannelCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);

## Object Hierarchy

      GObject
       +----TpAccountChannelRequest

## Properties

      "account"                  TpAccount*            : Read / Write / Construct Only
      "channel-request"          TpChannelRequest*     : Read
      "request"                  GHashTable_gchararray+GValue_*  : Read / Write / Construct Only
      "request-vardict"          GVariant*             : Read / Write / Construct Only
      "user-action-time"         gint64                : Read / Write / Construct Only

## Signals

      "re-handled"                                     : Has Details

## Description

A TpAccountChannelRequest object is used to request a channel using the ChannelDispatcher. Once created, use one of the create or ensure async method to actually request the channel.

Note that each TpAccountChannelRequest object can only be used to create one channel. You can't call a create or ensure method more than once on the same TpAccountChannelRequest.

Once the channel has been created you can use the TpAccountChannelRequest::re-handled: signal to be notified when the channel has to be re-handled. This can be useful for example to move its window to the foreground, if applicable.

Using this object is appropriate for most channel types. For a contact search channel, use `tp_contact_search_new_async()` instead.

## Details

### TpAccountChannelRequest

    typedef struct _TpAccountChannelRequest TpAccountChannelRequest;

Data structure representing a TpAccountChannelRequest object.

Since 0.11.12

### tp_account_channel_request_new ()

    TpAccountChannelRequest * tp_account_channel_request_new
                                                            (TpAccount *account,
                                                             GHashTable *request,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object.

`account` : | a TpAccount
`request` : | the requested properties of the channel (see "request"). [transfer none][element-type utf8 GObject.Value]
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.11.12

### tp_account_channel_request_new_vardict ()

    TpAccountChannelRequest * tp_account_channel_request_new_vardict
                                                            (TpAccount *account,
                                                             GVariant *request,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object.

If `request` is a floating reference, this function will take ownership of it, much like `g_variant_ref_sink()`. See documentation of that function for details.

`account` : | a TpAccount
`request` : | the requested properties of the channel (see "request") as a `G_VARIANT_TYPE_VARDICT`
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.19.10

### tp_account_channel_request_get_request ()

    GHashTable *        tp_account_channel_request_get_request
                                                            (TpAccountChannelRequest *self);

Return the "request" construct-only property

`self` : | a TpAccountChannelRequest
Returns : | the value of "request". [transfer none]

Since 0.11.12

### tp_account_channel_request_dup_request ()

    GVariant *          tp_account_channel_request_dup_request
                                                            (TpAccountChannelRequest *self);

Return the "request-vardict" construct-only property.

`self` : | a TpAccountChannelRequest
Returns : | the value of "request-vardict". [transfer full]

Since 0.19.10

### tp_account_channel_request_get_user_action_time ()

    gint64              tp_account_channel_request_get_user_action_time
                                                            (TpAccountChannelRequest *self);

Return the "user-action-time" construct-only property

`self` : | a TpAccountChannelRequest
Returns : | the value of "user-action-time"

Since 0.11.12

### tp_account_channel_request_get_account ()

    TpAccount *         tp_account_channel_request_get_account
                                                            (TpAccountChannelRequest *self);

Return the "account" construct-only property

`self` : | a TpAccountChannelRequest
Returns : | the value of "account". [transfer none]

Since 0.11.12

### tp_account_channel_request_set_target_contact ()

    void                tp_account_channel_request_set_target_contact
                                                            (TpAccountChannelRequest *self,
                                                             TpContact *contact);

Configure this request to create a peer-to-peer channel with `contact` as the other peer.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`contact` : | the contact to be contacted

Since 0.19.0

### tp_account_channel_request_set_target_id ()

    void                tp_account_channel_request_set_target_id
                                                            (TpAccountChannelRequest *self,
                                                             TpHandleType handle_type,
                                                             const gchar *identifier);

Configure this request to create a channel with `identifier`, an identifier of type `handle_type`.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`handle_type` : | the type of `identifier`, typically `TP_HANDLE_TYPE_CONTACT` or `TP_HANDLE_TYPE_ROOM`
`identifier` : | the unique identifier of the contact, room etc. to be contacted

Since 0.19.0

### tp_account_channel_request_set_request_property ()

    void                tp_account_channel_request_set_request_property
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *name,
                                                             GVariant *value);

Configure this channel request to include the given property, as documented in the Telepathy D-Bus API Specification or an implementation-specific extension.

Using this method is not recommended, but it can be necessary for experimental or implementation-specific interfaces.

If the property is not supported by the protocol or channel type, the channel request will fail. Use TpCapabilities and the Telepathy D-Bus API Specification to determine which properties are available.

If `value` is a floating reference, this method takes ownership of it by using `g_variant_ref_sink()`. This allows convenient inline use of GVariant constructors:

    tp_account_channel_request_set_request_property (acr, "com.example.Int",
        g_variant_new_int32 (17));
    tp_account_channel_request_set_request_property (acr, "com.example.String",
        g_variant_new_string ("ferret"));

It is an error to provide a `value` which contains types not supported by D-Bus.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`name` : | a D-Bus property name
`value` : | an arbitrary value for the property

Since 0.19.0

### tp_account_channel_request_new_text ()

    TpAccountChannelRequest * tp_account_channel_request_new_text
                                                            (TpAccount *account,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object which will yield a Text channel.

After creating the request, you will also need to set the "target" of the channel by calling one of the following functions:

- `tp_account_channel_request_set_target_contact()`

- `tp_account_channel_request_set_target_id()`

`account` : | a TpAccount
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.19.0

### tp_account_channel_request_new_audio_call ()

    TpAccountChannelRequest * tp_account_channel_request_new_audio_call
                                                            (TpAccount *account,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object which will yield a Call channel, initially carrying audio only.

After creating the request, you will usually also need to set the "target" of the channel by calling one of the following functions:

- `tp_account_channel_request_set_target_contact()`

- `tp_account_channel_request_set_target_id()`

To call a contact, either use `tp_account_channel_request_set_target_contact()` or one of the generic methods that takes a handle type argument. To check whether this is possible, use `tp_capabilities_supports_audio_call()` with `handle_type` set to `TP_HANDLE_TYPE_CONTACT`.

In some protocols, it is possible to create a Call channel without setting a target at all, which will result in a new, empty conference call. To test whether this is possible, use `tp_capabilities_supports_audio_call()` with `handle_type` set to `TP_HANDLE_TYPE_NONE`.

`account` : | a TpAccount
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.19.0

### tp_account_channel_request_new_audio_video_call ()

    TpAccountChannelRequest * tp_account_channel_request_new_audio_video_call
                                                            (TpAccount *account,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object which will yield a Call channel, initially carrying both audio and video.

This is the same as `tp_account_channel_request_new_audio_call()`, except that the channel will initially carry video as well as audio, and instead of using `tp_capabilities_supports_audio_call()` you should test capabilities with `tp_capabilities_supports_audio_video_call()`.

See the documentation of `tp_account_channel_request_new_audio_call()` for details of how to set the target (contact, chatroom etc.) for the call.

`account` : | a TpAccount
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.19.0

### tp_account_channel_request_new_file_transfer ()

    TpAccountChannelRequest * tp_account_channel_request_new_file_transfer
                                                            (TpAccount *account,
                                                             const gchar *filename,
                                                             const gchar *mime_type,
                                                             guint64 size,
                                                             gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object, which will yield a FileTransfer channel to send a file to a contact.

After creating the request, you will also need to set the "target" of the channel by calling one of the following functions:

- `tp_account_channel_request_set_target_contact()`

- `tp_account_channel_request_set_target_id()`

`account` : | a TpAccount
`filename` : | a suggested name for the file, which should not contain directories or directory separators (for example, if you are sending a file called /home/user/monkey.pdf, set this to monkey.pdf)
`mime_type` : | the MIME type (content-type) of the file; a `NULL` value is allowed, and is treated as "application/octet-stream". [allow-none]
`size` : | the file's size in bytes
`user_action_time` : | the time of the user action that caused this request, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see "user-action-time")
Returns : | a new TpAccountChannelRequest object

Since 0.19.0

### tp_account_channel_request_set_file_transfer_description ()

    void                tp_account_channel_request_set_file_transfer_description
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *description);

Configure this channel request to provide the recipient of the file with the given description.

If file descriptions are not supported by the protocol, or if this method is used on a request that is not actually a file transfer, the channel request will fail. Use `tp_capabilities_supports_file_transfer_description()` to determine whether outgoing file transfers can have a description.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`description` : | a description of the file

Since 0.19.0

### tp_account_channel_request_set_file_transfer_initial_offset ()

    void                tp_account_channel_request_set_file_transfer_initial_offset
                                                            (TpAccountChannelRequest *self,
                                                             guint64 offset);

Configure this channel request to inform the recipient of the file that this channel will not send the first `offset` bytes of the file. In some protocols, this can be used to resume an interrupted transfer.

If this method is not called, the default is to start from the beginning of the file (equivalent to `offset` = 0).

If offsets greater than 0 are not supported by the protocol, or if this method is used on a request that is not actually a file transfer, the channel request will fail. Use `tp_capabilities_supports_file_transfer_initial_offset()` to determine whether offsets greater than 0 are available.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`offset` : | the offset into the file at which the transfer will start

Since 0.19.0

### tp_account_channel_request_set_file_transfer_timestamp ()

    void                tp_account_channel_request_set_file_transfer_timestamp
                                                            (TpAccountChannelRequest *self,
                                                             guint64 timestamp);

Configure this channel request to accompany the file transfer with the given modification timestamp for the file.

If file timestamps are not supported by the protocol, or if this method is used on a request that is not actually a file transfer, the channel request will fail. Use `tp_capabilities_supports_file_transfer_date()` to determine whether outgoing file transfers can have a timestamp.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`timestamp` : | the modification timestamp of the file, in seconds since the Unix epoch (the beginning of 1970 in the UTC time zone), as returned by `g_date_time_to_unix()`

Since 0.19.0

### tp_account_channel_request_set_file_transfer_uri ()

    void                tp_account_channel_request_set_file_transfer_uri
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *uri);

Configure this channel request to provide other local Telepathy components with the URI of the file being sent. Unlike most properties on a file transfer channel, this information is not sent to the recipient of the file; instead, it is signalled on D-Bus for use by other Telepathy components.

The URI should usually be a `file` URI as defined by RFC 1738 §3.10 (for instance, `file:///path/to/file` or `file://localhost/path/to/file`). If a remote resource is being transferred to a contact, it may have a different scheme, such as `http`.

Even if this method is used, the connection manager will not read the file from disk: the handler for the channel is still responsible for streaming the file. However, providing the URI allows a local logger to log which file was transferred, for instance.

If this functionality is not supported by the connection manager, or if this method is used on a request that is not actually a file transfer, the channel request will fail. Use `tp_capabilities_supports_file_transfer_uri()` to determine whether outgoing file transfers can have a URI.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`uri` : | the source URI for the file

Since 0.19.0

### tp_account_channel_request_create_and_handle_channel_async ()

    void                tp_account_channel_request_create_and_handle_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls CreateChannel on the ChannelDispatcher to create a channel with the properties defined in "request" that you are going to handle yourself. When the operation is finished, `callback` will be called. You can then call `tp_account_channel_request_create_and_handle_channel_finish()` to get the result of the operation.

(Behind the scenes, this works by creating a temporary TpBaseClient, then acting like `tp_account_channel_request_create_channel_async()` with the temporary TpBaseClient as the `preferred_handler`.)

The caller is responsible for closing the channel with `tp_cli_channel_call_close()` when it has finished handling it.

`self` : | a TpAccountChannelRequest
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.11.12

### tp_account_channel_request_create_and_handle_channel_finish ()

    TpChannel *         tp_account_channel_request_create_and_handle_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             TpHandleChannelsContext **context,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_create_and_handle_channel_async()`.

See `tp_account_channel_request_ensure_and_handle_channel_finish()` for details of how `context` can be used.

The caller is responsible for closing the channel with `tp_cli_channel_call_close()` when it has finished handling it.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`context` : | pointer used to return a reference to the context of the `HandleChannels()` call, or `NULL`. [out][allow-none][transfer full]
`error` : | a GError to fill
Returns : | a new reference on a TpChannel if the channel was successfully created and you are handling it, otherwise `NULL`. [transfer full][allow-none]

Since 0.11.12

### tp_account_channel_request_ensure_and_handle_channel_async ()

    void                tp_account_channel_request_ensure_and_handle_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls EnsureChannel on the ChannelDispatcher to create a channel with the properties defined in "request" that you are going to handle yourself. When the operation is finished, `callback` will be called. You can then call `tp_account_channel_request_ensure_and_handle_channel_finish()` to get the result of the operation.

If the channel already exists and is already being handled, or if a newly created channel is sent to a different handler, this operation will fail with the error `TP_ERROR_NOT_YOURS`. The other handler will be notified that the channel was requested again (for instance with "re-handled", TpBaseClientClassHandleChannelsImpl or "callback"), and can move its window to the foreground, if applicable.

(Behind the scenes, this works by creating a temporary TpBaseClient, then acting like `tp_account_channel_request_ensure_channel_async()` with the temporary TpBaseClient as the `preferred_handler`.)

`self` : | a TpAccountChannelRequest
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.11.12

### tp_account_channel_request_ensure_and_handle_channel_finish ()

    TpChannel *         tp_account_channel_request_ensure_and_handle_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             TpHandleChannelsContext **context,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_ensure_and_handle_channel_async()`.

If the channel already exists and is already being handled, or if a newly created channel is sent to a different handler, this operation will fail with the error `TP_ERROR_NOT_YOURS`.

`context` can be used to obtain extensible information about the channel via `tp_handle_channels_context_get_handler_info()`, and any similar methods that are added in future. It is not valid for the caller of this method to call `tp_handle_channels_context_accept()`, `tp_handle_channels_context_delay()` or `tp_handle_channels_context_fail()`.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`context` : | pointer used to return a reference to the context of the `HandleChannels()` call, or `NULL`. [out][allow-none][transfer full]
`error` : | a GError to fill
Returns : | a new reference on a TpChannel if the channel was successfully created and you are handling it, otherwise `NULL`. [transfer full][allow-none]

Since 0.11.12

### tp_account_channel_request_create_channel_async ()

    void                tp_account_channel_request_create_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls CreateChannel on the ChannelDispatcher to create a channel with the properties defined in "request" and let the ChannelDispatcher dispatch it to an handler. `callback` will be called when the channel has been created and dispatched, or the request has failed. You can then call `tp_account_channel_request_create_channel_finish()` to get the result of the operation.

`self` : | a TpAccountChannelRequest
`preferred_handler` : | Either the well-known bus name (starting with `TP_CLIENT_BUS_NAME_BASE`) of the preferred handler for the channel, or `NULL` to indicate that any handler would be acceptable.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.11.12

### tp_account_channel_request_create_channel_finish ()

    gboolean            tp_account_channel_request_create_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_create_channel_async()`.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | `TRUE` if the channel was successfully created and dispatched, otherwise `FALSE`.

Since 0.11.12

### tp_account_channel_request_ensure_channel_async ()

    void                tp_account_channel_request_ensure_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls EnsureChannel on the ChannelDispatcher to create a channel with the properties defined in "request" and let the ChannelDispatcher dispatch it to an handler.

If a suitable channel already existed, its handler will be notified that the channel was requested again (for instance with "re-handled", TpBaseClientClassHandleChannelsImpl or "callback", if it is implemented using Telepathy-GLib), so that it can re-present the window to the user, for example. Otherwise, a new channel will be created and dispatched to a handler.

`callback` will be called when an existing channel's handler has been notified, a new channel has been created and dispatched, or the request has failed. You can then call `tp_account_channel_request_ensure_channel_finish()` to get the result of the operation.

`self` : | a TpAccountChannelRequest
`preferred_handler` : | Either the well-known bus name (starting with `TP_CLIENT_BUS_NAME_BASE`) of the preferred handler for the channel, or `NULL` to indicate that any handler would be acceptable.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.11.12

### tp_account_channel_request_ensure_channel_finish ()

    gboolean            tp_account_channel_request_ensure_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_ensure_channel_async()`.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | `TRUE` if the channel was successfully ensured and (re-)dispatched, otherwise `FALSE`.

Since 0.11.12

### tp_account_channel_request_create_and_observe_channel_async ()

    void                tp_account_channel_request_create_and_observe_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls CreateChannel on the ChannelDispatcher to create a channel with the properties defined in "request" and let the ChannelDispatcher dispatch it to an handler. `callback` will be called when the channel has been created and dispatched, or the request has failed. You can then call `tp_account_channel_request_create_channel_finish()` to get the result of the operation and a TpChannel representing the channel which has been created. Note that you are not handling this channel and so should interact with the channel as an Observer. See the Telepathy book for details about how clients should interact with channels.

`self` : | a TpAccountChannelRequest
`preferred_handler` : | Either the well-known bus name (starting with `TP_CLIENT_BUS_NAME_BASE`) of the preferred handler for the channel, or `NULL` to indicate that any handler would be acceptable.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.13.14

### tp_account_channel_request_create_and_observe_channel_finish ()

    TpChannel *         tp_account_channel_request_create_and_observe_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_create_and_observe_channel_async()`.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | a newly created TpChannel if the channel was successfully created and dispatched, otherwise `NULL`. [transfer full]

Since 0.13.14

### tp_account_channel_request_ensure_and_observe_channel_async ()

    void                tp_account_channel_request_ensure_and_observe_channel_async
                                                            (TpAccountChannelRequest *self,
                                                             const gchar *preferred_handler,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously calls EnsureChannel on the ChannelDispatcher to create a channel with the properties defined in "request" and let the ChannelDispatcher dispatch it to an handler. `callback` will be called when the channel has been created and dispatched, or the request has failed. You can then call `tp_account_channel_request_create_channel_finish()` to get the result of the operation and a TpChannel representing the channel which has been created. Note that you are not handling this channel and so should interact with the channel as an Observer. See the Telepathy book for details about how clients should interact with channels.

If a suitable channel already existed, its handler will be notified that the channel was requested again (for instance with "re-handled", TpBaseClientClassHandleChannelsImpl or "callback", if it is implemented using Telepathy-GLib), so that it can re-present the window to the user, for example. Otherwise, a new channel will be created and dispatched to a handler.

`self` : | a TpAccountChannelRequest
`preferred_handler` : | Either the well-known bus name (starting with `TP_CLIENT_BUS_NAME_BASE`) of the preferred handler for the channel, or `NULL` to indicate that any handler would be acceptable.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.13.14

### tp_account_channel_request_ensure_and_observe_channel_finish ()

    TpChannel *         tp_account_channel_request_ensure_and_observe_channel_finish
                                                            (TpAccountChannelRequest *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async channel creation started using `tp_account_channel_request_create_and_observe_channel_async()`.

`self` : | a TpAccountChannelRequest
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | a newly created TpChannel if the channel was successfully ensure and (re-)dispatched, otherwise `NULL`. [transfer full]

Since 0.13.14

### tp_account_channel_request_set_channel_factory ()

    void                tp_account_channel_request_set_channel_factory
                                                            (TpAccountChannelRequest *self,
                                                             TpClientChannelFactory *factory);

### Warning

`tp_account_channel_request_set_channel_factory` is deprecated and should not be used in newly-written code. since 0.15.5. The factory is taken from "account".

Set `factory` as the TpClientChannelFactory that will be used to create the channel requested by `self`. By default TpAutomaticProxyFactory is used.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`factory` : | a TpClientChannelFactory

Since 0.13.2

### tp_account_channel_request_get_channel_request ()

    TpChannelRequest *  tp_account_channel_request_get_channel_request
                                                            (TpAccountChannelRequest *self);

Return the "channel-request" property

`self` : | a TpAccountChannelRequest
Returns : | the value of "channel-request". [transfer none]

Since 0.13.13

### tp_account_channel_request_set_hint ()

    void                tp_account_channel_request_set_hint (TpAccountChannelRequest *self,
                                                             const gchar *key,
                                                             GVariant *value);

Set additional information about the channel request, which will be used in the resulting request's "hints" property.

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`key` : | the key used for the hint
`value` : | a variant containting the hint value. [transfer none]

Since 0.19.8

### tp_account_channel_request_set_hints ()

    void                tp_account_channel_request_set_hints
                                                            (TpAccountChannelRequest *self,
                                                             GHashTable *hints);

Set additional information about the channel request, which will be used as the value for the resulting request's "hints" property.

This function can't be called once `self` has been used to request a channel.

In high-level language bindings, use `tp_account_channel_request_set_hint()` instead.

`self` : | a TpAccountChannelRequest
`hints` : | a TP_HASH_TYPE_STRING_VARIANT_MAP

Since 0.13.14

### tp_account_channel_request_set_delegate_to_preferred_handler ()

    void                tp_account_channel_request_set_delegate_to_preferred_handler
                                                            (TpAccountChannelRequest *self,
                                                             gboolean delegate);

If `delegate` is `TRUE`, asks to the client currently handling the channels to delegate them to the preferred handler (passed when calling `tp_account_channel_request_ensure_channel_async()` for example).

This function can't be called once `self` has been used to request a channel.

`self` : | a TpAccountChannelRequest
`delegate` : | `TRUE` to request to delegate channels

Since 0.15.3

### TpAccountChannelRequestDelegatedChannelCb ()

    void                (*TpAccountChannelRequestDelegatedChannelCb)
                                                            (TpAccountChannelRequest *request,
                                                             TpChannel *channel,
                                                             gpointer user_data);

Called when a client asked us to delegate `channel` to another Handler. When this function is called you are no longer handling `channel`.

`request` : | a TpAccountChannelRequest instance
`channel` : | a TpChannel
`user_data` : | arbitrary user-supplied data passed to `tp_account_channel_request_set_delegated_channel_callback()`

Since 0.15.3

### tp_account_channel_request_set_delegated_channel_callback ()

    void                tp_account_channel_request_set_delegated_channel_callback
                                                            (TpAccountChannelRequest *self,
                                                             TpAccountChannelRequestDelegatedChannelCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);

Turn on support for the org.freedesktop.Telepathy.ChannelRequest.DelegateToPreferredHandler hint.

When receiving a request containing this hint, `self` will automatically delegate the channel to the preferred handler of the request and then call `callback` to inform the client that it is no longer handling this channel.

`callback` may be called any time after (and only after) requesting and handling the channel (i.e. you have called create_and_handle or ensure_and_handle).

This function can't be called once `self` has been used to request a channel.

See also: `tp_base_client_set_delegated_channels_callback()`

`self` : | a TpAccountChannelRequest
`callback` : | function called the channel requested using `self` is delegated, may not be `NULL`
`user_data` : | arbitrary user-supplied data passed to `callback`
`destroy` : | called with the `user_data` as argument, when `self` is destroyed

Since 0.15.3

## Property Details

### The `"account"` property

      "account"                  TpAccount*            : Read / Write / Construct Only

The TpAccount used to request the channel. Read-only except during construction.

This property can't be `NULL`.

Since 0.11.12

### The `"channel-request"` property

      "channel-request"          TpChannelRequest*     : Read

The TpChannelRequest used to request the channel, or `NULL` if the channel has not be requested yet.

This can be useful for example to compare with the TpChannelRequest objects received from the requests_satisfied argument of TpSimpleHandlerHandleChannelsImpl to check if the client is asked to handle the channel it just requested.

Note that the TpChannelRequest objects may be different while still representing the same ChannelRequest on D-Bus. You have to compare them using their object paths (`tp_proxy_get_object_path()`).

Since 0.13.13

### The `"request"` property

      "request"                  GHashTable_gchararray+GValue_*  : Read / Write / Construct Only

The desired D-Bus properties for the channel, represented as a GHashTable where the keys are strings and the values are GValue.

When constructing a new object, one of "request" or "request-vardict" must be set to a non-`NULL` value, and the other must remain unspecified.

Since 0.11.12

### The `"request-vardict"` property

      "request-vardict"          GVariant*             : Read / Write / Construct Only

The desired D-Bus properties for the channel.

When constructing a new object, one of "request" or "request-vardict" must be set to a non-`NULL` value, and the other must remain unspecified.

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.10

### The `"user-action-time"` property

      "user-action-time"         gint64                : Read / Write / Construct Only

The user action time that will be passed to the channel dispatcher when requesting the channel.

This may be the time at which user action occurred, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME`.

If `TP_USER_ACTION_TIME_NOT_USER_ACTION`, the action doesn't involve any user action. Clients should avoid stealing focus when presenting the channel.

If `TP_USER_ACTION_TIME_CURRENT_TIME`, clients SHOULD behave as though the user action happened at the current time, e.g. a client may request that its window gains focus.

On X11-based systems, GDK 2, GDK 3, Clutter 1.0 etc., `tp_user_action_time_from_x11()` can be used to convert an X11 timestamp to a Telepathy user action time.

If the channel request succeeds, this user action time will be passed on to the channel's handler. If the handler is a GUI, it may use `tp_user_action_time_should_present()` to decide whether to bring its window to the foreground.

Default value: 0

Since 0.11.12

## Signal Details

### The `"re-handled"` signal

    void                user_function                      (TpAccountChannelRequest *self,
                                                            TpChannel               *channel,
                                                            gint64                   user_action_time,
                                                            TpHandleChannelsContext *context,
                                                            gpointer                 user_data)             : Has Details

Emitted when the channel created using `self` has been "re-handled".

This means that a Telepathy client has made another request for a matching channel using an "ensure" API like `tp_account_channel_request_ensure_channel_async()`, while the channel still exists. Instead of creating a new channel, the channel dispatcher notifies the existing handler of `channel`, resulting in this signal.

Most GUI handlers should respond to this signal by checking `user_action_time`, and if appropriate, moving to the foreground.

`context` can be used to obtain extensible information about the channel via `tp_handle_channels_context_get_handler_info()`, and any similar methods that are added in future. It is not valid for the receiver of this signal to call `tp_handle_channels_context_accept()`, `tp_handle_channels_context_delay()` or `tp_handle_channels_context_fail()`.

`self` : | a TpAccountChannelRequest
`channel` : | the TpChannel being re-handled
`user_action_time` : | the time at which user action occurred, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME`; see "user-action-time"
`context` : | a TpHandleChannelsContext representing the context of the `HandleChannels()` call.
`user_data` : | user data set when the signal handler was connected.

Since 0.11.12