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_ */ 815