TpFileTransferChannel

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