libpurple/ft.h

   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  * Starts a file transfer.
 594  *
 595  * Either @a fd must be specified <i>or</i> @a ip and @a port on a
 596  * file receive transfer. On send, @a fd must be specified, and
 597  * @a ip and @a port are ignored.
 598  *
 599  * Prior to libpurple 2.6.0, passing '0' to @a fd was special-cased to
 600  * allow the protocol plugin to facilitate the file transfer itself. As of
 601  * 2.6.0, this is supported (for backward compatibility), but will be
 602  * removed in libpurple 3.0.0. If a prpl detects that the running libpurple
 603  * is running 2.6.0 or higher, it should use the invalid fd '-1'.
 604  *
 605  * @param xfer The file transfer.
 606  * @param fd   The file descriptor for the socket.
 607  * @param ip   The IP address to connect to.
 608  * @param port The port to connect to.
 609  */
 610 void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip,
 611                                          unsigned int port);
 612
 613 /**
 614  * Ends a file transfer.
 615  *
 616  * @param xfer The file transfer.
 617  */
 618 void purple_xfer_end(PurpleXfer *xfer);
 619
 620 /**
 621  * Adds a new file transfer to the list of file transfers. Call this only
 622  * if you are not using purple_xfer_start.
 623  *
 624  * @param xfer The file transfer.
 625  */
 626 void purple_xfer_add(PurpleXfer *xfer);
 627
 628 /**
 629  * Cancels a file transfer on the local end.
 630  *
 631  * @param xfer The file transfer.
 632  */
 633 void purple_xfer_cancel_local(PurpleXfer *xfer);
 634
 635 /**
 636  * Cancels a file transfer from the remote end.
 637  *
 638  * @param xfer The file transfer.
 639  */
 640 void purple_xfer_cancel_remote(PurpleXfer *xfer);
 641
 642 /**
 643  * Displays a file transfer-related error message.
 644  *
 645  * This is a wrapper around purple_notify_error(), which automatically
 646  * specifies a title ("File transfer to <i>user</i> failed" or
 647  * "File Transfer from <i>user</i> failed").
 648  *
 649  * @param type    The type of file transfer.
 650  * @param account The account sending or receiving the file.
 651  * @param who     The user on the other end of the transfer.
 652  * @param msg     The message to display.
 653  */
 654 void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg);
 655
 656 /**
 657  * Updates file transfer progress.
 658  *
 659  * @param xfer      The file transfer.
 660  */
 661 void purple_xfer_update_progress(PurpleXfer *xfer);
 662
 663 /**
 664  * Displays a file transfer-related message in the conversation window
 665  *
 666  * This is a wrapper around purple_conversation_write
 667  *
 668  * @param xfer The file transfer to which this message relates.
 669  * @param message The message to display.
 670  * @param is_error Is this an error message?.
 671  */
 672 void purple_xfer_conversation_write(PurpleXfer *xfer, char *message, gboolean is_error);
 673
 674 /**
 675  * Allows the UI to signal it's ready to send/receive data (depending on
 676  * the direction of the file transfer. Used when the UI is providing
 677  * read/write/data_not_sent UI ops.
 678  *
 679  * @param xfer The file transfer which is ready.
 680  *
 681  * @since 2.6.0
 682  */
 683 void purple_xfer_ui_ready(PurpleXfer *xfer);
 684
 685 /**
 686  * Allows the prpl to signal it's ready to send/receive data (depending on
 687  * the direction of the file transfer. Used when the prpl provides read/write
 688  * ops and cannot/does not provide a raw fd to the core.
 689  *
 690  * @param xfer The file transfer which is ready.
 691  *
 692  * @since 2.6.0
 693  */
 694 void purple_xfer_prpl_ready(PurpleXfer *xfer);
 695
 696 /**
 697  * Gets the thumbnail data for a transfer
 698  *
 699  * @param xfer The file transfer to get the thumbnail for
 700  * @param len  If not @c NULL, the length of the thumbnail data returned
 701  *             will be set in the location pointed to by this.
 702  * @return The thumbnail data, or NULL if there is no thumbnail
 703  * @since 2.7.0
 704  */
 705 gconstpointer purple_xfer_get_thumbnail(const PurpleXfer *xfer, gsize *len);
 706
 707 /**
 708  * Gets the mimetype of the thumbnail preview for a transfer
 709  *
 710  * @param xfer The file transfer to get the mimetype for
 711  * @return The mimetype of the thumbnail, or @c NULL if not thumbnail is set
 712  * @since 2.7.0
 713  */
 714 const gchar *purple_xfer_get_thumbnail_mimetype(const PurpleXfer *xfer);
 715
 716
 717 /**
 718  * Sets the thumbnail data for a transfer
 719  *
 720  * @param xfer The file transfer to set the data for
 721  * @param thumbnail A pointer to the thumbnail data, this will be copied
 722  * @param size The size in bytes of the passed in thumbnail data
 723  * @param mimetype The mimetype of the generated thumbnail
 724  * @since 2.7.0
 725  */
 726 void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail,
 727         gsize size, const gchar *mimetype);
 728
 729 /**
 730  * Prepare a thumbnail for a transfer (if the UI supports it)
 731  * will be no-op in case the UI doesn't implement thumbnail creation
 732  *
 733  * @param xfer The file transfer to create a thumbnail for
 734  * @param formats A comma-separated list of mimetypes for image formats
 735  *                the protocols can use for thumbnails.
 736  * @since 2.7.0
 737  */
 738 void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats);
 739
 740
 741 /*@}*/
 742
 743 /**************************************************************************/
 744 /** @name UI Registration Functions                                       */
 745 /**************************************************************************/
 746 /*@{*/
 747
 748 /**
 749  * Returns the handle to the file transfer subsystem
 750  *
 751  * @return The handle
 752  */
 753 void *purple_xfers_get_handle(void);
 754
 755 /**
 756  * Initializes the file transfer subsystem
 757  */
 758 void purple_xfers_init(void);
 759
 760 /**
 761  * Uninitializes the file transfer subsystem
 762  */
 763 void purple_xfers_uninit(void);
 764
 765 /**
 766  * Sets the UI operations structure to be used in all purple file transfers.
 767  *
 768  * @param ops The UI operations structure.
 769  */
 770 void purple_xfers_set_ui_ops(PurpleXferUiOps *ops);
 771
 772 /**
 773  * Returns the UI operations structure to be used in all purple file transfers.
 774  *
 775  * @return The UI operations structure.
 776  */
 777 PurpleXferUiOps *purple_xfers_get_ui_ops(void);
 778
 779 /*@}*/
 780
 781 #ifdef __cplusplus
 782 }
 783 #endif
 784
 785 #endif /* _PURPLE_FT_H_ */