libpurple/xfer.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_XFER_H
  23 #define PURPLE_XFER_H
  24 /**
  25  * SECTION:xfer
  26  * @section_id: libpurple-xfer
  27  * @short_description: <filename>xfer.h</filename>
  28  * @title: File Transfer API
  29  * @see_also: <link linkend="chapter-signals-xfer">File Transfer signals</link>
  30  */
  31
  32 #define PURPLE_TYPE_XFER_UI_OPS      (purple_xfer_ui_ops_get_type())
  33
  34 #define PURPLE_TYPE_PROTOCOL_XFER           (purple_protocol_xfer_get_type())
  35 #define PURPLE_PROTOCOL_XFER(obj)           (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PROTOCOL_XFER, PurpleProtocolXfer))
  36 #define PURPLE_IS_PROTOCOL_XFER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_XFER))
  37 #define PURPLE_PROTOCOL_XFER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_XFER, PurpleProtocolXferInterface))
  38
  39 /**************************************************************************/
  40 /* Data Structures                                                        */
  41 /**************************************************************************/
  42 typedef struct _PurpleXferUiOps PurpleXferUiOps;
  43
  44 typedef struct _PurpleProtocolXfer PurpleProtocolXfer;
  45 typedef struct _PurpleProtocolXferInterface PurpleProtocolXferInterface;
  46
  47 #include <glib.h>
  48 #include <stdio.h>
  49
  50 #include "account.h"
  51 #include "connection.h"
  52
  53 /**
  54  * PurpleXferType:
  55  * @PURPLE_XFER_TYPE_UNKNOWN: Unknown file transfer type.
  56  * @PURPLE_XFER_TYPE_SEND:    File sending.
  57  * @PURPLE_XFER_TYPE_RECEIVE: File receiving.
  58  *
  59  * Types of file transfers.
  60  */
  61 typedef enum
  62 {
  63         PURPLE_XFER_TYPE_UNKNOWN = 0,
  64         PURPLE_XFER_TYPE_SEND,
  65         PURPLE_XFER_TYPE_RECEIVE
  66 } PurpleXferType;
  67
  68 /**
  69  * PurpleXferStatus:
  70  * @PURPLE_XFER_STATUS_UNKNOWN:       Unknown, the xfer may be null.
  71  * @PURPLE_XFER_STATUS_NOT_STARTED:   It hasn't started yet.
  72  * @PURPLE_XFER_STATUS_ACCEPTED:      Receive accepted, but destination file
  73  *                                    not selected yet.
  74  * @PURPLE_XFER_STATUS_STARTED:       purple_xfer_start has been called.
  75  * @PURPLE_XFER_STATUS_DONE:          The xfer completed successfully.
  76  * @PURPLE_XFER_STATUS_CANCEL_LOCAL:  The xfer was cancelled by us.
  77  * @PURPLE_XFER_STATUS_CANCEL_REMOTE: The xfer was cancelled by the other end,
  78  *                                    or we couldn't connect.
  79  *
  80  * The different states of the xfer.
  81  */
  82 typedef enum
  83 {
  84         PURPLE_XFER_STATUS_UNKNOWN = 0,
  85         PURPLE_XFER_STATUS_NOT_STARTED,
  86         PURPLE_XFER_STATUS_ACCEPTED,
  87         PURPLE_XFER_STATUS_STARTED,
  88         PURPLE_XFER_STATUS_DONE,
  89         PURPLE_XFER_STATUS_CANCEL_LOCAL,
  90         PURPLE_XFER_STATUS_CANCEL_REMOTE
  91 } PurpleXferStatus;
  92
  93 G_BEGIN_DECLS
  94
  95 #define PURPLE_TYPE_XFER             (purple_xfer_get_type())
  96
  97 G_DECLARE_DERIVABLE_TYPE(PurpleXfer, purple_xfer, PURPLE, XFER, GObject)
  98
  99 /**
 100  * PurpleXferUiOps:
 101  * @new_xfer: UI op that's called after a new transfer is created.
 102  * @destroy: UI op that's called when a transfer is being destroyed.
 103  * @add_xfer: UI op that's called when a transfer should be added to the UI.
 104  * @update_progress: UI op that's called when a transfer's progress has been
 105  *                   updated.
 106  * @cancel_local: UI op that's called when a transfer has been cancelled on the
 107  *                local end.
 108  * @cancel_remote: UI op that's called when a transfer has been cancelled on
 109  *                 the remote end.
 110  * @ui_write: UI op to write data received from the protocol. The UI must deal
 111  *            with the entire buffer and return size, or it is treated as an
 112  *            error.
 113  *            <sbr/>@xfer:   The file transfer structure
 114  *            <sbr/>@buffer: The buffer to write
 115  *            <sbr/>@size:   The size of the buffer
 116  *            <sbr/>Returns: size if the write was successful, or a value
 117  *                           between 0 and size on error.
 118  * @ui_read: UI op to read data to send to the protocol for a file transfer.
 119  *           <sbr/>@xfer:   The file transfer structure
 120  *           <sbr/>@buffer: A pointer to a buffer. The UI must allocate this
 121  *                          buffer. libpurple will free the data.
 122  *           <sbr/>@size:   The maximum amount of data to put in the buffer.
 123  *           <sbr/>Returns: The amount of data in the buffer, 0 if nothing is
 124  *                          available, and a negative value if an error occurred
 125  *                          and the transfer should be cancelled (libpurple will
 126  *                          cancel).
 127  * @data_not_sent: Op to notify the UI that not all the data read in was
 128  *                 written. The UI should re-enqueue this data and return it the
 129  *                 next time read is called.
 130  *                 <sbr/>This <emphasis>MUST</emphasis> be implemented if read
 131  *                 and write are implemented.
 132  *                 <sbr/>@xfer:   The file transfer structure
 133  *                 <sbr/>@buffer: A pointer to the beginning of the unwritten
 134  *                                data.
 135  *                 <sbr/>@size:   The amount of unwritten data.
 136  * @add_thumbnail: Op to create a thumbnail image for a file transfer
 137  *
 138  * File transfer UI operations.
 139  *
 140  * Any UI representing a file transfer must assign a filled-out
 141  * PurpleXferUiOps structure to the purple_xfer.
 142  */
 143 struct _PurpleXferUiOps
 144 {
 145         void (*new_xfer)(PurpleXfer *xfer);
 146         void (*destroy)(PurpleXfer *xfer);
 147         void (*add_xfer)(PurpleXfer *xfer);
 148         void (*update_progress)(PurpleXfer *xfer, double percent);
 149         void (*cancel_local)(PurpleXfer *xfer);
 150         void (*cancel_remote)(PurpleXfer *xfer);
 151         gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size);
 152         gssize (*ui_read)(PurpleXfer *xfer, guchar **buffer, gssize size);
 153         void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size);
 154         void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats);
 155 };
 156
 157 /**
 158  * PurpleXferClass:
 159  * @init: Called when the file transfer is accepted by the user.  Must call
 160  *   purple_xfer_start() and must be implemented.
 161  * @request_denied: Called when the file transfer is denied by the other side.
 162  * @start: Called to start the file transfer.
 163  * @end: Called when the file transfer should end.
 164  * @cancel_send: Handler for cancelling a sending file transfer.
 165  * @cancel_recv: Handler for cancelling a receiving file transfer.
 166  * @read: Called when reading data from the file transfer.
 167  * @write: Called when writing data to the file transfer.
 168  * @ack: Called when a file transfer is acknowledged.
 169  *
 170  * Base class for all #PurpleXfer's
 171  */
 172 struct _PurpleXferClass
 173 {
 174         GObjectClass parent_class;
 175
 176         void (*init)(PurpleXfer *xfer);
 177         void (*request_denied)(PurpleXfer *xfer);
 178         void (*start)(PurpleXfer *xfer);
 179         void (*end)(PurpleXfer *xfer);
 180         void (*cancel_send)(PurpleXfer *xfer);
 181         void (*cancel_recv)(PurpleXfer *xfer);
 182         gssize (*read)(PurpleXfer *xfer, guchar **buffer, gsize size);
 183         gssize (*write)(PurpleXfer *xfer, const guchar *buffer, gsize size);
 184         void (*ack)(PurpleXfer *xfer, const guchar *buffer, gsize size);
 185
 186         /*< private >*/
 187         gpointer reserved[4];
 188 };
 189
 190 /**
 191  * PurpleProtocolXferInterface:
 192  * @can_receive: A method to determine if we can receive a file.
 193  * @send_file: A method to determine if we can send a file.
 194  * @new_xfer: A method to create a new file transfer.
 195  *
 196  * The protocol file transfer interface.
 197  *
 198  * This interface provides file transfer callbacks for the protocol.
 199  */
 200 struct _PurpleProtocolXferInterface
 201 {
 202         /*< private >*/
 203         GTypeInterface parent_iface;
 204
 205         /*< public >*/
 206         gboolean (*can_receive)(PurpleProtocolXfer *prplxfer,
 207                         PurpleConnection *connection, const gchar *who);
 208
 209         void (*send_file)(PurpleProtocolXfer *prplxfer,
 210                         PurpleConnection *connection, const gchar *who,
 211                         const gchar *filename);
 212
 213         PurpleXfer *(*new_xfer)(PurpleProtocolXfer *prplxfer,
 214                         PurpleConnection *connection, const gchar *who);
 215 };
 216
 217 /**************************************************************************/
 218 /* File Transfer API                                                      */
 219 /**************************************************************************/
 220
 221 /**
 222  * purple_xfer_new:
 223  * @account: The account sending or receiving the file.
 224  * @type:    The type of file transfer.
 225  * @who:     The name of the remote user.
 226  *
 227  * Creates a new file transfer handle.
 228  * This is called by protocols.
 229  *
 230  * Returns: A file transfer handle.
 231  */
 232 PurpleXfer *purple_xfer_new(PurpleAccount *account,
 233                                                                 PurpleXferType type, const char *who);
 234
 235 /**
 236  * purple_xfer_request:
 237  * @xfer: The file transfer to request confirmation on.
 238  *
 239  * Requests confirmation for a file transfer from the user. If receiving
 240  * a file which is known at this point, this requests user to accept and
 241  * save the file. If the filename is unknown (not set) this only requests user
 242  * to accept the file transfer. In this case protocol must call this function
 243  * again once the filename is available.
 244  */
 245 void purple_xfer_request(PurpleXfer *xfer);
 246
 247 /**
 248  * purple_xfer_request_accepted:
 249  * @xfer:     The file transfer.
 250  * @filename: The filename.
 251  *
 252  * Called if the user accepts the file transfer request.
 253  */
 254 void purple_xfer_request_accepted(PurpleXfer *xfer, const gchar *filename);
 255
 256 /**
 257  * purple_xfer_request_denied:
 258  * @xfer: The file transfer.
 259  *
 260  * Called if the user rejects the file transfer request.
 261  */
 262 void purple_xfer_request_denied(PurpleXfer *xfer);
 263
 264 /**
 265  * purple_xfer_get_fd:
 266  * @xfer: The file transfer.
 267  *
 268  * Returns the socket file descriptor.
 269  *
 270  * Returns: The socket file descriptor.
 271  */
 272 int purple_xfer_get_fd(PurpleXfer *xfer);
 273
 274 /**
 275  * purple_xfer_get_watcher:
 276  * @xfer: The file transfer.
 277  *
 278  * Returns the Watcher for the transfer.
 279  *
 280  * Returns: The watcher.
 281  */
 282 int purple_xfer_get_watcher(PurpleXfer *xfer);
 283
 284 /**
 285  * purple_xfer_get_xfer_type:
 286  * @xfer: The file transfer.
 287  *
 288  * Returns the type of file transfer.
 289  *
 290  * Returns: The type of the file transfer.
 291  */
 292 PurpleXferType purple_xfer_get_xfer_type(PurpleXfer *xfer);
 293
 294 /**
 295  * purple_xfer_get_account:
 296  * @xfer: The file transfer.
 297  *
 298  * Returns the account the file transfer is using.
 299  *
 300  * Returns: (transfer none): The account.
 301  */
 302 PurpleAccount *purple_xfer_get_account(PurpleXfer *xfer);
 303
 304 /**
 305  * purple_xfer_set_remote_user:
 306  * @xfer: The file transfer.
 307  * @who:  The name of the remote user.
 308  *
 309  * Sets the name of the remote user.
 310  */
 311 void purple_xfer_set_remote_user(PurpleXfer *xfer, const char *who);
 312
 313 /**
 314  * purple_xfer_get_remote_user:
 315  * @xfer: The file transfer.
 316  *
 317  * Returns the name of the remote user.
 318  *
 319  * Returns: The name of the remote user.
 320  */
 321 const char *purple_xfer_get_remote_user(PurpleXfer *xfer);
 322
 323 /**
 324  * purple_xfer_get_status:
 325  * @xfer: The file transfer.
 326  *
 327  * Returns the status of the xfer.
 328  *
 329  * Returns: The status.
 330  */
 331 PurpleXferStatus purple_xfer_get_status(PurpleXfer *xfer);
 332
 333 /**
 334  * purple_xfer_is_cancelled:
 335  * @xfer: The file transfer.
 336  *
 337  * Returns true if the file transfer was cancelled.
 338  *
 339  * Returns: Whether or not the transfer was cancelled.
 340  */
 341 gboolean purple_xfer_is_cancelled(PurpleXfer *xfer);
 342
 343 /**
 344  * purple_xfer_is_completed:
 345  * @xfer: The file transfer.
 346  *
 347  * Returns the completed state for a file transfer.
 348  *
 349  * Returns: The completed state.
 350  */
 351 gboolean purple_xfer_is_completed(PurpleXfer *xfer);
 352
 353 /**
 354  * purple_xfer_get_filename:
 355  * @xfer: The file transfer.
 356  *
 357  * Returns the name of the file being sent or received.
 358  *
 359  * Returns: The filename.
 360  */
 361 const char *purple_xfer_get_filename(PurpleXfer *xfer);
 362
 363 /**
 364  * purple_xfer_get_local_filename:
 365  * @xfer: The file transfer.
 366  *
 367  * Returns the file's destination filename,
 368  *
 369  * Returns: The destination filename.
 370  */
 371 const char *purple_xfer_get_local_filename(PurpleXfer *xfer);
 372
 373 /**
 374  * purple_xfer_get_bytes_sent:
 375  * @xfer: The file transfer.
 376  *
 377  * Returns the number of bytes sent (or received) so far.
 378  *
 379  * Returns: The number of bytes sent.
 380  */
 381 goffset purple_xfer_get_bytes_sent(PurpleXfer *xfer);
 382
 383 /**
 384  * purple_xfer_get_bytes_remaining:
 385  * @xfer: The file transfer.
 386  *
 387  * Returns the number of bytes remaining to send or receive.
 388  *
 389  * Returns: The number of bytes remaining.
 390  */
 391 goffset purple_xfer_get_bytes_remaining(PurpleXfer *xfer);
 392
 393 /**
 394  * purple_xfer_get_size:
 395  * @xfer: The file transfer.
 396  *
 397  * Returns the size of the file being sent or received.
 398  *
 399  * Returns: The total size of the file.
 400  */
 401 goffset purple_xfer_get_size(PurpleXfer *xfer);
 402
 403 /**
 404  * purple_xfer_get_progress:
 405  * @xfer: The file transfer.
 406  *
 407  * Returns the current percentage of progress of the transfer.
 408  *
 409  * This is a number between 0 (0%) and 1 (100%).
 410  *
 411  * Returns: The percentage complete.
 412  */
 413 double purple_xfer_get_progress(PurpleXfer *xfer);
 414
 415 /**
 416  * purple_xfer_get_local_port:
 417  * @xfer: The file transfer.
 418  *
 419  * Returns the local port number in the file transfer.
 420  *
 421  * Returns: The port number on this end.
 422  */
 423 guint16 purple_xfer_get_local_port(PurpleXfer *xfer);
 424
 425 /**
 426  * purple_xfer_get_remote_ip:
 427  * @xfer: The file transfer.
 428  *
 429  * Returns the remote IP address in the file transfer.
 430  *
 431  * Returns: The IP address on the other end.
 432  */
 433 const char *purple_xfer_get_remote_ip(PurpleXfer *xfer);
 434
 435 /**
 436  * purple_xfer_get_remote_port:
 437  * @xfer: The file transfer.
 438  *
 439  * Returns the remote port number in the file transfer.
 440  *
 441  * Returns: The port number on the other end.
 442  */
 443 guint16 purple_xfer_get_remote_port(PurpleXfer *xfer);
 444
 445 /**
 446  * purple_xfer_get_start_time:
 447  * @xfer:  The file transfer.
 448  *
 449  * Returns the time the transfer of a file started.
 450  *
 451  * Returns: The monotonic time when the transfer started.
 452  */
 453 gint64 purple_xfer_get_start_time(PurpleXfer *xfer);
 454
 455 /**
 456  * purple_xfer_get_end_time:
 457  * @xfer:  The file transfer.
 458  *
 459  * Returns the time the transfer of a file ended.
 460  *
 461  * Returns: The monotonic time when the transfer ended.
 462  */
 463 gint64 purple_xfer_get_end_time(PurpleXfer *xfer);
 464
 465 /**
 466  * purple_xfer_set_fd:
 467  * @xfer:      The file transfer.
 468  * @fd:        The file descriptor.
 469  *
 470  * Sets the socket file descriptor.
 471  */
 472 void purple_xfer_set_fd(PurpleXfer *xfer, int fd);
 473
 474 /**
 475  * purple_xfer_set_watcher:
 476  * @xfer:      The file transfer.
 477  * @watcher:   The watcher.
 478  *
 479  * Sets the watcher for the file transfer.
 480  */
 481 void purple_xfer_set_watcher(PurpleXfer *xfer, int watcher);
 482
 483 /**
 484  * purple_xfer_set_completed:
 485  * @xfer:      The file transfer.
 486  * @completed: The completed state.
 487  *
 488  * Sets the completed state for the file transfer.
 489  */
 490 void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed);
 491
 492 /**
 493  * purple_xfer_set_status:
 494  * @xfer:      The file transfer.
 495  * @status:    The current status.
 496  *
 497  * Sets the current status for the file transfer.
 498  */
 499 void purple_xfer_set_status(PurpleXfer *xfer, PurpleXferStatus status);
 500
 501 /**
 502  * purple_xfer_set_message:
 503  * @xfer:     The file transfer.
 504  * @message: The message.
 505  *
 506  * Sets the message for the file transfer.
 507  */
 508 void purple_xfer_set_message(PurpleXfer *xfer, const char *message);
 509
 510 /**
 511  * purple_xfer_get_message:
 512  * @xfer:     The file transfer.
 513  *
 514  * Returns the message for the file transfer.
 515  *
 516  * Returns: The message.
 517  */
 518 const char *purple_xfer_get_message(PurpleXfer *xfer);
 519
 520 /**
 521  * purple_xfer_set_filename:
 522  * @xfer:     The file transfer.
 523  * @filename: The filename.
 524  *
 525  * Sets the filename for the file transfer.
 526  */
 527 void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename);
 528
 529 /**
 530  * purple_xfer_set_local_filename:
 531  * @xfer:     The file transfer.
 532  * @filename: The filename
 533  *
 534  * Sets the local filename for the file transfer.
 535  */
 536 void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename);
 537
 538 /**
 539  * purple_xfer_set_size:
 540  * @xfer: The file transfer.
 541  * @size: The size of the file.
 542  *
 543  * Sets the size of the file in a file transfer.
 544  */
 545 void purple_xfer_set_size(PurpleXfer *xfer, goffset size);
 546
 547 /**
 548  * purple_xfer_set_local_port:
 549  * @xfer:          The file transfer.
 550  * @local_port:    The local port.
 551  *
 552  * Sets the local port of the file transfer.
 553  */
 554 void purple_xfer_set_local_port(PurpleXfer *xfer, guint16 local_port);
 555
 556 /**
 557  * purple_xfer_set_bytes_sent:
 558  * @xfer:       The file transfer.
 559  * @bytes_sent: The new current position in the file.  If we're
 560  *                   sending a file then this is the next byte that we
 561  *                   will send.  If we're receiving a file, this is the
 562  *                   next byte that we expect to receive.
 563  *
 564  * Sets the current working position in the active file transfer.  This
 565  * can be used to jump backward in the file if the protocol detects
 566  * that some bit of data needs to be resent or has been sent twice.
 567  *
 568  * It's used for pausing and resuming an oscar file transfer.
 569  */
 570 void purple_xfer_set_bytes_sent(PurpleXfer *xfer, goffset bytes_sent);
 571
 572 /**
 573  * purple_xfer_get_ui_ops:
 574  * @xfer: The file transfer.
 575  *
 576  * Returns the UI operations structure for a file transfer.
 577  *
 578  * Returns: The UI operations structure.
 579  */
 580 PurpleXferUiOps *purple_xfer_get_ui_ops(PurpleXfer *xfer);
 581
 582 /**
 583  * purple_xfer_read:
 584  * @xfer:   The file transfer.
 585  * @buffer: The buffer that will be created to contain the data.
 586  *
 587  * Reads in data from a file transfer stream.
 588  *
 589  * Returns: The number of bytes read, or -1.
 590  */
 591 gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer);
 592
 593 /**
 594  * purple_xfer_write:
 595  * @xfer:   The file transfer.
 596  * @buffer: The buffer to read the data from.
 597  * @size:   The number of bytes to write.
 598  *
 599  * Writes data to a file transfer stream.
 600  *
 601  * Returns: The number of bytes written, or -1.
 602  */
 603 gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size);
 604
 605 /**
 606  * purple_xfer_write_file:
 607  * @xfer:   The file transfer.
 608  * @buffer: The buffer to read the data from.
 609  * @size:   The number of bytes to write.
 610  *
 611  * Writes chunk of received file.
 612  *
 613  * Returns: TRUE on success, FALSE otherwise.
 614  */
 615 gboolean
 616 purple_xfer_write_file(PurpleXfer *xfer, const guchar *buffer, gsize size);
 617
 618 /**
 619  * purple_xfer_read_file:
 620  * @xfer:   The file transfer.
 621  * @buffer: The buffer to write the data to.
 622  * @size:   The size of buffer.
 623  *
 624  * Writes chunk of file being sent.
 625  *
 626  * Returns: Number of bytes written (0 means, the device is busy), or -1 on
 627  *         failure.
 628  */
 629 gssize
 630 purple_xfer_read_file(PurpleXfer *xfer, guchar *buffer, gsize size);
 631
 632 /**
 633  * purple_xfer_start:
 634  * @xfer: The file transfer.
 635  * @fd:   The file descriptor for the socket.
 636  * @ip:   The IP address to connect to.
 637  * @port: The port to connect to.
 638  *
 639  * Starts a file transfer.
 640  *
 641  * Either @fd must be specified <emphasis>or</emphasis> @ip and @port on a
 642  * file receive transfer. On send, @fd must be specified, and
 643  * @ip and @port are ignored.
 644  *
 645  * Passing @fd as '-1' is a special-case and indicates to the
 646  * protocol to facilitate the file transfer itself.
 647  */
 648 void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip, guint16 port);
 649
 650 /**
 651  * purple_xfer_end:
 652  * @xfer: The file transfer.
 653  *
 654  * Ends a file transfer.
 655  */
 656 void purple_xfer_end(PurpleXfer *xfer);
 657
 658 /**
 659  * purple_xfer_add:
 660  * @xfer: The file transfer.
 661  *
 662  * Adds a new file transfer to the list of file transfers. Call this only
 663  * if you are not using purple_xfer_start.
 664  */
 665 void purple_xfer_add(PurpleXfer *xfer);
 666
 667 /**
 668  * purple_xfer_cancel_local:
 669  * @xfer: The file transfer.
 670  *
 671  * Cancels a file transfer on the local end.
 672  */
 673 void purple_xfer_cancel_local(PurpleXfer *xfer);
 674
 675 /**
 676  * purple_xfer_cancel_remote:
 677  * @xfer: The file transfer.
 678  *
 679  * Cancels a file transfer from the remote end.
 680  */
 681 void purple_xfer_cancel_remote(PurpleXfer *xfer);
 682
 683 /**
 684  * purple_xfer_error:
 685  * @type:    The type of file transfer.
 686  * @account: The account sending or receiving the file.
 687  * @who:     The user on the other end of the transfer.
 688  * @msg:     The message to display.
 689  *
 690  * Displays a file transfer-related error message.
 691  *
 692  * This is a wrapper around purple_notify_error(), which automatically
 693  * specifies a title ("File transfer to <literal>user</literal> failed" or
 694  * "File Transfer from <literal>user</literal> failed").
 695  */
 696 void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg);
 697
 698 /**
 699  * purple_xfer_update_progress:
 700  * @xfer:      The file transfer.
 701  *
 702  * Updates file transfer progress.
 703  */
 704 void purple_xfer_update_progress(PurpleXfer *xfer);
 705
 706 /**
 707  * purple_xfer_conversation_write:
 708  * @xfer: The file transfer to which this message relates.
 709  * @message: The message to display.
 710  * @is_error: Is this an error message?.
 711  *
 712  * Displays a file transfer-related message in the conversation window
 713  *
 714  * This is a wrapper around purple_conversation_write_system_message
 715  */
 716 void purple_xfer_conversation_write(PurpleXfer *xfer, const gchar *message, gboolean is_error);
 717
 718 /**
 719  * purple_xfer_ui_ready:
 720  * @xfer: The file transfer which is ready.
 721  *
 722  * Allows the UI to signal it's ready to send/receive data (depending on
 723  * the direction of the file transfer. Used when the UI is providing
 724  * read/write/data_not_sent UI ops.
 725  */
 726 void purple_xfer_ui_ready(PurpleXfer *xfer);
 727
 728 /**
 729  * purple_xfer_protocol_ready:
 730  * @xfer: The file transfer which is ready.
 731  *
 732  * Allows the protocol to signal it's ready to send/receive data (depending on
 733  * the direction of the file transfer. Used when the protocol provides read/write
 734  * ops and cannot/does not provide a raw fd to the core.
 735  */
 736 void purple_xfer_protocol_ready(PurpleXfer *xfer);
 737
 738 /**
 739  * purple_xfer_get_thumbnail:
 740  * @xfer: The file transfer to get the thumbnail for
 741  * @len:  If not %NULL, the length of the thumbnail data returned
 742  *             will be set in the location pointed to by this.
 743  *
 744  * Gets the thumbnail data for a transfer
 745  *
 746  * Returns: The thumbnail data, or NULL if there is no thumbnail
 747  */
 748 gconstpointer purple_xfer_get_thumbnail(PurpleXfer *xfer, gsize *len);
 749
 750 /**
 751  * purple_xfer_get_thumbnail_mimetype:
 752  * @xfer: The file transfer to get the mimetype for
 753  *
 754  * Gets the mimetype of the thumbnail preview for a transfer
 755  *
 756  * Returns: The mimetype of the thumbnail, or %NULL if not thumbnail is set
 757  */
 758 const gchar *purple_xfer_get_thumbnail_mimetype(PurpleXfer *xfer);
 759
 760
 761 /**
 762  * purple_xfer_set_thumbnail:
 763  * @xfer: The file transfer to set the data for
 764  * @thumbnail: A pointer to the thumbnail data, this will be copied
 765  * @size: The size in bytes of the passed in thumbnail data
 766  * @mimetype: The mimetype of the generated thumbnail
 767  *
 768  * Sets the thumbnail data for a transfer
 769  */
 770 void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail,
 771         gsize size, const gchar *mimetype);
 772
 773 /**
 774  * purple_xfer_prepare_thumbnail:
 775  * @xfer: The file transfer to create a thumbnail for
 776  * @formats: A comma-separated list of mimetypes for image formats
 777  *                the protocols can use for thumbnails.
 778  *
 779  * Prepare a thumbnail for a transfer (if the UI supports it)
 780  * will be no-op in case the UI doesn't implement thumbnail creation
 781  */
 782 void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats);
 783
 784 /**
 785  * purple_xfer_set_ui_data:
 786  * @xfer:                       The file transfer.
 787  * @ui_data:            A pointer to associate with this file transfer.
 788  *
 789  * Set the UI data associated with this file transfer.
 790  */
 791 void purple_xfer_set_ui_data(PurpleXfer *xfer, gpointer ui_data);
 792
 793 /**
 794  * purple_xfer_get_ui_data:
 795  * @xfer:                       The file transfer.
 796  *
 797  * Get the UI data associated with this file transfer.
 798  *
 799  * Returns: The UI data associated with this file transfer.  This is a
 800  *         convenience field provided to the UIs--it is not
 801  *         used by the libpurple core.
 802  */
 803 gpointer purple_xfer_get_ui_data(PurpleXfer *xfer);
 804
 805 /**************************************************************************/
 806 /* File Transfer Subsystem API                                            */
 807 /**************************************************************************/
 808
 809 /**
 810  * purple_xfer_ui_ops_get_type:
 811  *
 812  * Returns: The #GType for the #PurpleXferUiOps boxed structure.
 813  */
 814 GType purple_xfer_ui_ops_get_type(void);
 815
 816 /**
 817  * purple_xfers_get_all:
 818  *
 819  * Returns all xfers
 820  *
 821  * Returns: (element-type Purple.Xfer) (transfer none): all current xfers
 822  *          with refs
 823  */
 824 GList *purple_xfers_get_all(void);
 825
 826 /**
 827  * purple_xfers_get_handle:
 828  *
 829  * Returns the handle to the file transfer subsystem
 830  *
 831  * Returns: The handle
 832  */
 833 void *purple_xfers_get_handle(void);
 834
 835 /**
 836  * purple_xfers_init:
 837  *
 838  * Initializes the file transfer subsystem
 839  */
 840 void purple_xfers_init(void);
 841
 842 /**
 843  * purple_xfers_uninit:
 844  *
 845  * Uninitializes the file transfer subsystem
 846  */
 847 void purple_xfers_uninit(void);
 848
 849 /**
 850  * purple_xfers_set_ui_ops:
 851  * @ops: The UI operations structure.
 852  *
 853  * Sets the UI operations structure to be used in all purple file transfers.
 854  */
 855 void purple_xfers_set_ui_ops(PurpleXferUiOps *ops);
 856
 857 /**
 858  * purple_xfers_get_ui_ops:
 859  *
 860  * Returns the UI operations structure to be used in all purple file transfers.
 861  *
 862  * Returns: The UI operations structure.
 863  */
 864 PurpleXferUiOps *purple_xfers_get_ui_ops(void);
 865
 866 /******************************************************************************
 867  * Protocol Interface
 868  *****************************************************************************/
 869
 870 /**
 871  * purple_protocol_xfer_get_type:
 872  *
 873  * Returns: The #GType for the protocol xfer interface.
 874  */
 875 GType purple_protocol_xfer_get_type(void);
 876
 877 /**
 878  * purple_protocol_xfer_can_receive:
 879  * @prplxfer: The #PurpleProtocolXfer implementer instance
 880  * @connection: The #PurpleConnection that we're checking
 881  * @who: The user that we want to send a file transfer to.
 882  *
 883  * Checks whether or not we can transfer a file to @who.
 884  *
 885  * Returns: TRUE on success, FALSE otherwise.
 886  */
 887 gboolean purple_protocol_xfer_can_receive(PurpleProtocolXfer *prplxfer, PurpleConnection *connection, const gchar *who);
 888
 889 /**
 890  * purple_protocol_xfer_send_file:
 891  * @prplxfer: The #PurpleProtocolXfer implementer instance
 892  * @connection: The #PurpleConnection that we're checking
 893  * @who: The user that we want to set a file transfer to.
 894  * @filename: The name of the file to send.
 895  *
 896  * Sends @filename to @who.
 897  */
 898 void purple_protocol_xfer_send_file(PurpleProtocolXfer *prplxfer, PurpleConnection *connection, const gchar *who, const gchar *filename);
 899
 900 /**
 901  * purple_protocol_xfer_new_xfer:
 902  * @prplxfer: The #PurpleProtocolXfer implementer instance
 903  * @connection: The #PurpleConnection that we're checking
 904  * @who: The user that we want to send a file transfer to.
 905  *
 906  * Creates a new #PurpleXfer to @who.
 907  *
 908  * Returns: (transfer full): A new #PurpleXfer instance.
 909  */
 910 PurpleXfer *purple_protocol_xfer_new_xfer(PurpleProtocolXfer *prplxfer, PurpleConnection *connection, const gchar *who);
 911
 912 G_END_DECLS
 913
 914 #endif /* PURPLE_XFER_H */