10969
|
1
|
|
2 /*
|
|
3 Meanwhile - Unofficial Lotus Sametime Community Client Library
|
|
4 Copyright (C) 2004 Christopher (siege) O'Brien
|
|
5
|
|
6 This library is free software; you can redistribute it and/or
|
|
7 modify it under the terms of the GNU Library General Public
|
|
8 License as published by the Free Software Foundation; either
|
|
9 version 2 of the License, or (at your option) any later version.
|
|
10
|
|
11 This library is distributed in the hope that it will be useful,
|
|
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
14 Library General Public License for more details.
|
|
15
|
|
16 You should have received a copy of the GNU Library General Public
|
|
17 License along with this library; if not, write to the Free
|
|
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
19 */
|
|
20
|
|
21
|
|
22 #ifndef _MW_SRVC_FT_H
|
|
23 #define _MW_SRVC_FT_H
|
|
24
|
|
25
|
|
26 #include "mw_common.h"
|
|
27
|
|
28
|
|
29 /** @file mw_srvc_ft.h
|
|
30
|
|
31 A file transfer is a simple way to get large chunks of binary data
|
|
32 from one client to another.
|
|
33 */
|
|
34
|
|
35
|
|
36 /** @struct mwServiceFileTransfer
|
|
37 File transfer service
|
|
38 */
|
|
39 struct mwServiceFileTransfer;
|
|
40
|
|
41
|
|
42 /** @struct mwFileTransfer
|
|
43 A single file trasfer session
|
|
44 */
|
|
45 struct mwFileTransfer;
|
|
46
|
|
47
|
|
48 #define mwService_FILE_TRANSFER 0x00000038
|
|
49
|
|
50
|
|
51 enum mwFileTransferState {
|
|
52 mwFileTransfer_NEW, /**< file transfer is not open */
|
|
53 mwFileTransfer_PENDING, /**< file transfer is opening */
|
|
54 mwFileTransfer_OPEN, /**< file transfer is open */
|
|
55 mwFileTransfer_CANCEL_LOCAL,
|
|
56 mwFileTransfer_CANCEL_REMOTE,
|
|
57 mwFileTransfer_DONE,
|
|
58 mwFileTransfer_ERROR, /**< error in file transfer */
|
|
59 mwFileTransfer_UNKNOWN, /**< unknown state */
|
|
60 };
|
|
61
|
|
62
|
|
63 #define mwFileTransfer_isState(ft, state) \
|
|
64 (mwFileTransfer_getState(ft) == (state))
|
|
65
|
|
66 #define mwFileTransfer_isNew(ft) \
|
|
67 mwFileTransfer_isState((ft), mwFileTransfer_NEW)
|
|
68
|
|
69 #define mwFileTransfer_isPending(ft) \
|
|
70 mwFileTransfer_isState((ft), mwFileTransfer_PENDING)
|
|
71
|
|
72 #define mwFileTransfer_isOpen(ft) \
|
|
73 mwFileTransfer_isState((ft), mwFileTransfer_OPEN)
|
|
74
|
|
75 #define mwFileTransfer_isDone(ft) \
|
|
76 mwFileTransfer_isState((ft), mwFileTransfer_DONE)
|
|
77
|
|
78 #define mwFileTransfer_isCancelLocal(ft) \
|
|
79 mwFileTransfer_isState((ft), mwFileTransfer_CANCEL_LOCAL)
|
|
80
|
|
81 #define mwFileTransfer_isCancelRemote(ft) \
|
|
82 mwFileTransfer_isState((ft), mwFileTransfer_CANCEL_REMOTE)
|
|
83
|
|
84
|
|
85 enum mwFileTranferCode {
|
|
86 mwFileTransfer_SUCCESS = 0x00000000,
|
|
87 mwFileTransfer_REJECTED = 0x08000606,
|
|
88 };
|
|
89
|
|
90
|
|
91 struct mwFileTransferHandler {
|
|
92
|
|
93 /** an incoming file transfer has been offered */
|
|
94 void (*ft_offered)(struct mwFileTransfer *ft);
|
|
95
|
|
96 /** a file transfer has been fully initiated */
|
|
97 void (*ft_opened)(struct mwFileTransfer *ft);
|
|
98
|
|
99 /** a file transfer has been closed. Check the status of the file
|
|
100 transfer to determine if the transfer was complete or if it had
|
|
101 been interrupted */
|
|
102 void (*ft_closed)(struct mwFileTransfer *ft, guint32 code);
|
|
103
|
|
104 /** receive a chunk of a file from an inbound file transfer. */
|
|
105 void (*ft_recv)(struct mwFileTransfer *ft, struct mwOpaque *data);
|
|
106
|
|
107 /** received an ack for a sent chunk on an outbound file transfer.
|
|
108 this indicates that a previous call to mwFileTransfer_send has
|
|
109 reached the target and that the target has responded. */
|
|
110 void (*ft_ack)(struct mwFileTransfer *ft);
|
|
111
|
|
112 /** optional. called from mwService_free */
|
|
113 void (*clear)(struct mwServiceFileTransfer *srvc);
|
|
114 };
|
|
115
|
|
116
|
|
117 struct mwServiceFileTransfer *
|
|
118 mwServiceFileTransfer_new(struct mwSession *session,
|
|
119 struct mwFileTransferHandler *handler);
|
|
120
|
|
121
|
|
122 struct mwFileTransferHandler *
|
|
123 mwServiceFileTransfer_getHandler(struct mwServiceFileTransfer *srvc);
|
|
124
|
|
125
|
|
126 struct mwFileTransfer *
|
|
127 mwFileTransfer_new(struct mwServiceFileTransfer *srvc,
|
|
128 const struct mwIdBlock *who, const char *msg,
|
|
129 const char *filename, guint32 filesize);
|
|
130
|
|
131
|
|
132 /** deallocate a file transfer. will call mwFileTransfer_close if
|
|
133 necessary */
|
|
134 void
|
|
135 mwFileTransfer_free(struct mwFileTransfer *ft);
|
|
136
|
|
137
|
|
138 /** the status of this file transfer */
|
|
139 enum mwFileTransferState
|
|
140 mwFileTransfer_getState(struct mwFileTransfer *ft);
|
|
141
|
|
142
|
|
143 struct mwServiceFileTransfer *
|
|
144 mwFileTransfer_getService(struct mwFileTransfer *ft);
|
|
145
|
|
146
|
|
147 /** the user on the other end of the file transfer */
|
|
148 const struct mwIdBlock *
|
|
149 mwFileTransfer_getUser(struct mwFileTransfer *ft);
|
|
150
|
|
151
|
|
152 /** the message sent along with an offered file transfer */
|
|
153 const char *
|
|
154 mwFileTransfer_getMessage(struct mwFileTransfer *ft);
|
|
155
|
|
156
|
|
157 /** the publicized file name. Not necessarily related to any actual
|
|
158 file on either system */
|
|
159 const char *
|
|
160 mwFileTransfer_getFileName(struct mwFileTransfer *ft);
|
|
161
|
|
162
|
|
163 /** total bytes intended to be sent/received */
|
|
164 guint32 mwFileTransfer_getFileSize(struct mwFileTransfer *ft);
|
|
165
|
|
166
|
|
167 /** bytes remaining to be received/send */
|
|
168 guint32 mwFileTransfer_getRemaining(struct mwFileTransfer *ft);
|
|
169
|
|
170
|
|
171 /** count of bytes sent/received over this file transfer so far */
|
|
172 #define mwFileTransfer_getSent(ft) \
|
|
173 (mwFileTransfer_getFileSize(ft) - mwFileTransfer_getRemaining(ft))
|
|
174
|
|
175
|
|
176 /** initiate an outgoing file transfer */
|
|
177 int mwFileTransfer_offer(struct mwFileTransfer *ft);
|
|
178
|
|
179
|
|
180 /** accept an incoming file transfer */
|
|
181 int mwFileTransfer_accept(struct mwFileTransfer *ft);
|
|
182
|
|
183
|
|
184 /** reject an incoming file transfer */
|
|
185 #define mwFileTransfer_reject(ft) \
|
|
186 mwFileTransfer_close((ft), mwFileTransfer_REJECTED)
|
|
187
|
|
188
|
|
189 /** cancel an open file transfer */
|
|
190 #define mwFileTransfer_cancel(ft) \
|
|
191 mwFileTransfer_close((ft), mwFileTransfer_SUCCESS);
|
|
192
|
|
193
|
|
194 /** Close a file transfer. This will trigger the ft_close function of the
|
|
195 session's handler.
|
|
196
|
|
197 @relates mwFileTransfer_reject
|
|
198 @relates mwFileTransfer_cancel
|
|
199 */
|
|
200 int mwFileTransfer_close(struct mwFileTransfer *ft, guint32 code);
|
|
201
|
|
202
|
|
203 /** send a chunk of data over an outbound file transfer. The client at
|
|
204 the other end of the transfer should respond with an acknowledgement
|
|
205 message, which can be caught in the service's handler.
|
|
206
|
|
207 @relates mwFileTransferHandler::ft_ack
|
|
208 */
|
|
209 int mwFileTransfer_send(struct mwFileTransfer *ft,
|
|
210 struct mwOpaque *data);
|
|
211
|
|
212
|
|
213 /** acknowledge the receipt of a chunk of data from an inbound file
|
|
214 transfer. This should be done after every received chunk, or the
|
|
215 transfer will stall. However, not all clients will wait for an ack
|
|
216 after sending a chunk before sending the next chunk, so it is
|
|
217 possible to have the handler's ft_recv function triggered again
|
|
218 even if no ack was sent.
|
|
219
|
|
220 @relates mwFileTransferHandler::ft_recv
|
|
221 */
|
|
222 int mwFileTransfer_ack(struct mwFileTransfer *ft);
|
|
223
|
|
224
|
|
225 void mwFileTransfer_setClientData(struct mwFileTransfer *ft,
|
|
226 gpointer data, GDestroyNotify clean);
|
|
227
|
|
228
|
|
229 gpointer mwFileTransfer_getClientData(struct mwFileTransfer *ft);
|
|
230
|
|
231
|
|
232 void mwFileTransfer_removeClientData(struct mwFileTransfer *ft);
|
|
233
|
|
234
|
|
235 #endif
|