Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/ft.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     1 /**
       
     2  * @file ft.h File Transfer API
       
     3  * @ingroup core
       
     4  * @see @ref xfer-signals
       
     5  */
       
     6 
       
     7 /* purple
       
     8  *
       
     9  * Purple is the legal property of its developers, whose names are too numerous
       
    10  * to list here.  Please refer to the COPYRIGHT file distributed with this
       
    11  * source distribution.
       
    12  *
       
    13  * This program is free software; you can redistribute it and/or modify
       
    14  * it under the terms of the GNU General Public License as published by
       
    15  * the Free Software Foundation; either version 2 of the License, or
       
    16  * (at your option) any later version.
       
    17  *
       
    18  * This program is distributed in the hope that it will be useful,
       
    19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
       
    20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       
    21  * GNU General Public License for more details.
       
    22  *
       
    23  * You should have received a copy of the GNU General Public License
       
    24  * along with this program; if not, write to the Free Software
       
    25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
       
    26  */
       
    27 #ifndef _PURPLE_FT_H_
       
    28 #define _PURPLE_FT_H_
       
    29 
       
    30 /**************************************************************************/
       
    31 /** Data Structures                                                       */
       
    32 /**************************************************************************/
       
    33 typedef struct _PurpleXfer PurpleXfer;
       
    34 
       
    35 #include <glib.h>
       
    36 #include <stdio.h>
       
    37 
       
    38 #include "account.h"
       
    39 
       
    40 /**
       
    41  * Types of file transfers.
       
    42  */
       
    43 typedef enum
       
    44 {
       
    45 	PURPLE_XFER_UNKNOWN = 0,  /**< Unknown file transfer type. */
       
    46 	PURPLE_XFER_SEND,         /**< File sending.               */
       
    47 	PURPLE_XFER_RECEIVE       /**< File receiving.             */
       
    48 
       
    49 } PurpleXferType;
       
    50 
       
    51 /**
       
    52  * The different states of the xfer.
       
    53  */
       
    54 typedef enum
       
    55 {
       
    56 	PURPLE_XFER_STATUS_UNKNOWN = 0,   /**< Unknown, the xfer may be null. */
       
    57 	PURPLE_XFER_STATUS_NOT_STARTED,   /**< It hasn't started yet. */
       
    58 	PURPLE_XFER_STATUS_ACCEPTED,      /**< Receive accepted, but destination file not selected yet */
       
    59 	PURPLE_XFER_STATUS_STARTED,       /**< purple_xfer_start has been called. */
       
    60 	PURPLE_XFER_STATUS_DONE,          /**< The xfer completed successfully. */
       
    61 	PURPLE_XFER_STATUS_CANCEL_LOCAL,  /**< The xfer was cancelled by us. */
       
    62 	PURPLE_XFER_STATUS_CANCEL_REMOTE  /**< The xfer was cancelled by the other end, or we couldn't connect. */
       
    63 } PurpleXferStatusType;
       
    64 
       
    65 /**
       
    66  * File transfer UI operations.
       
    67  *
       
    68  * Any UI representing a file transfer must assign a filled-out
       
    69  * PurpleXferUiOps structure to the purple_xfer.
       
    70  */
       
    71 typedef struct
       
    72 {
       
    73 	void (*new_xfer)(PurpleXfer *xfer);
       
    74 	void (*destroy)(PurpleXfer *xfer);
       
    75 	void (*add_xfer)(PurpleXfer *xfer);
       
    76 	void (*update_progress)(PurpleXfer *xfer, double percent);
       
    77 	void (*cancel_local)(PurpleXfer *xfer);
       
    78 	void (*cancel_remote)(PurpleXfer *xfer);
       
    79 
       
    80 	/**
       
    81 	 * UI op to write data received from the prpl. The UI must deal with the
       
    82 	 * entire buffer and return size, or it is treated as an error.
       
    83 	 *
       
    84 	 * @param xfer    The file transfer structure
       
    85 	 * @param buffer  The buffer to write
       
    86 	 * @param size    The size of the buffer
       
    87 	 *
       
    88 	 * @return size if the write was successful, or a value between 0 and
       
    89 	 *         size on error.
       
    90 	 * @since 2.6.0
       
    91 	 */
       
    92 	gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size);
       
    93 
       
    94 	/**
       
    95 	 * UI op to read data to send to the prpl for a file transfer.
       
    96 	 *
       
    97 	 * @param xfer    The file transfer structure
       
    98 	 * @param buffer  A pointer to a buffer. The UI must allocate this buffer.
       
    99 	 *                libpurple will free the data.
       
   100 	 * @param size    The maximum amount of data to put in the buffer.
       
   101 	 *
       
   102 	 * @returns The amount of data in the buffer, 0 if nothing is available,
       
   103 	 *          and a negative value if an error occurred and the transfer
       
   104 	 *          should be cancelled (libpurple will cancel).
       
   105 	 * @since 2.6.0
       
   106 	 */
       
   107 	gssize (*ui_read)(PurpleXfer *xfer, guchar **buffer, gssize size);
       
   108 
       
   109 	/**
       
   110 	 * Op to notify the UI that not all the data read in was written. The UI
       
   111 	 * should re-enqueue this data and return it the next time read is called.
       
   112 	 *
       
   113 	 * This MUST be implemented if read and write are implemented.
       
   114 	 *
       
   115 	 * @param xfer    The file transfer structure
       
   116 	 * @param buffer  A pointer to the beginning of the unwritten data.
       
   117 	 * @param size    The amount of unwritten data.
       
   118 	 *
       
   119 	 * @since 2.6.0
       
   120 	 */
       
   121 	void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size);
       
   122 
       
   123 	/**
       
   124 	 * Op to create a thumbnail image for a file transfer
       
   125 	 *
       
   126 	 * @param xfer   The file transfer structure
       
   127 	 */
       
   128 	void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats);
       
   129 } PurpleXferUiOps;
       
   130 
       
   131 /**
       
   132  * A core representation of a file transfer.
       
   133  */
       
   134 struct _PurpleXfer
       
   135 {
       
   136 	guint ref;                    /**< The reference count.                */
       
   137 	PurpleXferType type;            /**< The type of transfer.               */
       
   138 
       
   139 	PurpleAccount *account;         /**< The account.                        */
       
   140 
       
   141 	char *who;                    /**< The person on the other end of the
       
   142 	                                   transfer.                           */
       
   143 
       
   144 	char *message;                /**< A message sent with the request     */
       
   145 	char *filename;               /**< The name sent over the network.     */
       
   146 	char *local_filename;         /**< The name on the local hard drive.   */
       
   147 	size_t size;                  /**< The size of the file.               */
       
   148 
       
   149 	FILE *dest_fp;                /**< The destination file pointer.       */
       
   150 
       
   151 	char *remote_ip;              /**< The remote IP address.              */
       
   152 	int local_port;               /**< The local port.                     */
       
   153 	int remote_port;              /**< The remote port.                    */
       
   154 
       
   155 	int fd;                       /**< The socket file descriptor.         */
       
   156 	int watcher;                  /**< Watcher.                            */
       
   157 
       
   158 	size_t bytes_sent;            /**< The number of bytes sent.           */
       
   159 	size_t bytes_remaining;       /**< The number of bytes remaining.      */
       
   160 	time_t start_time;            /**< When the transfer of data began.    */
       
   161 	time_t end_time;              /**< When the transfer of data ended.    */
       
   162 
       
   163 	size_t current_buffer_size;   /**< This gradually increases for fast
       
   164 	                                   network connections. */
       
   165 
       
   166 	PurpleXferStatusType status;    /**< File Transfer's status.             */
       
   167 
       
   168 	/** I/O operations, which should be set by the prpl using
       
   169 	 *  purple_xfer_set_init_fnc() and friends.  Setting #init is
       
   170 	 *  mandatory; all others are optional.
       
   171 	 */
       
   172 	struct
       
   173 	{
       
   174 		void (*init)(PurpleXfer *xfer);
       
   175 		void (*request_denied)(PurpleXfer *xfer);
       
   176 		void (*start)(PurpleXfer *xfer);
       
   177 		void (*end)(PurpleXfer *xfer);
       
   178 		void (*cancel_send)(PurpleXfer *xfer);
       
   179 		void (*cancel_recv)(PurpleXfer *xfer);
       
   180 		gssize (*read)(guchar **buffer, PurpleXfer *xfer);
       
   181 		gssize (*write)(const guchar *buffer, size_t size, PurpleXfer *xfer);
       
   182 		void (*ack)(PurpleXfer *xfer, const guchar *buffer, size_t size);
       
   183 	} ops;
       
   184 
       
   185 	PurpleXferUiOps *ui_ops;            /**< UI-specific operations. */
       
   186 	void *ui_data;                    /**< UI-specific data.       */
       
   187 
       
   188 	void *data;                       /**< prpl-specific data.     */
       
   189 };
       
   190 
       
   191 #ifdef __cplusplus
       
   192 extern "C" {
       
   193 #endif
       
   194 
       
   195 /**************************************************************************/
       
   196 /** @name File Transfer API                                               */
       
   197 /**************************************************************************/
       
   198 /*@{*/
       
   199 
       
   200 /**
       
   201  * Creates a new file transfer handle.
       
   202  * This is called by prpls.
       
   203  * The handle starts with a ref count of 1, and this reference
       
   204  * is owned by the core. The prpl normally does not need to
       
   205  * purple_xfer_ref or unref.
       
   206  *
       
   207  * @param account The account sending or receiving the file.
       
   208  * @param type    The type of file transfer.
       
   209  * @param who     The name of the remote user.
       
   210  *
       
   211  * @return A file transfer handle.
       
   212  */
       
   213 PurpleXfer *purple_xfer_new(PurpleAccount *account,
       
   214 								PurpleXferType type, const char *who);
       
   215 
       
   216 /**
       
   217  * Returns all xfers
       
   218  *
       
   219  * @return all current xfers with refs
       
   220  */
       
   221 GList *purple_xfers_get_all(void);
       
   222 
       
   223 /**
       
   224  * Increases the reference count on a PurpleXfer.
       
   225  * Please call purple_xfer_unref later.
       
   226  *
       
   227  * @param xfer A file transfer handle.
       
   228  */
       
   229 void purple_xfer_ref(PurpleXfer *xfer);
       
   230 
       
   231 /**
       
   232  * Decreases the reference count on a PurpleXfer.
       
   233  * If the reference reaches 0, purple_xfer_destroy (an internal function)
       
   234  * will destroy the xfer. It calls the ui destroy cb first.
       
   235  * Since the core keeps a ref on the xfer, only an erroneous call to
       
   236  * this function will destroy the xfer while still in use.
       
   237  *
       
   238  * @param xfer A file transfer handle.
       
   239  */
       
   240 void purple_xfer_unref(PurpleXfer *xfer);
       
   241 
       
   242 /**
       
   243  * Requests confirmation for a file transfer from the user. If receiving
       
   244  * a file which is known at this point, this requests user to accept and
       
   245  * save the file. If the filename is unknown (not set) this only requests user
       
   246  * to accept the file transfer. In this case protocol must call this function
       
   247  * again once the filename is available.
       
   248  *
       
   249  * @param xfer The file transfer to request confirmation on.
       
   250  */
       
   251 void purple_xfer_request(PurpleXfer *xfer);
       
   252 
       
   253 /**
       
   254  * Called if the user accepts the file transfer request.
       
   255  *
       
   256  * @param xfer     The file transfer.
       
   257  * @param filename The filename.
       
   258  */
       
   259 void purple_xfer_request_accepted(PurpleXfer *xfer, const char *filename);
       
   260 
       
   261 /**
       
   262  * Called if the user rejects the file transfer request.
       
   263  *
       
   264  * @param xfer The file transfer.
       
   265  */
       
   266 void purple_xfer_request_denied(PurpleXfer *xfer);
       
   267 
       
   268 /**
       
   269  * Returns the type of file transfer.
       
   270  *
       
   271  * @param xfer The file transfer.
       
   272  *
       
   273  * @return The type of the file transfer.
       
   274  */
       
   275 PurpleXferType purple_xfer_get_type(const PurpleXfer *xfer);
       
   276 
       
   277 /**
       
   278  * Returns the account the file transfer is using.
       
   279  *
       
   280  * @param xfer The file transfer.
       
   281  *
       
   282  * @return The account.
       
   283  */
       
   284 PurpleAccount *purple_xfer_get_account(const PurpleXfer *xfer);
       
   285 
       
   286 /**
       
   287  * Returns the name of the remote user.
       
   288  *
       
   289  * @param xfer The file transfer.
       
   290  *
       
   291  * @return The name of the remote user.
       
   292  *
       
   293  * @since 2.1.0
       
   294  */
       
   295 const char *purple_xfer_get_remote_user(const PurpleXfer *xfer);
       
   296 
       
   297 /**
       
   298  * Returns the status of the xfer.
       
   299  *
       
   300  * @param xfer The file transfer.
       
   301  *
       
   302  * @return The status.
       
   303  */
       
   304 PurpleXferStatusType purple_xfer_get_status(const PurpleXfer *xfer);
       
   305 
       
   306 /**
       
   307  * Returns true if the file transfer was cancelled.
       
   308  *
       
   309  * @param xfer The file transfer.
       
   310  *
       
   311  * @return Whether or not the transfer was cancelled.
       
   312  * FIXME: This should be renamed using cancelled for 3.0.0.
       
   313  */
       
   314 gboolean purple_xfer_is_canceled(const PurpleXfer *xfer);
       
   315 
       
   316 /**
       
   317  * Returns the completed state for a file transfer.
       
   318  *
       
   319  * @param xfer The file transfer.
       
   320  *
       
   321  * @return The completed state.
       
   322  */
       
   323 gboolean purple_xfer_is_completed(const PurpleXfer *xfer);
       
   324 
       
   325 /**
       
   326  * Returns the name of the file being sent or received.
       
   327  *
       
   328  * @param xfer The file transfer.
       
   329  *
       
   330  * @return The filename.
       
   331  */
       
   332 const char *purple_xfer_get_filename(const PurpleXfer *xfer);
       
   333 
       
   334 /**
       
   335  * Returns the file's destination filename,
       
   336  *
       
   337  * @param xfer The file transfer.
       
   338  *
       
   339  * @return The destination filename.
       
   340  */
       
   341 const char *purple_xfer_get_local_filename(const PurpleXfer *xfer);
       
   342 
       
   343 /**
       
   344  * Returns the number of bytes sent (or received) so far.
       
   345  *
       
   346  * @param xfer The file transfer.
       
   347  *
       
   348  * @return The number of bytes sent.
       
   349  */
       
   350 size_t purple_xfer_get_bytes_sent(const PurpleXfer *xfer);
       
   351 
       
   352 /**
       
   353  * Returns the number of bytes remaining to send or receive.
       
   354  *
       
   355  * @param xfer The file transfer.
       
   356  *
       
   357  * @return The number of bytes remaining.
       
   358  */
       
   359 size_t purple_xfer_get_bytes_remaining(const PurpleXfer *xfer);
       
   360 
       
   361 /**
       
   362  * Returns the size of the file being sent or received.
       
   363  *
       
   364  * @param xfer The file transfer.
       
   365  *
       
   366  * @return The total size of the file.
       
   367  */
       
   368 size_t purple_xfer_get_size(const PurpleXfer *xfer);
       
   369 
       
   370 /**
       
   371  * Returns the current percentage of progress of the transfer.
       
   372  *
       
   373  * This is a number between 0 (0%) and 1 (100%).
       
   374  *
       
   375  * @param xfer The file transfer.
       
   376  *
       
   377  * @return The percentage complete.
       
   378  */
       
   379 double purple_xfer_get_progress(const PurpleXfer *xfer);
       
   380 
       
   381 /**
       
   382  * Returns the local port number in the file transfer.
       
   383  *
       
   384  * @param xfer The file transfer.
       
   385  *
       
   386  * @return The port number on this end.
       
   387  */
       
   388 unsigned int purple_xfer_get_local_port(const PurpleXfer *xfer);
       
   389 
       
   390 /**
       
   391  * Returns the remote IP address in the file transfer.
       
   392  *
       
   393  * @param xfer The file transfer.
       
   394  *
       
   395  * @return The IP address on the other end.
       
   396  */
       
   397 const char *purple_xfer_get_remote_ip(const PurpleXfer *xfer);
       
   398 
       
   399 /**
       
   400  * Returns the remote port number in the file transfer.
       
   401  *
       
   402  * @param xfer The file transfer.
       
   403  *
       
   404  * @return The port number on the other end.
       
   405  */
       
   406 unsigned int purple_xfer_get_remote_port(const PurpleXfer *xfer);
       
   407 
       
   408 /**
       
   409  * Returns the time the transfer of a file started.
       
   410  *
       
   411  * @param xfer  The file transfer.
       
   412  *
       
   413  * @return The time when the transfer started.
       
   414  * @since 2.4.0
       
   415  */
       
   416 time_t purple_xfer_get_start_time(const PurpleXfer *xfer);
       
   417 
       
   418 /**
       
   419  * Returns the time the transfer of a file ended.
       
   420  *
       
   421  * @param xfer  The file transfer.
       
   422  *
       
   423  * @return The time when the transfer ended.
       
   424  * @since 2.4.0
       
   425  */
       
   426 time_t purple_xfer_get_end_time(const PurpleXfer *xfer);
       
   427 
       
   428 /**
       
   429  * Sets the completed state for the file transfer.
       
   430  *
       
   431  * @param xfer      The file transfer.
       
   432  * @param completed The completed state.
       
   433  */
       
   434 void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed);
       
   435 
       
   436 /**
       
   437  * Sets the filename for the file transfer.
       
   438  *
       
   439  * @param xfer     The file transfer.
       
   440  * @param message The message.
       
   441  */
       
   442 void purple_xfer_set_message(PurpleXfer *xfer, const char *message);
       
   443 
       
   444 /**
       
   445  * Sets the filename for the file transfer.
       
   446  *
       
   447  * @param xfer     The file transfer.
       
   448  * @param filename The filename.
       
   449  */
       
   450 void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename);
       
   451 
       
   452 /**
       
   453  * Sets the local filename for the file transfer.
       
   454  *
       
   455  * @param xfer     The file transfer.
       
   456  * @param filename The filename
       
   457  */
       
   458 void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename);
       
   459 
       
   460 /**
       
   461  * Sets the size of the file in a file transfer.
       
   462  *
       
   463  * @param xfer The file transfer.
       
   464  * @param size The size of the file.
       
   465  */
       
   466 void purple_xfer_set_size(PurpleXfer *xfer, size_t size);
       
   467 
       
   468 /**
       
   469  * Sets the current working position in the active file transfer.  This
       
   470  * can be used to jump backward in the file if the protocol detects
       
   471  * that some bit of data needs to be resent or has been sent twice.
       
   472  *
       
   473  * It's used for pausing and resuming an oscar file transfer.
       
   474  *
       
   475  * @param xfer       The file transfer.
       
   476  * @param bytes_sent The new current position in the file.  If we're
       
   477  *                   sending a file then this is the byte that we will
       
   478  *                   send.  If we're receiving a file, this is the
       
   479  *                   next byte that we expect to receive.
       
   480  */
       
   481 void purple_xfer_set_bytes_sent(PurpleXfer *xfer, size_t bytes_sent);
       
   482 
       
   483 /**
       
   484  * Returns the UI operations structure for a file transfer.
       
   485  *
       
   486  * @param xfer The file transfer.
       
   487  *
       
   488  * @return The UI operations structure.
       
   489  */
       
   490 PurpleXferUiOps *purple_xfer_get_ui_ops(const PurpleXfer *xfer);
       
   491 
       
   492 /**
       
   493  * Sets the read function for the file transfer.
       
   494  *
       
   495  * @param xfer The file transfer.
       
   496  * @param fnc  The read function.
       
   497  */
       
   498 void purple_xfer_set_read_fnc(PurpleXfer *xfer,
       
   499 		gssize (*fnc)(guchar **, PurpleXfer *));
       
   500 
       
   501 /**
       
   502  * Sets the write function for the file transfer.
       
   503  *
       
   504  * @param xfer The file transfer.
       
   505  * @param fnc  The write function.
       
   506  */
       
   507 void purple_xfer_set_write_fnc(PurpleXfer *xfer,
       
   508 		gssize (*fnc)(const guchar *, size_t, PurpleXfer *));
       
   509 
       
   510 /**
       
   511  * Sets the acknowledge function for the file transfer.
       
   512  *
       
   513  * @param xfer The file transfer.
       
   514  * @param fnc  The acknowledge function.
       
   515  */
       
   516 void purple_xfer_set_ack_fnc(PurpleXfer *xfer,
       
   517 		void (*fnc)(PurpleXfer *, const guchar *, size_t));
       
   518 
       
   519 /**
       
   520  * Sets the function to be called if the request is denied.
       
   521  *
       
   522  * @param xfer The file transfer.
       
   523  * @param fnc The request denied prpl callback.
       
   524  */
       
   525 void purple_xfer_set_request_denied_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   526 
       
   527 /**
       
   528  * Sets the transfer initialization function for the file transfer.
       
   529  *
       
   530  * This function is required, and must call purple_xfer_start() with
       
   531  * the necessary parameters. This will be called if the file transfer
       
   532  * is accepted by the user.
       
   533  *
       
   534  * @param xfer The file transfer.
       
   535  * @param fnc  The transfer initialization function.
       
   536  */
       
   537 void purple_xfer_set_init_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   538 
       
   539 /**
       
   540  * Sets the start transfer function for the file transfer.
       
   541  *
       
   542  * @param xfer The file transfer.
       
   543  * @param fnc  The start transfer function.
       
   544  */
       
   545 void purple_xfer_set_start_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   546 
       
   547 /**
       
   548  * Sets the end transfer function for the file transfer.
       
   549  *
       
   550  * @param xfer The file transfer.
       
   551  * @param fnc  The end transfer function.
       
   552  */
       
   553 void purple_xfer_set_end_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   554 
       
   555 /**
       
   556  * Sets the cancel send function for the file transfer.
       
   557  *
       
   558  * @param xfer The file transfer.
       
   559  * @param fnc  The cancel send function.
       
   560  */
       
   561 void purple_xfer_set_cancel_send_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   562 
       
   563 /**
       
   564  * Sets the cancel receive function for the file transfer.
       
   565  *
       
   566  * @param xfer The file transfer.
       
   567  * @param fnc  The cancel receive function.
       
   568  */
       
   569 void purple_xfer_set_cancel_recv_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
       
   570 
       
   571 /**
       
   572  * Reads in data from a file transfer stream.
       
   573  *
       
   574  * @param xfer   The file transfer.
       
   575  * @param buffer The buffer that will be created to contain the data.
       
   576  *
       
   577  * @return The number of bytes read, or -1.
       
   578  */
       
   579 gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer);
       
   580 
       
   581 /**
       
   582  * Writes data to a file transfer stream.
       
   583  *
       
   584  * @param xfer   The file transfer.
       
   585  * @param buffer The buffer to read the data from.
       
   586  * @param size   The number of bytes to write.
       
   587  *
       
   588  * @return The number of bytes written, or -1.
       
   589  */
       
   590 gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size);
       
   591 
       
   592 /**
       
   593  * Writes chunk of received file.
       
   594  *
       
   595  * @param xfer   The file transfer.
       
   596  * @param buffer The buffer to read the data from.
       
   597  * @param size   The number of bytes to write.
       
   598  *
       
   599  * @return TRUE on success, FALSE otherwise.
       
   600  *
       
   601  * @since 2.11.0
       
   602  */
       
   603 gboolean
       
   604 purple_xfer_write_file(PurpleXfer *xfer, const guchar *buffer, gsize size);
       
   605 
       
   606 /**
       
   607  * Writes chunk of file being sent.
       
   608  *
       
   609  * @param xfer   The file transfer.
       
   610  * @param buffer The buffer to write the data to.
       
   611  * @param size   The size of buffer.
       
   612  *
       
   613  * @return Number of bytes written (0 means, the device is busy), or -1 on
       
   614  *         failure.
       
   615  *
       
   616  * @since 2.11.0
       
   617  */
       
   618 gssize
       
   619 purple_xfer_read_file(PurpleXfer *xfer, guchar *buffer, gsize size);
       
   620 
       
   621 /**
       
   622  * Starts a file transfer.
       
   623  *
       
   624  * Either @a fd must be specified <i>or</i> @a ip and @a port on a
       
   625  * file receive transfer. On send, @a fd must be specified, and
       
   626  * @a ip and @a port are ignored.
       
   627  *
       
   628  * Prior to libpurple 2.6.0, passing '0' to @a fd was special-cased to
       
   629  * allow the protocol plugin to facilitate the file transfer itself. As of
       
   630  * 2.6.0, this is supported (for backward compatibility), but will be
       
   631  * removed in libpurple 3.0.0. If a prpl detects that the running libpurple
       
   632  * is running 2.6.0 or higher, it should use the invalid fd '-1'.
       
   633  *
       
   634  * @param xfer The file transfer.
       
   635  * @param fd   The file descriptor for the socket.
       
   636  * @param ip   The IP address to connect to.
       
   637  * @param port The port to connect to.
       
   638  */
       
   639 void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip,
       
   640 					 unsigned int port);
       
   641 
       
   642 /**
       
   643  * Ends a file transfer.
       
   644  *
       
   645  * @param xfer The file transfer.
       
   646  */
       
   647 void purple_xfer_end(PurpleXfer *xfer);
       
   648 
       
   649 /**
       
   650  * Adds a new file transfer to the list of file transfers. Call this only
       
   651  * if you are not using purple_xfer_start.
       
   652  *
       
   653  * @param xfer The file transfer.
       
   654  */
       
   655 void purple_xfer_add(PurpleXfer *xfer);
       
   656 
       
   657 /**
       
   658  * Cancels a file transfer on the local end.
       
   659  *
       
   660  * @param xfer The file transfer.
       
   661  */
       
   662 void purple_xfer_cancel_local(PurpleXfer *xfer);
       
   663 
       
   664 /**
       
   665  * Cancels a file transfer from the remote end.
       
   666  *
       
   667  * @param xfer The file transfer.
       
   668  */
       
   669 void purple_xfer_cancel_remote(PurpleXfer *xfer);
       
   670 
       
   671 /**
       
   672  * Displays a file transfer-related error message.
       
   673  *
       
   674  * This is a wrapper around purple_notify_error(), which automatically
       
   675  * specifies a title ("File transfer to <i>user</i> failed" or
       
   676  * "File Transfer from <i>user</i> failed").
       
   677  *
       
   678  * @param type    The type of file transfer.
       
   679  * @param account The account sending or receiving the file.
       
   680  * @param who     The user on the other end of the transfer.
       
   681  * @param msg     The message to display.
       
   682  */
       
   683 void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg);
       
   684 
       
   685 /**
       
   686  * Updates file transfer progress.
       
   687  *
       
   688  * @param xfer      The file transfer.
       
   689  */
       
   690 void purple_xfer_update_progress(PurpleXfer *xfer);
       
   691 
       
   692 /**
       
   693  * Displays a file transfer-related message in the conversation window
       
   694  *
       
   695  * This is a wrapper around purple_conversation_write
       
   696  *
       
   697  * @param xfer The file transfer to which this message relates.
       
   698  * @param message The message to display.
       
   699  * @param is_error Is this an error message?.
       
   700  */
       
   701 void purple_xfer_conversation_write(PurpleXfer *xfer, char *message, gboolean is_error);
       
   702 
       
   703 /**
       
   704  * Allows the UI to signal it's ready to send/receive data (depending on
       
   705  * the direction of the file transfer. Used when the UI is providing
       
   706  * read/write/data_not_sent UI ops.
       
   707  *
       
   708  * @param xfer The file transfer which is ready.
       
   709  *
       
   710  * @since 2.6.0
       
   711  */
       
   712 void purple_xfer_ui_ready(PurpleXfer *xfer);
       
   713 
       
   714 /**
       
   715  * Allows the prpl to signal it's ready to send/receive data (depending on
       
   716  * the direction of the file transfer. Used when the prpl provides read/write
       
   717  * ops and cannot/does not provide a raw fd to the core.
       
   718  *
       
   719  * @param xfer The file transfer which is ready.
       
   720  *
       
   721  * @since 2.6.0
       
   722  */
       
   723 void purple_xfer_prpl_ready(PurpleXfer *xfer);
       
   724 
       
   725 /**
       
   726  * Gets the thumbnail data for a transfer
       
   727  *
       
   728  * @param xfer The file transfer to get the thumbnail for
       
   729  * @param len  If not @c NULL, the length of the thumbnail data returned
       
   730  *             will be set in the location pointed to by this.
       
   731  * @return The thumbnail data, or NULL if there is no thumbnail
       
   732  * @since 2.7.0
       
   733  */
       
   734 gconstpointer purple_xfer_get_thumbnail(const PurpleXfer *xfer, gsize *len);
       
   735 
       
   736 /**
       
   737  * Gets the mimetype of the thumbnail preview for a transfer
       
   738  *
       
   739  * @param xfer The file transfer to get the mimetype for
       
   740  * @return The mimetype of the thumbnail, or @c NULL if not thumbnail is set
       
   741  * @since 2.7.0
       
   742  */
       
   743 const gchar *purple_xfer_get_thumbnail_mimetype(const PurpleXfer *xfer);
       
   744 
       
   745 
       
   746 /**
       
   747  * Sets the thumbnail data for a transfer
       
   748  *
       
   749  * @param xfer The file transfer to set the data for
       
   750  * @param thumbnail A pointer to the thumbnail data, this will be copied
       
   751  * @param size The size in bytes of the passed in thumbnail data
       
   752  * @param mimetype The mimetype of the generated thumbnail
       
   753  * @since 2.7.0
       
   754  */
       
   755 void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail,
       
   756 	gsize size, const gchar *mimetype);
       
   757 
       
   758 /**
       
   759  * Prepare a thumbnail for a transfer (if the UI supports it)
       
   760  * will be no-op in case the UI doesn't implement thumbnail creation
       
   761  *
       
   762  * @param xfer The file transfer to create a thumbnail for
       
   763  * @param formats A comma-separated list of mimetypes for image formats
       
   764  *	 	  the protocols can use for thumbnails.
       
   765  * @since 2.7.0
       
   766  */
       
   767 void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats);
       
   768 
       
   769 
       
   770 /*@}*/
       
   771 
       
   772 /**************************************************************************/
       
   773 /** @name UI Registration Functions                                       */
       
   774 /**************************************************************************/
       
   775 /*@{*/
       
   776 
       
   777 /**
       
   778  * Returns the handle to the file transfer subsystem
       
   779  *
       
   780  * @return The handle
       
   781  */
       
   782 void *purple_xfers_get_handle(void);
       
   783 
       
   784 /**
       
   785  * Initializes the file transfer subsystem
       
   786  */
       
   787 void purple_xfers_init(void);
       
   788 
       
   789 /**
       
   790  * Uninitializes the file transfer subsystem
       
   791  */
       
   792 void purple_xfers_uninit(void);
       
   793 
       
   794 /**
       
   795  * Sets the UI operations structure to be used in all purple file transfers.
       
   796  *
       
   797  * @param ops The UI operations structure.
       
   798  */
       
   799 void purple_xfers_set_ui_ops(PurpleXferUiOps *ops);
       
   800 
       
   801 /**
       
   802  * Returns the UI operations structure to be used in all purple file transfers.
       
   803  *
       
   804  * @return The UI operations structure.
       
   805  */
       
   806 PurpleXferUiOps *purple_xfers_get_ui_ops(void);
       
   807 
       
   808 /*@}*/
       
   809 
       
   810 #ifdef __cplusplus
       
   811 }
       
   812 #endif
       
   813 
       
   814 #endif /* _PURPLE_FT_H_ */