source: protocols/ft.h @ e88fe7da

Last change on this file since e88fe7da was e88fe7da, checked in by Veres Lajos <vlajos@…>, at 2015-08-07T21:53:25Z

typofix - https://github.com/vlajos/misspell_fixer

  • Property mode set to 100644
File size: 5.7 KB
RevLine 
[2c2df7d]1/********************************************************************\
2* BitlBee -- An IRC to other IM-networks gateway                     *
3*                                                                    *
4* Copyright 2006 Marijn Kruisselbrink and others                     *
5\********************************************************************/
6
7/* Generic file transfer header                                     */
8
9/*
10  This program is free software; you can redistribute it and/or modify
11  it under the terms of the GNU General Public License as published by
12  the Free Software Foundation; either version 2 of the License, or
13  (at your option) any later version.
14
15  This program is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  GNU General Public License for more details.
19
20  You should have received a copy of the GNU General Public License with
21  the Debian GNU/Linux distribution in /usr/share/common-licenses/GPL;
[6f10697]22  if not, write to the Free Software Foundation, Inc., 51 Franklin St.,
23  Fifth Floor, Boston, MA  02110-1301  USA
[2c2df7d]24*/
25
26#ifndef _FT_H
27#define _FT_H
28
[dce3903]29/*
30 * One buffer is needed for each transfer. The receiver stores a message
31 * in it and gives it to the sender. The sender will stall the receiver
32 * till the buffer has been sent out.
33 */
34#define FT_BUFFER_SIZE 2048
35
[2c2df7d]36typedef enum {
[5ebff60]37        FT_STATUS_LISTENING     = 1,
38        FT_STATUS_TRANSFERRING  = 2,
39        FT_STATUS_FINISHED      = 4,
40        FT_STATUS_CANCELED      = 8,
41        FT_STATUS_CONNECTING    = 16
[2c2df7d]42} file_status_t;
43
44/*
45 * This structure holds all irc specific information regarding an incoming (from the point of view of
46 * the irc client) file transfer. New instances of this struct should only be created by calling the
47 * imcb_file_send_start() method, which will initialize most of the fields. The data field and the various
48 * methods are zero-initialized. Instances will automatically be deleted once the transfer is completed,
49 * canceled, or the connection to the irc client has been lost (note that also if only the irc connection
[506e61b]50 * and not the file transfer connection is lost, the file transfer will still be canceled and freed).
[2c2df7d]51 *
52 * The following (poor ascii-art) diagram illustrates what methods are called for which status-changes:
53 *
54 *                              /-----------\                    /----------\
55 *                     -------> | LISTENING | -----------------> | CANCELED |
56 *                              \-----------/  [canceled,]free   \----------/
57 *                                    |
58 *                                    | accept
59 *                                    V
[e88fe7da]60 *                     /------ /-------------\                    /--------------------------\
61 *         out_of_data |       | TRANSFERRING | -----------------> | TRANSFERRING | CANCELED |
62 *                     \-----> \-------------/  [canceled,]free   \--------------------------/
[2c2df7d]63 *                                    |
64 *                                    | finished,free
65 *                                    V
[e88fe7da]66 *                       /-------------------------\
67 *                       | TRANSFERRING | FINISHED |
68 *                       \-------------------------/
[2c2df7d]69 */
70typedef struct file_transfer {
[2ff2076]71
72        /* Are we sending something? */
73        int sending;
74
[2c2df7d]75        /*
76         * The current status of this file transfer.
[5ebff60]77         */
[2c2df7d]78        file_status_t status;
[5ebff60]79
[2c2df7d]80        /*
81         * file size
82         */
83        size_t file_size;
[5ebff60]84
[2c2df7d]85        /*
86         * Number of bytes that have been successfully transferred.
87         */
88        size_t bytes_transferred;
89
90        /*
91         * Time started. Used to calculate kb/s.
92         */
93        time_t started;
94
95        /*
96         * file name
97         */
98        char *file_name;
99
100        /*
101         * A unique local ID for this file transfer.
102         */
103        unsigned int local_id;
104
105        /*
106         * IM-protocol specific data associated with this file transfer.
107         */
108        gpointer data;
[9d4352c]109        struct im_connection *ic;
[5ebff60]110
[2c2df7d]111        /*
112         * Private data.
113         */
114        gpointer priv;
[5ebff60]115
[2c2df7d]116        /*
[e88fe7da]117         * If set, called after successful connection setup.
[2c2df7d]118         */
[5ebff60]119        void (*accept)(struct file_transfer *file);
120
[2c2df7d]121        /*
122         * If set, called when the transfer is canceled or finished.
123         * Subsequently, this structure will be freed.
124         *
125         */
[5ebff60]126        void (*free)(struct file_transfer *file);
127
[2c2df7d]128        /*
129         * If set, called when the transfer is finished and successful.
130         */
[5ebff60]131        void (*finished)(struct file_transfer *file);
132
[2c2df7d]133        /*
134         * If set, called when the transfer is canceled.
135         * ( canceled either by the transfer implementation or by
136         *  a call to imcb_file_canceled )
137         */
[5ebff60]138        void (*canceled)(struct file_transfer *file, char *reason);
139
[2c2df7d]140        /*
[dce3903]141         * called by the sending side to indicate that it is writable.
[5ebff60]142         * The callee should check if data is available and call the
[dce3903]143         * function(as seen below) if that is the case.
[2c2df7d]144         */
[5ebff60]145        gboolean (*write_request)(struct file_transfer *file);
[2c2df7d]146
[2ff2076]147        /*
148         * When sending files, protocols register this function to receive data.
[dce3903]149         * This should only be called once after write_request is called. The caller
150         * should not read more data until write_request is called again. This technique
151         * avoids buffering.
152         */
[5ebff60]153        gboolean (*write)(struct file_transfer *file, char *buffer, unsigned int len);
[dce3903]154
155        /* The send buffer associated with this transfer.
156         * Since receivers always wait for a write_request call one is enough.
[2ff2076]157         */
[dce3903]158        char buffer[FT_BUFFER_SIZE];
[2ff2076]159
[2c2df7d]160} file_transfer_t;
161
162/*
[506e61b]163 * This starts a file transfer from bitlbee to the user.
[2c2df7d]164 */
[5ebff60]165file_transfer_t *imcb_file_send_start(struct im_connection *ic, char *user_nick, char *file_name, size_t file_size);
[2c2df7d]166
167/*
168 * This should be called by a protocol when the transfer is canceled. Note that
169 * the canceled() and free() callbacks given in file will be called by this function.
170 */
[5ebff60]171void imcb_file_canceled(struct im_connection *ic, file_transfer_t *file, char *reason);
[2c2df7d]172
[5ebff60]173gboolean imcb_file_recv_start(struct im_connection *ic, file_transfer_t *ft);
[4ac647d]174
[5ebff60]175void imcb_file_finished(struct im_connection *ic, file_transfer_t *file);
[2c2df7d]176#endif
Note: See TracBrowser for help on using the repository browser.