## TpAccountChannelRequest

TpAccountChannelRequest — Object used to request a channel from a TpAccount

## Synopsis

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

                        TpAccountChannelRequest;
    TpAccountChannelRequest * tp_account_channel_request_new
                                                            (TpAccount *account,
                                                             GHashTable *request,
                                                             gint64 user_action_time);
    GHashTable *        tp_account_channel_request_get_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_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);

## Object Hierarchy

      GObject
       +----TpAccountChannelRequest

## Properties

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

## Signals

      "re-handled"                                     : Run Last / 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.

## 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_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_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_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"), and can move its window to the foreground, if applicable. 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

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

This property can't be `NULL`.

Since 0.11.12

### 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.x, 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)             : Run Last / 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