telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
#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
);
"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
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()
.
struct TpFileTransferChannel;
Data structure representing a TpFileTransferChannel.
Since 0.15.5
struct TpFileTransferChannelClass { };
The class of a TpFileTransferChannel.
Since 0.15.5
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
|
a TpConnection; may not be NULL
|
|
the object path of the channel; may not be NULL
|
|
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] |
|
used to indicate the error if NULL is returned |
Returns : |
a newly created TpFileTransferChannel. [transfer full] |
Since 0.15.5
#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
const char * tp_file_transfer_channel_get_mime_type
(TpFileTransferChannel *self
);
Return the "mime-type" property
|
a TpFileTransferChannel |
Returns : |
the value of the "mime-type" property. [transfer none] |
Since 0.15.5
GDateTime * tp_file_transfer_channel_get_date (TpFileTransferChannel *self
);
Return the "date" property
|
a TpFileTransferChannel |
Returns : |
the value of the "date" property. [transfer none] |
Since 0.15.5
const gchar * tp_file_transfer_channel_get_description
(TpFileTransferChannel *self
);
Return the "description" property
|
a TpFileTransferChannel |
Returns : |
the value of the "description" property. [transfer none] |
Since 0.15.5
const gchar * tp_file_transfer_channel_get_filename
(TpFileTransferChannel *self
);
Return the "filename" property
|
a TpFileTransferChannel |
Returns : |
the value of the "filename" property. [transfer none] |
Since 0.15.5
guint64 tp_file_transfer_channel_get_size (TpFileTransferChannel *self
);
Return the "size" property
|
a TpFileTransferChannel |
Returns : |
the value of the "size" property |
Since 0.15.5
guint64 tp_file_transfer_channel_get_transferred_bytes
(TpFileTransferChannel *self
);
Return the "transferred-bytes" property
|
a TpFileTransferChannel |
Returns : |
the value of the "transferred-bytes" property |
Since 0.15.5
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.
|
a TpFileTransferChannel |
|
a TpFileTransferStateChangeReason, or NULL . [out]
|
Returns : |
the value of the "state" property |
Since 0.17.1
const gchar * tp_file_transfer_channel_get_service_name
(TpFileTransferChannel *self
);
Return the "service-name" property
|
a TpFileTransferChannel |
Returns : |
the value of the "service-name" property |
Since 0.17.1
const GHashTable * tp_file_transfer_channel_get_metadata
(TpFileTransferChannel *self
);
Return the "metadata" property
|
a TpFileTransferChannel |
Returns : |
the value of the "metadata" property. [transfer none][element-type utf8 GStrv] |
Since 0.17.1
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.
|
a TpFileTransferChannel |
|
a GFile where the file should be saved |
|
Offset from the start of file where transfer begins |
|
a callback to call when the transfer has been accepted |
|
data to pass to callback
|
Since 0.17.1
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()
.
|
a TpFileTransferChannel |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
TRUE if the accept operation was a success, or FALSE
|
Since 0.17.1
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.
|
a TpFileTransferChannel |
|
a GFile to send to the remote contact |
|
a callback to call when the transfer has been accepted |
|
data to pass to callback
|
Since 0.17.1
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.
|
a TpFileTransferChannel |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
TRUE if the file has been successfully provided, or
FALSE . |
Since 0.17.1
"date"
property "date" GDateTime* : Read
A GDateTime representing the last modification time of the file to be transferred.
Since 0.15.5
"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
"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
"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
"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
"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
"mime-type"
property "mime-type" gchar* : Read
The MIME type of the file to be transferred.
Default value: NULL
Since 0.15.5
"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
"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
"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
"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