source: protocols/ft.h @ 8240840

Last change on this file since 8240840 was 17a6ee9, checked in by Wilmer van der Gaast <wilmer@…>, at 2010-04-11T14:37:06Z

Including DCC stuff again, with a wonderful extra layer of abstraction.
Some hooks are missing so sending files doesn't work yet. Receiving also
still seems to have some issues. On the plus side, at least the MSN/Jabber
modules work again.
  • Property mode set to 100644
File size: 5.7 KB
Line 
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;
22  if not, write to the Free Software Foundation, Inc., 59 Temple Place,
23  Suite 330, Boston, MA  02111-1307  USA
24*/
25
26#ifndef _FT_H
27#define _FT_H
28
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
36typedef enum {
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
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
50 * and not the file transfer connection is lost, the file transfer will still be canceled and freed).
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
60 *                     /------ /-------------\                    /------------------------\
61 *         out_of_data |       | TRANSFERING | -----------------> | TRANSFERING | CANCELED |
62 *                     \-----> \-------------/  [canceled,]free   \------------------------/
63 *                                    |
64 *                                    | finished,free
65 *                                    V
66 *                       /------------------------\
67 *                       | TRANSFERING | FINISHED |
68 *                       \------------------------/
69 */
70typedef struct file_transfer {
71
72        /* Are we sending something? */
73        int sending;
74
75        /*
76         * The current status of this file transfer.
77         */ 
78        file_status_t status;
79       
80        /*
81         * file size
82         */
83        size_t file_size;
84       
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;
109       
110        /*
111         * Private data.
112         */
113        gpointer priv;
114       
115        /*
116         * If set, called after succesful connection setup.
117         */
118        void (*accept) ( struct file_transfer *file );
119       
120        /*
121         * If set, called when the transfer is canceled or finished.
122         * Subsequently, this structure will be freed.
123         *
124         */
125        void (*free) ( struct file_transfer *file );
126       
127        /*
128         * If set, called when the transfer is finished and successful.
129         */
130        void (*finished) ( struct file_transfer *file );
131       
132        /*
133         * If set, called when the transfer is canceled.
134         * ( canceled either by the transfer implementation or by
135         *  a call to imcb_file_canceled )
136         */
137        void (*canceled) ( struct file_transfer *file, char *reason );
138       
139        /*
140         * called by the sending side to indicate that it is writable.
141         * The callee should check if data is available and call the
142         * function(as seen below) if that is the case.
143         */
144        gboolean (*write_request) ( struct file_transfer *file );
145
146        /*
147         * When sending files, protocols register this function to receive data.
148         * This should only be called once after write_request is called. The caller
149         * should not read more data until write_request is called again. This technique
150         * avoids buffering.
151         */
152        gboolean (*write) (struct file_transfer *file, char *buffer, unsigned int len );
153
154        /* The send buffer associated with this transfer.
155         * Since receivers always wait for a write_request call one is enough.
156         */
157        char buffer[FT_BUFFER_SIZE];
158
159} file_transfer_t;
160
161/*
162 * This starts a file transfer from bitlbee to the user.
163 */
164file_transfer_t *imcb_file_send_start( struct im_connection *ic, char *user_nick, char *file_name, size_t file_size );
165
166/*
167 * This should be called by a protocol when the transfer is canceled. Note that
168 * the canceled() and free() callbacks given in file will be called by this function.
169 */
170void imcb_file_canceled( struct im_connection *ic, file_transfer_t *file, char *reason );
171
172gboolean imcb_file_recv_start( struct im_connection *ic, file_transfer_t *ft );
173
174void imcb_file_finished( struct im_connection *ic, file_transfer_t *file );
175#endif
Note: See TracBrowser for help on using the repository browser.