TpFileTransferChannel: telepathy-glib API Reference Manual

## TpFileTransferChannel TpFileTransferChannel — proxy object for a file transfer channel |

## Functions

TpFileTransferChannel * | tp_file_transfer_channel_new ()
const char * | tp_file_transfer_channel_get_mime_type ()
GDateTime * | tp_file_transfer_channel_get_date ()
const gchar * | tp_file_transfer_channel_get_description ()
const gchar * | tp_file_transfer_channel_get_filename ()
guint64 | tp_file_transfer_channel_get_size ()
guint64 | tp_file_transfer_channel_get_transferred_bytes ()
TpFileTransferState | tp_file_transfer_channel_get_state ()
const gchar * | tp_file_transfer_channel_get_service_name ()
const GHashTable * | tp_file_transfer_channel_get_metadata ()
void | tp_file_transfer_channel_accept_file_async ()
gboolean | tp_file_transfer_channel_accept_file_finish ()
void | tp_file_transfer_channel_provide_file_async ()
gboolean | tp_file_transfer_channel_provide_file_finish ()

## Properties

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

## Types and Values

struct | TpFileTransferChannel
struct | TpFileTransferChannelClass
#define | TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE

## Object Hierarchy

        GObject
        ╰── TpProxy
            ╰── TpChannel
                ╰── TpFileTransferChannel

## Implemented Interfaces

TpFileTransferChannel implements TpChannelIface.

## Includes

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

## 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()`.

## Functions

### tp_file_transfer_channel_new ()

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

`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

#### Parameters

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

    const char *
    tp_file_transfer_channel_get_mime_type
                                   (TpFileTransferChannel *self);

Return the “mime-type” property

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

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

## Property Details

### The `“date”` property

      “date”                     GDateTime *

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

Since 0.15.5

Owner: TpFileTransferChannel

Flags: Read

### The `“description”` property

      “description”              char *

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

Since 0.15.5

Owner: TpFileTransferChannel

Flags: Read

Default value: NULL

### The `“file”` property

      “file”                     GFile *

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.

Owner: TpFileTransferChannel

Flags: Read

Since: 0.17.1

### The `“filename”` property

      “filename”                 char *

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

Owner: TpFileTransferChannel

Flags: Read

Default value: NULL

### The `“initial-offset”` property

      “initial-offset”           guint64

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.

Owner: TpFileTransferChannel

Flags: Read

Default value: 0

Since: 0.17.1

### The `“metadata”` property

      “metadata”                 GHashTable_gchararray+GStrv_*

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.

Owner: TpFileTransferChannel

Flags: Read

Since: 0.17.1

### The `“mime-type”` property

      “mime-type”                char *

The MIME type of the file to be transferred.

Owner: TpFileTransferChannel

Flags: Read

Default value: NULL

Since: 0.15.5

### The `“service-name”` property

      “service-name”             char *

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.

Owner: TpFileTransferChannel

Flags: Read

Default value: ""

Since: 0.17.1

### The `“size”` property

      “size”                     guint64

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

Since 0.15.5

Owner: TpFileTransferChannel

Flags: Read

Default value: 0

### The `“state”` property

      “state”                    guint

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

Owner: TpFileTransferChannel

Flags: Read

Allowed values: <= 6

Default value: 0

### The `“transferred-bytes”` property

      “transferred-bytes”        guint64

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.

Owner: TpFileTransferChannel

Flags: Read

Default value: 0

Since: 0.15.5