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