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);
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_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
  "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.

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", 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.

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

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.

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)             : 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