Mercurial > pidgin3 / file comparison

comparison: src/ft.h

src/ft.h

changeset 14253
b63ebf84c42b
parent 14252
d10dda2777a9
child 14254
77edc7a6191a
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
1 /**
2 * @file ft.h File Transfer API
3 * @ingroup core
4 *
5 * gaim
6 *
7 * Gaim is the legal property of its developers, whose names are too numerous
8 * to list here. Please refer to the COPYRIGHT file distributed with this
9 * source distribution.
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 */
25 #ifndef _GAIM_FT_H_
26 #define _GAIM_FT_H_
27
28 /**************************************************************************/
29 /** Data Structures */
30 /**************************************************************************/
31 typedef struct _GaimXfer GaimXfer;
32
33 #include <glib.h>
34 #include <stdio.h>
35
36 #include "account.h"
37
38 /**
39 * Types of file transfers.
40 */
41 typedef enum
42 {
43 GAIM_XFER_UNKNOWN = 0, /**< Unknown file transfer type. */
44 GAIM_XFER_SEND, /**< File sending. */
45 GAIM_XFER_RECEIVE /**< File receiving. */
46
47 } GaimXferType;
48
49 /**
50 * The different states of the xfer.
51 */
52 typedef enum
53 {
54 GAIM_XFER_STATUS_UNKNOWN = 0, /**< Unknown, the xfer may be null. */
55 GAIM_XFER_STATUS_NOT_STARTED, /**< It hasn't started yet. */
56 GAIM_XFER_STATUS_ACCEPTED, /**< Receive accepted, but destination file not selected yet */
57 GAIM_XFER_STATUS_STARTED, /**< gaim_xfer_start has been called. */
58 GAIM_XFER_STATUS_DONE, /**< The xfer completed successfully. */
59 GAIM_XFER_STATUS_CANCEL_LOCAL, /**< The xfer was canceled by us. */
60 GAIM_XFER_STATUS_CANCEL_REMOTE /**< The xfer was canceled by the other end, or we couldn't connect. */
61 } GaimXferStatusType;
62
63 /**
64 * File transfer UI operations.
65 *
66 * Any UI representing a file transfer must assign a filled-out
67 * GaimXferUiOps structure to the gaim_xfer.
68 */
69 typedef struct
70 {
71 void (*new_xfer)(GaimXfer *xfer);
72 void (*destroy)(GaimXfer *xfer);
73 void (*add_xfer)(GaimXfer *xfer);
74 void (*update_progress)(GaimXfer *xfer, double percent);
75 void (*cancel_local)(GaimXfer *xfer);
76 void (*cancel_remote)(GaimXfer *xfer);
77
78 } GaimXferUiOps;
79
80 /**
81 * A core representation of a file transfer.
82 */
83 struct _GaimXfer
84 {
85 guint ref; /**< The reference count. */
86 GaimXferType type; /**< The type of transfer. */
87
88 GaimAccount *account; /**< The account. */
89
90 char *who; /**< The person on the other end of the
91 transfer. */
92
93 char *message; /**< A message sent with the request */
94 char *filename; /**< The name sent over the network. */
95 char *local_filename; /**< The name on the local hard drive. */
96 size_t size; /**< The size of the file. */
97
98 FILE *dest_fp; /**< The destination file pointer. */
99
100 char *remote_ip; /**< The remote IP address. */
101 int local_port; /**< The local port. */
102 int remote_port; /**< The remote port. */
103
104 int fd; /**< The socket file descriptor. */
105 int watcher; /**< Watcher. */
106
107 size_t bytes_sent; /**< The number of bytes sent. */
108 size_t bytes_remaining; /**< The number of bytes remaining. */
109 time_t start_time; /**< When the transfer of data began. */
110 time_t end_time; /**< When the transfer of data ended. */
111
112 GaimXferStatusType status; /**< File Transfer's status. */
113
114 /* I/O operations. */
115 struct
116 {
117 void (*init)(GaimXfer *xfer);
118 void (*request_denied)(GaimXfer *xfer);
119 void (*start)(GaimXfer *xfer);
120 void (*end)(GaimXfer *xfer);
121 void (*cancel_send)(GaimXfer *xfer);
122 void (*cancel_recv)(GaimXfer *xfer);
123 gssize (*read)(guchar **buffer, GaimXfer *xfer);
124 gssize (*write)(const guchar *buffer, size_t size, GaimXfer *xfer);
125 void (*ack)(GaimXfer *xfer, const guchar *buffer, size_t size);
126
127 } ops;
128
129 GaimXferUiOps *ui_ops; /**< UI-specific operations. */
130 void *ui_data; /**< UI-specific data. */
131
132 void *data; /**< prpl-specific data. */
133 };
134
135 #ifdef __cplusplus
136 extern "C" {
137 #endif
138
139 /**************************************************************************/
140 /** @name File Transfer API */
141 /**************************************************************************/
142 /*@{*/
143
144 /**
145 * Creates a new file transfer handle.
146 * This is called by prpls.
147 * The handle starts with a ref count of 1, and this reference
148 * is owned by the core. The prpl normally does not need to
149 * gaim_xfer_ref or unref.
150 *
151 * @param account The account sending or receiving the file.
152 * @param type The type of file transfer.
153 * @param who The name of the remote user.
154 *
155 * @return A file transfer handle.
156 */
157 GaimXfer *gaim_xfer_new(GaimAccount *account,
158 GaimXferType type, const char *who);
159
160 /**
161 * Increases the reference count on a GaimXfer.
162 * Please call gaim_xfer_unref later.
163 *
164 * @param xfer A file transfer handle.
165 */
166 void gaim_xfer_ref(GaimXfer *xfer);
167
168 /**
169 * Decreases the reference count on a GaimXfer.
170 * If the reference reaches 0, gaim_xfer_destroy (an internal function)
171 * will destroy the xfer. It calls the ui destroy cb first.
172 * Since the core keeps a ref on the xfer, only an erroneous call to
173 * this function will destroy the xfer while still in use.
174 *
175 * @param xfer A file transfer handle.
176 */
177 void gaim_xfer_unref(GaimXfer *xfer);
178
179 /**
180 * Requests confirmation for a file transfer from the user. If receiving
181 * a file which is known at this point, this requests user to accept and
182 * save the file. If the filename is unknown (not set) this only requests user
183 * to accept the file transfer. In this case protocol must call this function
184 * again once the filename is available.
185 *
186 * @param xfer The file transfer to request confirmation on.
187 */
188 void gaim_xfer_request(GaimXfer *xfer);
189
190 /**
191 * Called if the user accepts the file transfer request.
192 *
193 * @param xfer The file transfer.
194 * @param filename The filename.
195 */
196 void gaim_xfer_request_accepted(GaimXfer *xfer, const char *filename);
197
198 /**
199 * Called if the user rejects the file transfer request.
200 *
201 * @param xfer The file transfer.
202 */
203 void gaim_xfer_request_denied(GaimXfer *xfer);
204
205 /**
206 * Returns the type of file transfer.
207 *
208 * @param xfer The file transfer.
209 *
210 * @return The type of the file transfer.
211 */
212 GaimXferType gaim_xfer_get_type(const GaimXfer *xfer);
213
214 /**
215 * Returns the account the file transfer is using.
216 *
217 * @param xfer The file transfer.
218 *
219 * @return The account.
220 */
221 GaimAccount *gaim_xfer_get_account(const GaimXfer *xfer);
222
223 /**
224 * Returns the status of the xfer.
225 *
226 * @param xfer The file transfer.
227 *
228 * @return The status.
229 */
230 GaimXferStatusType gaim_xfer_get_status(const GaimXfer *xfer);
231
232 /**
233 * Returns true if the file transfer was canceled.
234 *
235 * @param xfer The file transfer.
236 *
237 * @return Whether or not the transfer was canceled.
238 */
239 gboolean gaim_xfer_is_canceled(const GaimXfer *xfer);
240
241 /**
242 * Returns the completed state for a file transfer.
243 *
244 * @param xfer The file transfer.
245 *
246 * @return The completed state.
247 */
248 gboolean gaim_xfer_is_completed(const GaimXfer *xfer);
249
250 /**
251 * Returns the name of the file being sent or received.
252 *
253 * @param xfer The file transfer.
254 *
255 * @return The filename.
256 */
257 const char *gaim_xfer_get_filename(const GaimXfer *xfer);
258
259 /**
260 * Returns the file's destination filename,
261 *
262 * @param xfer The file transfer.
263 *
264 * @return The destination filename.
265 */
266 const char *gaim_xfer_get_local_filename(const GaimXfer *xfer);
267
268 /**
269 * Returns the number of bytes sent (or received) so far.
270 *
271 * @param xfer The file transfer.
272 *
273 * @return The number of bytes sent.
274 */
275 size_t gaim_xfer_get_bytes_sent(const GaimXfer *xfer);
276
277 /**
278 * Returns the number of bytes remaining to send or receive.
279 *
280 * @param xfer The file transfer.
281 *
282 * @return The number of bytes remaining.
283 */
284 size_t gaim_xfer_get_bytes_remaining(const GaimXfer *xfer);
285
286 /**
287 * Returns the size of the file being sent or received.
288 *
289 * @param xfer The file transfer.
290 *
291 * @return The total size of the file.
292 */
293 size_t gaim_xfer_get_size(const GaimXfer *xfer);
294
295 /**
296 * Returns the current percentage of progress of the transfer.
297 *
298 * This is a number between 0 (0%) and 1 (100%).
299 *
300 * @param xfer The file transfer.
301 *
302 * @return The percentage complete.
303 */
304 double gaim_xfer_get_progress(const GaimXfer *xfer);
305
306 /**
307 * Returns the local port number in the file transfer.
308 *
309 * @param xfer The file transfer.
310 *
311 * @return The port number on this end.
312 */
313 unsigned int gaim_xfer_get_local_port(const GaimXfer *xfer);
314
315 /**
316 * Returns the remote IP address in the file transfer.
317 *
318 * @param xfer The file transfer.
319 *
320 * @return The IP address on the other end.
321 */
322 const char *gaim_xfer_get_remote_ip(const GaimXfer *xfer);
323
324 /**
325 * Returns the remote port number in the file transfer.
326 *
327 * @param xfer The file transfer.
328 *
329 * @return The port number on the other end.
330 */
331 unsigned int gaim_xfer_get_remote_port(const GaimXfer *xfer);
332
333 /**
334 * Sets the completed state for the file transfer.
335 *
336 * @param xfer The file transfer.
337 * @param completed The completed state.
338 */
339 void gaim_xfer_set_completed(GaimXfer *xfer, gboolean completed);
340
341 /**
342 * Sets the filename for the file transfer.
343 *
344 * @param xfer The file transfer.
345 * @param message The message.
346 */
347 void gaim_xfer_set_message(GaimXfer *xfer, const char *message);
348
349 /**
350 * Sets the filename for the file transfer.
351 *
352 * @param xfer The file transfer.
353 * @param filename The filename.
354 */
355 void gaim_xfer_set_filename(GaimXfer *xfer, const char *filename);
356
357 /**
358 * Sets the local filename for the file transfer.
359 *
360 * @param xfer The file transfer.
361 * @param filename The filename
362 */
363 void gaim_xfer_set_local_filename(GaimXfer *xfer, const char *filename);
364
365 /**
366 * Sets the size of the file in a file transfer.
367 *
368 * @param xfer The file transfer.
369 * @param size The size of the file.
370 */
371 void gaim_xfer_set_size(GaimXfer *xfer, size_t size);
372
373 /**
374 * Returns the UI operations structure for a file transfer.
375 *
376 * @param xfer The file transfer.
377 *
378 * @return The UI operations structure.
379 */
380 GaimXferUiOps *gaim_xfer_get_ui_ops(const GaimXfer *xfer);
381
382 /**
383 * Sets the read function for the file transfer.
384 *
385 * @param xfer The file transfer.
386 * @param fnc The read function.
387 */
388 void gaim_xfer_set_read_fnc(GaimXfer *xfer,
389 gssize (*fnc)(guchar **, GaimXfer *));
390
391 /**
392 * Sets the write function for the file transfer.
393 *
394 * @param xfer The file transfer.
395 * @param fnc The write function.
396 */
397 void gaim_xfer_set_write_fnc(GaimXfer *xfer,
398 gssize (*fnc)(const guchar *, size_t, GaimXfer *));
399
400 /**
401 * Sets the acknowledge function for the file transfer.
402 *
403 * @param xfer The file transfer.
404 * @param fnc The acknowledge function.
405 */
406 void gaim_xfer_set_ack_fnc(GaimXfer *xfer,
407 void (*fnc)(GaimXfer *, const guchar *, size_t));
408
409 /**
410 * Sets the function to be called if the request is denied.
411 *
412 * @param xfer The file transfer.
413 * @param fnc The request denied prpl callback.
414 */
415 void gaim_xfer_set_request_denied_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
416
417 /**
418 * Sets the transfer initialization function for the file transfer.
419 *
420 * This function is required, and must call gaim_xfer_start() with
421 * the necessary parameters. This will be called if the file transfer
422 * is accepted by the user.
423 *
424 * @param xfer The file transfer.
425 * @param fnc The transfer initialization function.
426 */
427 void gaim_xfer_set_init_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
428
429 /**
430 * Sets the start transfer function for the file transfer.
431 *
432 * @param xfer The file transfer.
433 * @param fnc The start transfer function.
434 */
435 void gaim_xfer_set_start_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
436
437 /**
438 * Sets the end transfer function for the file transfer.
439 *
440 * @param xfer The file transfer.
441 * @param fnc The end transfer function.
442 */
443 void gaim_xfer_set_end_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
444
445 /**
446 * Sets the cancel send function for the file transfer.
447 *
448 * @param xfer The file transfer.
449 * @param fnc The cancel send function.
450 */
451 void gaim_xfer_set_cancel_send_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
452
453 /**
454 * Sets the cancel receive function for the file transfer.
455 *
456 * @param xfer The file transfer.
457 * @param fnc The cancel receive function.
458 */
459 void gaim_xfer_set_cancel_recv_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
460
461 /**
462 * Reads in data from a file transfer stream.
463 *
464 * @param xfer The file transfer.
465 * @param buffer The buffer that will be created to contain the data.
466 *
467 * @return The number of bytes read, or -1.
468 */
469 gssize gaim_xfer_read(GaimXfer *xfer, guchar **buffer);
470
471 /**
472 * Writes data to a file transfer stream.
473 *
474 * @param xfer The file transfer.
475 * @param buffer The buffer to read the data from.
476 * @param size The number of bytes to write.
477 *
478 * @return The number of bytes written, or -1.
479 */
480 gssize gaim_xfer_write(GaimXfer *xfer, const guchar *buffer, gsize size);
481
482 /**
483 * Starts a file transfer.
484 *
485 * Either @a fd must be specified <i>or</i> @a ip and @a port on a
486 * file receive transfer. On send, @a fd must be specified, and
487 * @a ip and @a port are ignored.
488 *
489 * @param xfer The file transfer.
490 * @param fd The file descriptor for the socket.
491 * @param ip The IP address to connect to.
492 * @param port The port to connect to.
493 */
494 void gaim_xfer_start(GaimXfer *xfer, int fd, const char *ip,
495 unsigned int port);
496
497 /**
498 * Ends a file transfer.
499 *
500 * @param xfer The file transfer.
501 */
502 void gaim_xfer_end(GaimXfer *xfer);
503
504 /**
505 * Adds a new file transfer to the list of file transfers. Call this only
506 * if you are not using gaim_xfer_start.
507 *
508 * @param xfer The file transfer.
509 */
510 void gaim_xfer_add(GaimXfer *xfer);
511
512 /**
513 * Cancels a file transfer on the local end.
514 *
515 * @param xfer The file transfer.
516 */
517 void gaim_xfer_cancel_local(GaimXfer *xfer);
518
519 /**
520 * Cancels a file transfer from the remote end.
521 *
522 * @param xfer The file transfer.
523 */
524 void gaim_xfer_cancel_remote(GaimXfer *xfer);
525
526 /**
527 * Displays a file transfer-related error message.
528 *
529 * This is a wrapper around gaim_notify_error(), which automatically
530 * specifies a title ("File transfer to <i>user</i> failed" or
531 * "File Transfer from <i>user</i> failed").
532 *
533 * @param type The type of file transfer.
534 * @param account The account sending or receiving the file.
535 * @param who The user on the other end of the transfer.
536 * @param msg The message to display.
537 */
538 void gaim_xfer_error(GaimXferType type, GaimAccount *account, const char *who, const char *msg);
539
540 /**
541 * Updates file transfer progress.
542 *
543 * @param xfer The file transfer.
544 */
545 void gaim_xfer_update_progress(GaimXfer *xfer);
546
547 /**
548 * Displays a file transfer-related message in the conversation window
549 *
550 * This is a wrapper around gaim_conversation_write
551 *
552 * @param xfer The file transfer to which this message relates.
553 * @param message The message to display.
554 * @param is_error Is this an error message?.
555 */
556 void gaim_xfer_conversation_write(GaimXfer *xfer, char *message, gboolean is_error);
557
558 /*@}*/
559
560 /**************************************************************************/
561 /** @name UI Registration Functions */
562 /**************************************************************************/
563 /*@{*/
564
565 /**
566 * Returns the handle to the file transfer subsystem
567 *
568 * @return The handle
569 */
570 void *gaim_xfers_get_handle(void);
571
572 /**
573 * Initializes the file transfer subsystem
574 */
575 void gaim_xfers_init(void);
576
577 /**
578 * Uninitializes the file transfer subsystem
579 */
580 void gaim_xfers_uninit(void);
581
582 /**
583 * Sets the UI operations structure to be used in all gaim file transfers.
584 *
585 * @param ops The UI operations structure.
586 */
587 void gaim_xfers_set_ui_ops(GaimXferUiOps *ops);
588
589 /**
590 * Returns the UI operations structure to be used in all gaim file transfers.
591 *
592 * @return The UI operations structure.
593 */
594 GaimXferUiOps *gaim_xfers_get_ui_ops(void);
595
596 /*@}*/
597
598 #ifdef __cplusplus
599 }
600 #endif
601
602 #endif /* _GAIM_FT_H_ */

Mercurial Repository: pidgin3

mercurial