## EmpathyTpFile

EmpathyTpFile — Object which represents a Telepathy file channel

## Synopsis

    #include <libempathy/empathy-tp-file.h>

    #define             EMPATHY_FT_ERROR_QUARK
    enum                EmpathyFTErrorEnum;
                        EmpathyTpFile;
    EmpathyTpFile *     empathy_tp_file_new                 (TpChannel *channel,
                                                             gboolean incoming);
    void                empathy_tp_file_accept              (EmpathyTpFile *tp_file,
                                                             guint64 offset,
                                                             GFile *gfile,
                                                             GCancellable *cancellable,
                                                             EmpathyTpFileProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             EmpathyTpFileOperationCallback op_callback,
                                                             gpointer op_user_data);
    void                empathy_tp_file_offer               (EmpathyTpFile *tp_file,
                                                             GFile *gfile,
                                                             GCancellable *cancellable,
                                                             EmpathyTpFileProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             EmpathyTpFileOperationCallback op_callback,
                                                             gpointer op_user_data);
    void                empathy_tp_file_cancel              (EmpathyTpFile *tp_file);
    void                empathy_tp_file_close               (EmpathyTpFile *tp_file);
    gboolean            empathy_tp_file_is_incoming         (EmpathyTpFile *tp_file);

## Object Hierarchy

      GObject
       +----EmpathyTpFile

## Properties

      "channel"                  TpChannel*            : Read / Write / Construct Only
      "incoming"                 gboolean              : Read / Write / Construct Only

## Description

EmpathyTpFile is an object which represents a Telepathy file channel. Usually, clients do not need to deal with EmpathyTpFile objects directly, and are supposed to use EmpathyFTHandler and EmpathyFTFactory for transferring files using libempathy.

## Details

### EMPATHY_FT_ERROR_QUARK

    #define EMPATHY_FT_ERROR_QUARK g_quark_from_static_string ("EmpathyFTError")

### enum EmpathyFTErrorEnum

    typedef enum {
    	EMPATHY_FT_ERROR_FAILED,
    	EMPATHY_FT_ERROR_HASH_MISMATCH,
    	EMPATHY_FT_ERROR_TP_ERROR,
    	EMPATHY_FT_ERROR_SOCKET,
    	EMPATHY_FT_ERROR_NOT_SUPPORTED,
    	EMPATHY_FT_ERROR_INVALID_SOURCE_FILE,
    	EMPATHY_FT_ERROR_EMPTY_SOURCE_FILE
    } EmpathyFTErrorEnum;

### EmpathyTpFile

    typedef struct _EmpathyTpFile EmpathyTpFile;

### empathy_tp_file_new ()

    EmpathyTpFile *     empathy_tp_file_new                 (TpChannel *channel,
                                                             gboolean incoming);

Creates a new EmpathyTpFile wrapping `channel`, with the direction specified by `incoming`. The returned EmpathyTpFile should be unrefed with `g_object_unref()` when finished with.

`channel` : | a TpChannel
`incoming` : | whether the file transfer is incoming or not
Returns : | a new EmpathyTpFile

### empathy_tp_file_accept ()

    void                empathy_tp_file_accept              (EmpathyTpFile *tp_file,
                                                             guint64 offset,
                                                             GFile *gfile,
                                                             GCancellable *cancellable,
                                                             EmpathyTpFileProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             EmpathyTpFileOperationCallback op_callback,
                                                             gpointer op_user_data);

Accepts an incoming file transfer, saving the result into `gfile`. The callback `op_callback` will be called both when the transfer is successful and in case of an error. Note that cancelling `cancellable`, closes the socket of the file operation in progress, but doesn't guarantee that the transfer channel will be closed as well. Thus, `empathy_tp_file_cancel()` or `empathy_tp_file_close()` should be used to actually cancel an ongoing EmpathyTpFile.

`tp_file` : | an incoming EmpathyTpFile
`offset` : | the offset of `gfile` where we should start writing
`gfile` : | the destination GFile for the transfer
`cancellable` : | a GCancellable
`progress_callback` : | function to callback with progress information
`progress_user_data` : | user_data to pass to `progress_callback`
`op_callback` : | function to callback when the transfer ends
`op_user_data` : | user_data to pass to `op_callback`

### empathy_tp_file_offer ()

    void                empathy_tp_file_offer               (EmpathyTpFile *tp_file,
                                                             GFile *gfile,
                                                             GCancellable *cancellable,
                                                             EmpathyTpFileProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             EmpathyTpFileOperationCallback op_callback,
                                                             gpointer op_user_data);

Offers an outgoing file transfer, reading data from `gfile`. The callback `op_callback` will be called both when the transfer is successful and in case of an error. Note that cancelling `cancellable`, closes the socket of the file operation in progress, but doesn't guarantee that the transfer channel will be closed as well. Thus, `empathy_tp_file_cancel()` or `empathy_tp_file_close()` should be used to actually cancel an ongoing EmpathyTpFile.

`tp_file` : | an outgoing EmpathyTpFile
`gfile` : | the source GFile for the transfer
`cancellable` : | a GCancellable
`progress_callback` : | function to callback with progress information
`progress_user_data` : | user_data to pass to `progress_callback`
`op_callback` : | function to callback when the transfer ends
`op_user_data` : | user_data to pass to `op_callback`

### empathy_tp_file_cancel ()

    void                empathy_tp_file_cancel              (EmpathyTpFile *tp_file);

Cancels an ongoing EmpathyTpFile, first closing the channel and then cancelling any I/O operation and closing the socket.

`tp_file` : | an EmpathyTpFile

### empathy_tp_file_close ()

    void                empathy_tp_file_close               (EmpathyTpFile *tp_file);

Closes the channel for an ongoing EmpathyTpFile. It's safe to call this method after the transfer has ended.

`tp_file` : | an EmpathyTpFile

### empathy_tp_file_is_incoming ()

    gboolean            empathy_tp_file_is_incoming         (EmpathyTpFile *tp_file);

Returns whether `tp_file` is incoming.

`tp_file` : | an EmpathyTpFile
Returns : | `TRUE` if the `tp_file` is incoming, otherwise `FALSE`

## Property Details

### The `"channel"` property

      "channel"                  TpChannel*            : Read / Write / Construct Only

The TpChannel requested for the file transfer.

### The `"incoming"` property

      "incoming"                 gboolean              : Read / Write / Construct Only

`TRUE` if the transfer is incoming, `FALSE` if it's outgoing.

Default value: FALSE