TpAccountChannelRequest

TpAccountChannelRequest — Object used to request a channel from a TpAccount

Functions

TpAccountChannelRequest * tp_account_channel_request_new ()
GVariant * tp_account_channel_request_dup_request ()
gint64 tp_account_channel_request_get_user_action_time ()
TpAccount * tp_account_channel_request_get_account ()
void tp_account_channel_request_set_target_contact ()
void tp_account_channel_request_set_target_id ()
void tp_account_channel_request_set_request_property ()
TpAccountChannelRequest * tp_account_channel_request_new_text ()
void tp_account_channel_request_set_sms_channel ()
TpAccountChannelRequest * tp_account_channel_request_new_audio_call ()
TpAccountChannelRequest * tp_account_channel_request_new_audio_video_call ()
TpAccountChannelRequest * tp_account_channel_request_new_file_transfer ()
void tp_account_channel_request_set_file_transfer_description ()
void tp_account_channel_request_set_file_transfer_initial_offset ()
void tp_account_channel_request_set_file_transfer_timestamp ()
void tp_account_channel_request_set_file_transfer_uri ()
TpAccountChannelRequest * tp_account_channel_request_new_dbus_tube ()
TpAccountChannelRequest * tp_account_channel_request_new_stream_tube ()
void tp_account_channel_request_set_conference_initial_channels ()
void tp_account_channel_request_set_file_transfer_hash ()
void tp_account_channel_request_set_initial_invitee_ids ()
void tp_account_channel_request_set_initial_invitees ()
void tp_account_channel_request_create_and_handle_channel_async ()
TpChannel * tp_account_channel_request_create_and_handle_channel_finish ()
void tp_account_channel_request_ensure_and_handle_channel_async ()
TpChannel * tp_account_channel_request_ensure_and_handle_channel_finish ()
void tp_account_channel_request_create_channel_async ()
TpChannel * tp_account_channel_request_create_channel_finish ()
void tp_account_channel_request_ensure_channel_async ()
TpChannel * tp_account_channel_request_ensure_channel_finish ()
TpChannelRequest * tp_account_channel_request_get_channel_request ()
void tp_account_channel_request_set_hint ()
void tp_account_channel_request_set_hints ()
void tp_account_channel_request_set_delegate_to_preferred_handler ()
void (*TpAccountChannelRequestDelegatedChannelCb) ()
void tp_account_channel_request_set_delegated_channel_callback ()

Properties

TpAccount * account Read / Write / Construct Only
TpChannelRequest * channel-request Read
GVariant * request Read / Write / Construct Only
gint64 user-action-time Read / Write / Construct Only

Signals

void re-handled Has Details

Types and Values

Object Hierarchy

    GObject
    ╰── TpAccountChannelRequest

Includes

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

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.

Functions

tp_account_channel_request_new ()

TpAccountChannelRequest *
tp_account_channel_request_new (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.

Parameters

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_dup_request ()

GVariant *
tp_account_channel_request_dup_request
                               (TpAccountChannelRequest *self);

Return the “request” construct-only property.

Parameters

Returns

the value of “request”.

[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

Parameters

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

Parameters

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.

Parameters

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,
                                TpEntityType entity_type,
                                const gchar *identifier);

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

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

Parameters

self

a TpAccountChannelRequest

 

entity_type

the type of identifier , typically TP_ENTITY_TYPE_CONTACT or TP_ENTITY_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:

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.

Parameters

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

Parameters

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_set_sms_channel ()

void
tp_account_channel_request_set_sms_channel
                               (TpAccountChannelRequest *self,
                                gboolean is_sms_channel);

If is_sms_channel is set to TRUE, messages sent and received on the requested channel will be transmitted via SMS.

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

Parameters

self

a TpAccountChannelRequest

 

is_sms_channel

TRUE if the channel should use SMS

 

Since 0.23.2


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 entity type argument. To check whether this is possible, use tp_capabilities_supports_audio_call() with entity_type set to TP_ENTITY_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 entity_type set to TP_ENTITY_TYPE_NONE.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

self

a TpAccountChannelRequest

 

uri

the source URI for the file

 

Since 0.19.0


tp_account_channel_request_new_dbus_tube ()

TpAccountChannelRequest *
tp_account_channel_request_new_dbus_tube
                               (TpAccount *account,
                                const gchar *service_name,
                                gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object, which will yield a DBusTube 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()

Parameters

account

a TpAccount

 

service_name

the service name that will be used over the tube. It should be

 

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


tp_account_channel_request_new_stream_tube ()

TpAccountChannelRequest *
tp_account_channel_request_new_stream_tube
                               (TpAccount *account,
                                const gchar *service,
                                gint64 user_action_time);

Convenience function to create a new TpAccountChannelRequest object, which will yield a StreamTube 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()

Parameters

account

a TpAccount

 

service

the service name that will be used over the tube. It should be a well-known TCP service name as defined by http://www.iana.org/assignments/port-numbers or http://www.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".

 

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


tp_account_channel_request_set_conference_initial_channels ()

void
tp_account_channel_request_set_conference_initial_channels
                               (TpAccountChannelRequest *self,
                                const gchar * const *channels);

Indicate that the channel which is going to be requested using self is an upgrade of the channels whose object paths is listed in channels .

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

Parameters

self

a TpAccountChannelRequest

 

channels

a NULL-terminated array of channel paths

 

Since 0.23.2


tp_account_channel_request_set_file_transfer_hash ()

void
tp_account_channel_request_set_file_transfer_hash
                               (TpAccountChannelRequest *self,
                                TpFileHashType hash_type,
                                const gchar *hash);

Configure this channel request to accompany the file transfer with the hash of the file.

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

Parameters

self

a TpAccountChannelRequest

 

hash_type

a type of hash

 

hash

hash of the contents of the file transfer

 

Since 0.23.2


tp_account_channel_request_set_initial_invitee_ids ()

void
tp_account_channel_request_set_initial_invitee_ids
                               (TpAccountChannelRequest *self,
                                const gchar * const *ids);

Indicate that the contacts listed in ids have to be invited to the conference represented by the channel which is going to be requested using self .

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

Parameters

self

a TpAccountChannelRequest

 

ids

a NULL-terminated array of contact ids

 

Since 0.23.2


tp_account_channel_request_set_initial_invitees ()

void
tp_account_channel_request_set_initial_invitees
                               (TpAccountChannelRequest *self,
                                GPtrArray *contacts);

Indicate that the contacts listed in contacts have to be invited to the conference represented by the channel which is going to be requested using self .

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

Parameters

self

a TpAccountChannelRequest

 

contacts

a GPtrArray of TpContact.

[element-type TelepathyGLib.Contact]

Since 0.23.2


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.

Parameters

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,
                                TpHandleChannelContext **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.

Parameters

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

Parameters

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,
                                TpHandleChannelContext **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_channel_context_dup_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_channel_context_accept(), tp_handle_channel_context_delay() or tp_handle_channel_context_fail().

Parameters

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

Parameters

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_channel_finish ()

TpChannel *
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().

Parameters

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

Parameters

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_channel_finish ()

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

Finishes an async channel creation started using tp_account_channel_request_create_channel_async().

Parameters

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_get_channel_request ()

TpChannelRequest *
tp_account_channel_request_get_channel_request
                               (TpAccountChannelRequest *self);

Return the “channel-request” property

Parameters

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.

Parameters

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,
                                      GVariant *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.

hints is consumed if it is floating.

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

Parameters

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.

Parameters

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 .

Parameters

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 im.telepathy.v1.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()

Parameters

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

Types and Values

TpAccountChannelRequest

typedef struct _TpAccountChannelRequest TpAccountChannelRequest;

Data structure representing a TpAccountChannelRequest object.

Since 0.11.12

Property Details

The “account” property

  “account”                  TpAccount *

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

This property can't be NULL.

Flags: Read / Write / Construct Only

Since 0.11.12


The “channel-request” property

  “channel-request”          TpChannelRequest *

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

Flags: Read


The “request” property

  “request”                  GVariant *

The desired D-Bus properties for the channel.

When constructing a new object, “request” must be set to a non-NULL value.

Flags: Read / Write / Construct Only

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.10


The “user-action-time” property

  “user-action-time”         gint64

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.

Flags: Read / Write / Construct Only

Default value: 0

Since 0.11.12

Signal Details

The “re-handled” signal

void
user_function (TpAccountChannelRequest *self,
               TpChannel               *channel,
               gint64                   user_action_time,
               TpHandleChannelContext  *context,
               gpointer                 user_data)

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_channel_context_dup_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_channel_context_accept(), tp_handle_channel_context_delay() or tp_handle_channel_context_fail().

Parameters

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 TpHandleChannelContext representing the context of the HandleChannels() call.

 

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

Since 0.11.12