TpFileTransferChannel

TpFileTransferChannel — proxy object for a file transfer channel

Synopsis

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

struct              TpFileTransferChannel;
struct              TpFileTransferChannelClass;
TpFileTransferChannel * tp_file_transfer_channel_new    (TpConnection *conn,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);
#define             TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE

const char *        tp_file_transfer_channel_get_mime_type
                                                        (TpFileTransferChannel *self);
GDateTime *         tp_file_transfer_channel_get_date   (TpFileTransferChannel *self);
const gchar *       tp_file_transfer_channel_get_description
                                                        (TpFileTransferChannel *self);
const gchar *       tp_file_transfer_channel_get_filename
                                                        (TpFileTransferChannel *self);
guint64             tp_file_transfer_channel_get_size   (TpFileTransferChannel *self);
guint64             tp_file_transfer_channel_get_transferred_bytes
                                                        (TpFileTransferChannel *self);
TpFileTransferState tp_file_transfer_channel_get_state  (TpFileTransferChannel *self,
                                                         TpFileTransferStateChangeReason *reason);
const gchar *       tp_file_transfer_channel_get_service_name
                                                        (TpFileTransferChannel *self);
const GHashTable *  tp_file_transfer_channel_get_metadata
                                                        (TpFileTransferChannel *self);
void                tp_file_transfer_channel_accept_file_async
                                                        (TpFileTransferChannel *self,
                                                         GFile *file,
                                                         guint64 offset,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_file_transfer_channel_accept_file_finish
                                                        (TpFileTransferChannel *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_file_transfer_channel_provide_file_async
                                                        (TpFileTransferChannel *self,
                                                         GFile *file,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_file_transfer_channel_provide_file_finish
                                                        (TpFileTransferChannel *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpChannel
               +----TpFileTransferChannel

Implemented Interfaces

TpFileTransferChannel implements TpChannelIface.

Properties

  "date"                     GDateTime*            : Read
  "description"              gchar*                : Read
  "file"                     GFile*                : Read
  "filename"                 gchar*                : Read
  "initial-offset"           guint64               : Read
  "metadata"                 GHashTable_gchararray+GStrv_*  : Read
  "mime-type"                gchar*                : Read
  "service-name"             gchar*                : Read
  "size"                     guint64               : Read
  "state"                    guint                 : Read
  "transferred-bytes"        guint64               : Read

Description

TpFileTransferChannel is a sub-class of TpChannel providing convenient API to send and receive files.

The channel properties are available in "date", "description", "filename", "initial-offset", "mime-type", "size", "state", and "transferred-bytes" GObject properties, with accessor functions too.

To send a file to a contact, one should create a File Transfer channel with the appropriate D-Bus properties set by specifying their values in the channel creation method call. The file transfer invitation will be sent to the remote contact when the channel is created. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
GHashTable *request = tp_asv_new (
    TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
    TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_CONTACT,
    TP_PROP_CHANNEL_TARGET_ID, G_TYPE_STRING, "foo@bar.com",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_TYPE, G_TYPE_STRING, "text/plain",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DATE, G_TYPE_INT64, 1320925992,
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DESCRIPTION, G_TYPE_STRING, "",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_FILENAME, G_TYPE_STRING, "test.pdf",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_INITIAL_OFFSET, G_TYPE_UINT64, 0,
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_SIZE, G_TYPE_UINT64, 165710,
    NULL);

TpAccountChannelRequest *channel_request = tp_account_channel_request_new (
    account, request,
    TP_USER_ACTION_TIME_CURRENT_TIME);

tp_account_channel_request_create_and_handle_channel_async (channel_request, NULL,
    create_and_handle_cb, NULL);

g_hash_table_unref (request);

Once a TpFileTransferChannel is created as a proxy to the channel on D-Bus. The "notify::state" GObject signals on the resulting channel should be monitored; when the channel moves to state TP_FILE_TRANSFER_STATE_ACCEPTED, tp_file_transfer_channel_provide_file_async() should be called.

When an incoming File Transfer channel appears, one should call tp_file_transfer_channel_accept_file_async().

To cancel or reject a pending or ongoing file transfer, one should close the channel using tp_channel_close_async().

Details

struct TpFileTransferChannel

struct TpFileTransferChannel;

Data structure representing a TpFileTransferChannel.

Since 0.15.5


struct TpFileTransferChannelClass

struct TpFileTransferChannelClass {
};

The class of a TpFileTransferChannel.

Since 0.15.5


tp_file_transfer_channel_new ()

TpFileTransferChannel * tp_file_transfer_channel_new    (TpConnection *conn,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);

Warning

tp_file_transfer_channel_new is deprecated and should not be used in newly-written code. Use tp_simple_client_factory_ensure_channel() instead.

Convenient function to create a new TpFileTransferChannel

conn :

a TpConnection; may not be NULL

object_path :

the object path of the channel; may not be NULL

immutable_properties :

the immutable properties of the channel, as signalled by the NewChannel D-Bus signal or returned by the CreateChannel and EnsureChannel D-Bus methods: a mapping from strings (D-Bus interface name + "." + property name) to GValue instances. [transfer none][element-type utf8 GObject.Value]

error :

used to indicate the error if NULL is returned

Returns :

a newly created TpFileTransferChannel. [transfer full]

Since 0.15.5


TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE

#define             TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE

Expands to a call to a function that returns a quark for the "core" feature on a TpFileTransferChannel.

When this feature is prepared, the "transferred-bytes" property has been retrieved and will be updated.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to trigger the callback.

Since 0.15.5


tp_file_transfer_channel_get_mime_type ()

const char *        tp_file_transfer_channel_get_mime_type
                                                        (TpFileTransferChannel *self);

Return the "mime-type" property

self :

a TpFileTransferChannel

Returns :

the value of the "mime-type" property. [transfer none]

Since 0.15.5


tp_file_transfer_channel_get_date ()

GDateTime *         tp_file_transfer_channel_get_date   (TpFileTransferChannel *self);

Return the "date" property

self :

a TpFileTransferChannel

Returns :

the value of the "date" property. [transfer none]

Since 0.15.5


tp_file_transfer_channel_get_description ()

const gchar *       tp_file_transfer_channel_get_description
                                                        (TpFileTransferChannel *self);

Return the "description" property

self :

a TpFileTransferChannel

Returns :

the value of the "description" property. [transfer none]

Since 0.15.5


tp_file_transfer_channel_get_filename ()

const gchar *       tp_file_transfer_channel_get_filename
                                                        (TpFileTransferChannel *self);

Return the "filename" property

self :

a TpFileTransferChannel

Returns :

the value of the "filename" property. [transfer none]

Since 0.15.5


tp_file_transfer_channel_get_size ()

guint64             tp_file_transfer_channel_get_size   (TpFileTransferChannel *self);

Return the "size" property

self :

a TpFileTransferChannel

Returns :

the value of the "size" property

Since 0.15.5


tp_file_transfer_channel_get_transferred_bytes ()

guint64             tp_file_transfer_channel_get_transferred_bytes
                                                        (TpFileTransferChannel *self);

Return the "transferred-bytes" property

self :

a TpFileTransferChannel

Returns :

the value of the "transferred-bytes" property

Since 0.15.5


tp_file_transfer_channel_get_state ()

TpFileTransferState tp_file_transfer_channel_get_state  (TpFileTransferChannel *self,
                                                         TpFileTransferStateChangeReason *reason);

Returns the "state" property.

If reason is not NULL it is set to the reason why "state" changed to its current value.

self :

a TpFileTransferChannel

reason :

a TpFileTransferStateChangeReason, or NULL. [out]

Returns :

the value of the "state" property

Since 0.17.1


tp_file_transfer_channel_get_service_name ()

const gchar *       tp_file_transfer_channel_get_service_name
                                                        (TpFileTransferChannel *self);

Return the "service-name" property

self :

a TpFileTransferChannel

Returns :

the value of the "service-name" property

Since 0.17.1


tp_file_transfer_channel_get_metadata ()

const GHashTable *  tp_file_transfer_channel_get_metadata
                                                        (TpFileTransferChannel *self);

Return the "metadata" property

self :

a TpFileTransferChannel

Returns :

the value of the "metadata" property. [transfer none][element-type utf8 GStrv]

Since 0.17.1


tp_file_transfer_channel_accept_file_async ()

void                tp_file_transfer_channel_accept_file_async
                                                        (TpFileTransferChannel *self,
                                                         GFile *file,
                                                         guint64 offset,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Accept an incoming file transfer in the TP_FILE_TRANSFER_STATE_PENDING state. Once the accept has been processed, callback will be called. You can then call tp_file_transfer_channel_accept_file_finish() to get the result of the operation.

self :

a TpFileTransferChannel

file :

a GFile where the file should be saved

offset :

Offset from the start of file where transfer begins

callback :

a callback to call when the transfer has been accepted

user_data :

data to pass to callback

Since 0.17.1


tp_file_transfer_channel_accept_file_finish ()

gboolean            tp_file_transfer_channel_accept_file_finish
                                                        (TpFileTransferChannel *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes a call to tp_file_transfer_channel_accept_file_async().

self :

a TpFileTransferChannel

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the accept operation was a success, or FALSE

Since 0.17.1


tp_file_transfer_channel_provide_file_async ()

void                tp_file_transfer_channel_provide_file_async
                                                        (TpFileTransferChannel *self,
                                                         GFile *file,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Provide a file transfer. This should be called when the file transfer state changes (tp_file_transfer_channel_get_state() and the "notify::state" signal) to TP_FILE_TRANSFER_STATE_ACCEPTED or TP_FILE_TRANSFER_STATE_PENDING. Once the file has been provided, the channel "state" will change to TP_FILE_TRANSFER_STATE_OPEN.

Once the file has been provided, callback will be called. You should then call tp_file_transfer_channel_provide_file_finish() to get the result of the operation.

self :

a TpFileTransferChannel

file :

a GFile to send to the remote contact

callback :

a callback to call when the transfer has been accepted

user_data :

data to pass to callback

Since 0.17.1


tp_file_transfer_channel_provide_file_finish ()

gboolean            tp_file_transfer_channel_provide_file_finish
                                                        (TpFileTransferChannel *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes a call to tp_file_transfer_channel_provide_file_async().

Successful return from this function does not mean that the file transfer has completed or has even started at all. The state of the file transfer should be monitored with the "notify::state" signal.

self :

a TpFileTransferChannel

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the file has been successfully provided, or FALSE.

Since 0.17.1

Property Details

The "date" property

  "date"                     GDateTime*            : Read

A GDateTime representing the last modification time of the file to be transferred.

Since 0.15.5


The "description" property

  "description"              gchar*                : Read

The description of the file transfer, defined by the sender when sending the file transfer offer.

Since 0.15.5

Default value: NULL


The "file" property

  "file"                     GFile*                : Read

For incoming file transfers, this property will be set to a GFile for the location where the file will be saved (given by tp_file_transfer_channel_accept_file_async()) when the transfer starts. The feature TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE must already be prepared for this property to have a meaningful value, and to receive change notification. Once the initial value is set, this property will not be changed.

For outgoing file transfers, this property is a GFile for the location of the file being sent (given by tp_file_transfer_channel_provide_file_async()). The feature TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE does not have to be prepared and there is no change notification.

Since 0.17.1


The "filename" property

  "filename"                 gchar*                : Read

The name of the file on the sender's side. This is therefore given as a suggested filename for the receiver.

Since 0.15.5

Default value: NULL


The "initial-offset" property

  "initial-offset"           guint64               : Read

The offset in bytes from where the file should be sent.

The TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE feature has to be prepared for this property to be meaningful and kept up to date.

Default value: 0

Since 0.17.1


The "metadata" property

  "metadata"                 GHashTable_gchararray+GStrv_*  : Read

Additional information about the file transfer set by the channel initiator, or an empty GHashTable if the initiator did not provide any additional information.

To provide metadata along with a file offer, include TP_PROP_CHANNEL_INTERFACE_FILE_TRANSFER_METADATA_METADATA in the channel request. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
GHashTable *request;
GHashTable *metadata = g_hash_table_new (g_str_hash, g_str_equal);
const gchar * const values[] = { "Jason Derulo", "Tinie Tempah", NULL };

g_hash_table_insert (metadata, "best buds", values);

request = tp_asv_new (
    TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
    TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_CONTACT,
    TP_PROP_CHANNEL_TARGET_ID, G_TYPE_STRING, "foo@bar.com",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_TYPE, G_TYPE_STRING, "text/plain",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DATE, G_TYPE_INT64, 1320925992,
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DESCRIPTION, G_TYPE_STRING, "",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_FILENAME, G_TYPE_STRING, "test.pdf",
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_INITIAL_OFFSET, G_TYPE_UINT64, 0,
    TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_SIZE, G_TYPE_UINT64, 165710,
    TP_PROP_CHANNEL_INTERFACE_FILE_TRANSFER_METADATA_METADATA, TP_TYPE_METADATA, metadata,
    NULL);

...

The TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE feature has to be prepared for this property to be meaningful.

Since 0.17.1


The "mime-type" property

  "mime-type"                gchar*                : Read

The MIME type of the file to be transferred.

Default value: NULL

Since 0.15.5


The "service-name" property

  "service-name"             gchar*                : Read

A string representing the name of the service suggested to handle this file transfer channel, or NULL if the initiator did not provide one.

This is a useful way of requesting file transfer channels with a hint of what handler they should be handled by on the remote side. If a channel request is made with this property set (to a contact who also supports the metadata extension; see the requestable channel classes for said contact), this property will be set to the same value on the remote incoming channel and handlers can match on this in their handler filter. For example, a remote handler could call the following:

1
2
3
4
5
6
tp_base_client_take_handler_filter (handler, tp_asv_new (
              TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
              TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_CONTACT,
              TP_PROP_CHANNEL_REQUESTED, G_TYPE_BOOLEAN, FALSE,
              TP_PROP_CHANNEL_INTERFACE_FILE_TRANSFER_METADATA_SERVICE_NAME, G_TYPE_STRING, "service.name",
              NULL));

The TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE feature has to be prepared for this property to be meaningful.

Default value: ""

Since 0.17.1


The "size" property

  "size"                     guint64               : Read

The size of the file to be transferred, or G_MAXUINT64 if not known.

Since 0.15.5

Default value: 0


The "state" property

  "state"                    guint                 : Read

A TpFileTransferState holding the state of the file transfer.

The TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE feature has to be prepared for this property to be meaningful and kept up to date.

Since 0.17.1

Allowed values: <= 6

Default value: 0


The "transferred-bytes" property

  "transferred-bytes"        guint64               : Read

The number of bytes transferred so far in this file transfer.

The TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE feature has to be prepared for this property to be meaningful and kept up to date.

Default value: 0

Since 0.15.5