![]() |
![]() |
![]() |
libempathy Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#include <libempathy/empathy-ft-handler> EmpathyFTHandler; void (*EmpathyFTHandlerReadyCallback) (EmpathyFTHandler *handler, GError *error, gpointer user_data); void empathy_ft_handler_new_outgoing (EmpathyContact *contact, GFile *source, EmpathyFTHandlerReadyCallback callback, gpointer user_data); void empathy_ft_handler_new_incoming (EmpathyTpFile *tp_file, EmpathyFTHandlerReadyCallback callback, gpointer user_data); void empathy_ft_handler_incoming_set_destination (EmpathyFTHandler *handler, GFile *destination); void empathy_ft_handler_start_transfer (EmpathyFTHandler *handler); void empathy_ft_handler_cancel_transfer (EmpathyFTHandler *handler); const char * empathy_ft_handler_get_filename (EmpathyFTHandler *handler); const char * empathy_ft_handler_get_content_type (EmpathyFTHandler *handler); EmpathyContact * empathy_ft_handler_get_contact (EmpathyFTHandler *handler); GFile * empathy_ft_handler_get_gfile (EmpathyFTHandler *handler); gboolean empathy_ft_handler_get_use_hash (EmpathyFTHandler *handler); gboolean empathy_ft_handler_is_incoming (EmpathyFTHandler *handler); guint64 empathy_ft_handler_get_transferred_bytes (EmpathyFTHandler *handler); guint64 empathy_ft_handler_get_total_bytes (EmpathyFTHandler *handler); gboolean empathy_ft_handler_is_completed (EmpathyFTHandler *handler); gboolean empathy_ft_handler_is_cancelled (EmpathyFTHandler *handler);
"contact" EmpathyContact* : Read / Write / Construct Only "content-type" gchar* : Read "description" gchar* : Read "filename" gchar* : Read "gfile" GFile* : Read / Write "modification-time" guint64 : Read "total-bytes" guint64 : Read "tp-file" EmpathyTpFile* : Read / Write / Construct Only "transferred-bytes" guint64 : Read
"hashing-done" : Run Last "hashing-progress" : Run Last "hashing-started" : Run Last "transfer-done" : Run Last "transfer-error" : Run Last "transfer-progress" : Run Last "transfer-started" : Run Last
EmpathyFTHandler is the object which represents a File Transfer with all
its properties.
The creation of an EmpathyFTHandler is done with
empathy_ft_handler_new_outgoing()
or empathy_ft_handler_new_incoming()
,
even though clients should not need to call them directly, as
EmpathyFTFactory does it for them. Remember that for the file transfer
to work with an incoming handler,
empathy_ft_handler_incoming_set_destination()
should be called after
empathy_ft_handler_new_incoming()
. EmpathyFTFactory does this
automatically.
It's important to note that, as the creation of the handlers is async, once
an handler is created, it already has all the interesting properties set,
like filename, total bytes, content type and so on, making it useful
to be displayed in an UI.
The transfer API works like a state machine; it has three signals,
::transfer-started, ::transfer-progress, ::transfer-done, which will be
emitted in the relevant phases.
In addition, if the handler is created with checksumming enabled,
other three signals (::hashing-started, ::hashing-progress, ::hashing-done)
will be emitted before or after the transfer, depending on the direction
(respectively outgoing and incoming) of the handler.
At any time between the call to empathy_ft_handler_start_transfer()
and
the last signal, a ::transfer-error can be emitted, indicating that an
error has happened in the operation. The message of the error is localized
to use in an UI.
void (*EmpathyFTHandlerReadyCallback) (EmpathyFTHandler *handler, GError *error, gpointer user_data);
void empathy_ft_handler_new_outgoing (EmpathyContact *contact, GFile *source, EmpathyFTHandlerReadyCallback callback, gpointer user_data);
Triggers the creation of a new EmpathyFTHandler for an outgoing transfer.
|
the EmpathyContact to send source to
|
|
the GFile to send |
|
callback to be called when the handler has been created |
|
user data to be passed to callback
|
void empathy_ft_handler_new_incoming (EmpathyTpFile *tp_file, EmpathyFTHandlerReadyCallback callback, gpointer user_data);
Triggers the creation of a new EmpathyFTHandler for an incoming transfer.
Note that for the handler to be useful, you will have to set a destination
file with empathy_ft_handler_incoming_set_destination()
after the handler
is ready.
|
the EmpathyTpFile wrapping the incoming channel |
|
callback to be called when the handler has been created |
|
user data to be passed to callback
|
void empathy_ft_handler_incoming_set_destination (EmpathyFTHandler *handler, GFile *destination);
Sets the destination of the incoming handler to be destination
.
Note that calling this method is mandatory before starting the transfer
for incoming handlers.
|
an EmpathyFTHandler |
|
the GFile where the transfer should be saved |
void empathy_ft_handler_start_transfer (EmpathyFTHandler *handler);
Starts the transfer machinery. After this call, the transfer and hashing signals will be emitted by the handler.
|
an EmpathyFTHandler |
void empathy_ft_handler_cancel_transfer (EmpathyFTHandler *handler);
Cancels an ongoing handler operation. Note that this doesn't destroy the object, which will keep all the properties, altough it won't be able to do any more I/O.
|
an EmpathyFTHandler |
const char * empathy_ft_handler_get_filename (EmpathyFTHandler *handler);
Returns the name of the file being transferred.
|
an EmpathyFTHandler |
Returns : |
the name of the file being transferred |
const char * empathy_ft_handler_get_content_type (EmpathyFTHandler *handler);
Returns the content type of the file being transferred.
|
an EmpathyFTHandler |
Returns : |
the content type of the file being transferred |
EmpathyContact * empathy_ft_handler_get_contact (EmpathyFTHandler *handler);
Returns the remote EmpathyContact at the other side of the transfer.
|
an EmpathyFTHandler |
Returns : |
the remote EmpathyContact for handler
|
GFile * empathy_ft_handler_get_gfile (EmpathyFTHandler *handler);
Returns the GFile where the transfer is being read/saved.
|
an EmpathyFTHandler |
Returns : |
the GFile where the transfer is being read/saved |
gboolean empathy_ft_handler_get_use_hash (EmpathyFTHandler *handler);
Returns whether handler
has checksumming enabled. This can depend on
the CM and the remote contact capabilities.
|
an EmpathyFTHandler |
Returns : |
TRUE if the handler has checksumming enabled,
FALSE otherwise.
|
gboolean empathy_ft_handler_is_incoming (EmpathyFTHandler *handler);
Returns whether handler
is incoming or outgoing.
|
an EmpathyFTHandler |
Returns : |
TRUE if the handler is incoming, FALSE otherwise.
|
guint64 empathy_ft_handler_get_transferred_bytes (EmpathyFTHandler *handler);
Returns the number of bytes already transferred by the handler.
|
an EmpathyFTHandler |
Returns : |
the number of bytes already transferred by the handler. |
guint64 empathy_ft_handler_get_total_bytes (EmpathyFTHandler *handler);
Returns the total size of the file being transferred by the handler.
|
an EmpathyFTHandler |
Returns : |
a number of bytes indicating the total size of the file being transferred by the handler. |
gboolean empathy_ft_handler_is_completed (EmpathyFTHandler *handler);
Returns whether the transfer for handler
has been completed succesfully.
|
an EmpathyFTHandler |
Returns : |
TRUE if the handler has been transferred correctly, FALSE
otherwise
|
gboolean empathy_ft_handler_is_cancelled (EmpathyFTHandler *handler);
Returns whether the transfer for handler
has been cancelled or has stopped
due to an error.
|
an EmpathyFTHandler |
Returns : |
TRUE if the transfer for handler has been cancelled
or has stopped due to an error, FALSE otherwise.
|
"contact"
property"contact" EmpathyContact* : Read / Write / Construct Only
The remote EmpathyContact for the transfer
"content-type"
property"content-type" gchar* : Read
The content type of the file being transferred
Default value: NULL
"description"
property"description" gchar* : Read
The description of the file being transferred
Default value: NULL
"filename"
property"filename" gchar* : Read
The name of the file being transferred
Default value: NULL
"gfile"
property"gfile" GFile* : Read / Write
The GFile object where the transfer actually happens
"modification-time"
property"modification-time" guint64 : Read
The modification time of the file being transferred
Default value: 0
"total-bytes"
property"total-bytes" guint64 : Read
The size (in bytes) of the file being transferred
Default value: 0
"tp-file"
property"tp-file" EmpathyTpFile* : Read / Write / Construct Only
The underlying EmpathyTpFile managing the transfer
"transferred-bytes"
property"transferred-bytes" guint64 : Read
The number of the bytes already transferred
Default value: 0
"hashing-done"
signalvoid user_function (EmpathyFTHandler *handler, gpointer user_data) : Run Last
This signal is emitted when the hashing operation of the handler is completed.
|
the object which has received the signal |
|
user data set when the signal handler was connected. |
"hashing-progress"
signalvoid user_function (EmpathyFTHandler *handler, guint64 current_bytes, guint64 total_bytes, gpointer user_data) : Run Last
This signal is emitted to notify clients of the progress of the hashing operation.
|
the object which has received the signal |
|
the bytes currently hashed |
|
the total bytes of the handler |
|
user data set when the signal handler was connected. |
"hashing-started"
signalvoid user_function (EmpathyFTHandler *handler, gpointer user_data) : Run Last
This signal is emitted when the hashing operation of the handler
is started. Note that this might happen or not, depending on the CM
and remote contact capabilities. Clients shoud use
empathy_ft_handler_get_use_hash()
before calling
empathy_ft_handler_start_transfer()
to know whether they should connect
to this signal.
|
the object which has received the signal |
|
user data set when the signal handler was connected. |
"transfer-done"
signalvoid user_function (EmpathyFTHandler *handler, EmpathyTpFile *tp_file, gpointer user_data) : Run Last
This signal will be emitted when the actual transfer is completed successfully.
|
the object which has received the signal |
|
the EmpathyTpFile for which the transfer has started |
|
user data set when the signal handler was connected. |
"transfer-error"
signalvoid user_function (EmpathyFTHandler *handler, gpointer error, gpointer user_data) : Run Last
This signal can be emitted anytime between the call to
empathy_ft_handler_start_transfer()
and the last expected signal
(::transfer-done or ::hashing-done), and it's guaranteed to be the last
signal coming from the handler, meaning that no other operation will
take place after this signal.
|
the object which has received the signal |
|
a GError |
|
user data set when the signal handler was connected. |
"transfer-progress"
signalvoid user_function (EmpathyFTHandler *handler, guint64 current_bytes, guint64 total_bytes, guint remaining_time, gdouble speed, gpointer user_data) : Run Last
This signal is emitted to notify clients of the progress of the transfer.
|
the object which has received the signal |
|
the bytes currently transferred |
|
the total bytes of the handler |
|
the number of seconds remaining for the transfer to be completed |
|
the current speed of the transfer (in KB/s) |
|
user data set when the signal handler was connected. |
"transfer-started"
signalvoid user_function (EmpathyFTHandler *handler, EmpathyTpFile *tp_file, gpointer user_data) : Run Last
This signal is emitted when the actual transfer starts.
|
the object which has received the signal |
|
the EmpathyTpFile for which the transfer has started |
|
user data set when the signal handler was connected. |