EmpathyFTHandler

EmpathyFTHandler — an object representing a File Transfer

Synopsis


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

Object Hierarchy

  GObject
   +----EmpathyFTHandler

Properties

  "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

Signals

  "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

Description

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.

Details

EmpathyFTHandler

typedef struct _EmpathyFTHandler EmpathyFTHandler;


EmpathyFTHandlerReadyCallback ()

void                (*EmpathyFTHandlerReadyCallback)    (EmpathyFTHandler *handler,
                                                         GError *error,
                                                         gpointer user_data);

handler :

the handler which is now ready

error :

a GError if the operation failed, or NULL

user_data :

user data passed to the callback

empathy_ft_handler_new_outgoing ()

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.

contact :

the EmpathyContact to send source to

source :

the GFile to send

callback :

callback to be called when the handler has been created

user_data :

user data to be passed to callback

empathy_ft_handler_new_incoming ()

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.

tp_file :

the EmpathyTpFile wrapping the incoming channel

callback :

callback to be called when the handler has been created

user_data :

user data to be passed to callback

empathy_ft_handler_incoming_set_destination ()

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.

handler :

an EmpathyFTHandler

destination :

the GFile where the transfer should be saved

empathy_ft_handler_start_transfer ()

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.

handler :

an EmpathyFTHandler

empathy_ft_handler_cancel_transfer ()

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.

handler :

an EmpathyFTHandler

empathy_ft_handler_get_filename ()

const char *        empathy_ft_handler_get_filename     (EmpathyFTHandler *handler);

Returns the name of the file being transferred.

handler :

an EmpathyFTHandler

Returns :

the name of the file being transferred

empathy_ft_handler_get_content_type ()

const char *        empathy_ft_handler_get_content_type (EmpathyFTHandler *handler);

Returns the content type of the file being transferred.

handler :

an EmpathyFTHandler

Returns :

the content type of the file being transferred

empathy_ft_handler_get_contact ()

EmpathyContact *    empathy_ft_handler_get_contact      (EmpathyFTHandler *handler);

Returns the remote EmpathyContact at the other side of the transfer.

handler :

an EmpathyFTHandler

Returns :

the remote EmpathyContact for handler

empathy_ft_handler_get_gfile ()

GFile *             empathy_ft_handler_get_gfile        (EmpathyFTHandler *handler);

Returns the GFile where the transfer is being read/saved.

handler :

an EmpathyFTHandler

Returns :

the GFile where the transfer is being read/saved

empathy_ft_handler_get_use_hash ()

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.

handler :

an EmpathyFTHandler

Returns :

TRUE if the handler has checksumming enabled, FALSE otherwise.

empathy_ft_handler_is_incoming ()

gboolean            empathy_ft_handler_is_incoming      (EmpathyFTHandler *handler);

Returns whether handler is incoming or outgoing.

handler :

an EmpathyFTHandler

Returns :

TRUE if the handler is incoming, FALSE otherwise.

empathy_ft_handler_get_transferred_bytes ()

guint64             empathy_ft_handler_get_transferred_bytes
                                                        (EmpathyFTHandler *handler);

Returns the number of bytes already transferred by the handler.

handler :

an EmpathyFTHandler

Returns :

the number of bytes already transferred by the handler.

empathy_ft_handler_get_total_bytes ()

guint64             empathy_ft_handler_get_total_bytes  (EmpathyFTHandler *handler);

Returns the total size of the file being transferred by the handler.

handler :

an EmpathyFTHandler

Returns :

a number of bytes indicating the total size of the file being transferred by the handler.

empathy_ft_handler_is_completed ()

gboolean            empathy_ft_handler_is_completed     (EmpathyFTHandler *handler);

Returns whether the transfer for handler has been completed succesfully.

handler :

an EmpathyFTHandler

Returns :

TRUE if the handler has been transferred correctly, FALSE otherwise

empathy_ft_handler_is_cancelled ()

gboolean            empathy_ft_handler_is_cancelled     (EmpathyFTHandler *handler);

Returns whether the transfer for handler has been cancelled or has stopped due to an error.

handler :

an EmpathyFTHandler

Returns :

TRUE if the transfer for handler has been cancelled or has stopped due to an error, FALSE otherwise.

Property Details

The "contact" property

  "contact"                  EmpathyContact*       : Read / Write / Construct Only

The remote EmpathyContact for the transfer


The "content-type" property

  "content-type"             gchar*                : Read

The content type of the file being transferred

Default value: NULL


The "description" property

  "description"              gchar*                : Read

The description of the file being transferred

Default value: NULL


The "filename" property

  "filename"                 gchar*                : Read

The name of the file being transferred

Default value: NULL


The "gfile" property

  "gfile"                    GFile*                : Read / Write

The GFile object where the transfer actually happens


The "modification-time" property

  "modification-time"        guint64               : Read

The modification time of the file being transferred

Default value: 0


The "total-bytes" property

  "total-bytes"              guint64               : Read

The size (in bytes) of the file being transferred

Default value: 0


The "tp-file" property

  "tp-file"                  EmpathyTpFile*        : Read / Write / Construct Only

The underlying EmpathyTpFile managing the transfer


The "transferred-bytes" property

  "transferred-bytes"        guint64               : Read

The number of the bytes already transferred

Default value: 0

Signal Details

The "hashing-done" signal

void                user_function                      (EmpathyFTHandler *handler,
                                                        gpointer          user_data)      : Run Last

This signal is emitted when the hashing operation of the handler is completed.

handler :

the object which has received the signal

user_data :

user data set when the signal handler was connected.

The "hashing-progress" signal

void                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.

handler :

the object which has received the signal

current_bytes :

the bytes currently hashed

total_bytes :

the total bytes of the handler

user_data :

user data set when the signal handler was connected.

The "hashing-started" signal

void                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.

handler :

the object which has received the signal

user_data :

user data set when the signal handler was connected.

The "transfer-done" signal

void                user_function                      (EmpathyFTHandler *handler,
                                                        EmpathyTpFile    *tp_file,
                                                        gpointer          user_data)      : Run Last

This signal will be emitted when the actual transfer is completed successfully.

handler :

the object which has received the signal

tp_file :

the EmpathyTpFile for which the transfer has started

user_data :

user data set when the signal handler was connected.

The "transfer-error" signal

void                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.

handler :

the object which has received the signal

error :

a GError

user_data :

user data set when the signal handler was connected.

The "transfer-progress" signal

void                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.

handler :

the object which has received the signal

current_bytes :

the bytes currently transferred

total_bytes :

the total bytes of the handler

remaining_time :

the number of seconds remaining for the transfer to be completed

speed :

the current speed of the transfer (in KB/s)

user_data :

user data set when the signal handler was connected.

The "transfer-started" signal

void                user_function                      (EmpathyFTHandler *handler,
                                                        EmpathyTpFile    *tp_file,
                                                        gpointer          user_data)      : Run Last

This signal is emitted when the actual transfer starts.

handler :

the object which has received the signal

tp_file :

the EmpathyTpFile for which the transfer has started

user_data :

user data set when the signal handler was connected.