Mercurial > pidgin3 / file comparison

comparison: libpurple/xfer.h

libpurple/xfer.h

branch
soc.2013.gobjectification.plugins
changeset 37023
d9bcdc9a91e6
parent 37021
04c99b24db84
child 37034
9d6765962b22
equal deleted inserted replaced
37022:d891503c8aa6 37023:d9bcdc9a91e6
89 89
90 /** 90 /**
91 * UI op to write data received from the protocol. The UI must deal with the 91 * UI op to write data received from the protocol. The UI must deal with the
92 * entire buffer and return size, or it is treated as an error. 92 * entire buffer and return size, or it is treated as an error.
93 * 93 *
94 * @xfer: The file transfer structure 94 * @param xfer The file transfer structure
95 * @buffer: The buffer to write 95 * @param buffer The buffer to write
96 * @size: The size of the buffer 96 * @param size The size of the buffer
97 * 97 *
98 * Returns: size if the write was successful, or a value between 0 and 98 * @return size if the write was successful, or a value between 0 and
99 * size on error. 99 * size on error.
100 */ 100 */
101 gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size); 101 gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size);
102 102
103 /** 103 /**
104 * UI op to read data to send to the protocol for a file transfer. 104 * UI op to read data to send to the protocol for a file transfer.
105 * 105 *
106 * @xfer: The file transfer structure 106 * @param xfer The file transfer structure
107 * @buffer: A pointer to a buffer. The UI must allocate this buffer. 107 * @param buffer A pointer to a buffer. The UI must allocate this buffer.
108 * libpurple will free the data. 108 * libpurple will free the data.
109 * @size: The maximum amount of data to put in the buffer. 109 * @param size The maximum amount of data to put in the buffer.
110 * 110 *
111 * Returns:s The amount of data in the buffer, 0 if nothing is available, 111 * @returns The amount of data in the buffer, 0 if nothing is available,
112 * and a negative value if an error occurred and the transfer 112 * and a negative value if an error occurred and the transfer
113 * should be cancelled (libpurple will cancel). 113 * should be cancelled (libpurple will cancel).
114 */ 114 */
115 gssize (*ui_read)(PurpleXfer *xfer, guchar **buffer, gssize size); 115 gssize (*ui_read)(PurpleXfer *xfer, guchar **buffer, gssize size);
116 116
118 * Op to notify the UI that not all the data read in was written. The UI 118 * Op to notify the UI that not all the data read in was written. The UI
119 * should re-enqueue this data and return it the next time read is called. 119 * should re-enqueue this data and return it the next time read is called.
120 * 120 *
121 * This MUST be implemented if read and write are implemented. 121 * This MUST be implemented if read and write are implemented.
122 * 122 *
123 * @xfer: The file transfer structure 123 * @param xfer The file transfer structure
124 * @buffer: A pointer to the beginning of the unwritten data. 124 * @param buffer A pointer to the beginning of the unwritten data.
125 * @size: The amount of unwritten data. 125 * @param size The amount of unwritten data.
126 */ 126 */
127 void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size); 127 void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size);
128 128
129 /** 129 /**
130 * Op to create a thumbnail image for a file transfer 130 * Op to create a thumbnail image for a file transfer
131 * 131 *
132 * @xfer: The file transfer structure 132 * @param xfer The file transfer structure
133 */ 133 */
134 void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats); 134 void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats);
135 } PurpleXferUiOps; 135 } PurpleXferUiOps;
136 136
137 /** 137 /**
173 173
174 /** 174 /**
175 * Creates a new file transfer handle. 175 * Creates a new file transfer handle.
176 * This is called by protocols. 176 * This is called by protocols.
177 * 177 *
178 * @account: The account sending or receiving the file. 178 * @param account The account sending or receiving the file.
179 * @type: The type of file transfer. 179 * @param type The type of file transfer.
180 * @who: The name of the remote user. 180 * @param who The name of the remote user.
181 * 181 *
182 * Returns: A file transfer handle. 182 * @return A file transfer handle.
183 */ 183 */
184 PurpleXfer *purple_xfer_new(PurpleAccount *account, 184 PurpleXfer *purple_xfer_new(PurpleAccount *account,
185 PurpleXferType type, const char *who); 185 PurpleXferType type, const char *who);
186 186
187 /** 187 /**
189 * a file which is known at this point, this requests user to accept and 189 * a file which is known at this point, this requests user to accept and
190 * save the file. If the filename is unknown (not set) this only requests user 190 * save the file. If the filename is unknown (not set) this only requests user
191 * to accept the file transfer. In this case protocol must call this function 191 * to accept the file transfer. In this case protocol must call this function
192 * again once the filename is available. 192 * again once the filename is available.
193 * 193 *
194 * @xfer: The file transfer to request confirmation on. 194 * @param xfer The file transfer to request confirmation on.
195 */ 195 */
196 void purple_xfer_request(PurpleXfer *xfer); 196 void purple_xfer_request(PurpleXfer *xfer);
197 197
198 /** 198 /**
199 * Called if the user accepts the file transfer request. 199 * Called if the user accepts the file transfer request.
200 * 200 *
201 * @xfer: The file transfer. 201 * @param xfer The file transfer.
202 * @filename: The filename. 202 * @param filename The filename.
203 */ 203 */
204 void purple_xfer_request_accepted(PurpleXfer *xfer, const char *filename); 204 void purple_xfer_request_accepted(PurpleXfer *xfer, const char *filename);
205 205
206 /** 206 /**
207 * Called if the user rejects the file transfer request. 207 * Called if the user rejects the file transfer request.
208 * 208 *
209 * @xfer: The file transfer. 209 * @param xfer The file transfer.
210 */ 210 */
211 void purple_xfer_request_denied(PurpleXfer *xfer); 211 void purple_xfer_request_denied(PurpleXfer *xfer);
212 212
213 /** 213 /**
214 * Returns the socket file descriptor. 214 * Returns the socket file descriptor.
215 * 215 *
216 * @xfer: The file transfer. 216 * @param xfer The file transfer.
217 * 217 *
218 * Returns: The socket file descriptor. 218 * @return The socket file descriptor.
219 */ 219 */
220 int purple_xfer_get_fd(PurpleXfer *xfer); 220 int purple_xfer_get_fd(PurpleXfer *xfer);
221 221
222 /** 222 /**
223 * Returns the Watcher for the transfer. 223 * Returns the Watcher for the transfer.
224 * 224 *
225 * @xfer: The file transfer. 225 * @param xfer The file transfer.
226 * 226 *
227 * Returns: The watcher. 227 * @return The watcher.
228 */ 228 */
229 int purple_xfer_get_watcher(PurpleXfer *xfer); 229 int purple_xfer_get_watcher(PurpleXfer *xfer);
230 230
231 /** 231 /**
232 * Returns the type of file transfer. 232 * Returns the type of file transfer.
233 * 233 *
234 * @xfer: The file transfer. 234 * @param xfer The file transfer.
235 * 235 *
236 * Returns: The type of the file transfer. 236 * @return The type of the file transfer.
237 */ 237 */
238 PurpleXferType purple_xfer_get_xfer_type(const PurpleXfer *xfer); 238 PurpleXferType purple_xfer_get_xfer_type(const PurpleXfer *xfer);
239 239
240 /** 240 /**
241 * Returns the account the file transfer is using. 241 * Returns the account the file transfer is using.
242 * 242 *
243 * @xfer: The file transfer. 243 * @param xfer The file transfer.
244 * 244 *
245 * Returns: The account. 245 * @return The account.
246 */ 246 */
247 PurpleAccount *purple_xfer_get_account(const PurpleXfer *xfer); 247 PurpleAccount *purple_xfer_get_account(const PurpleXfer *xfer);
248 248
249 /** 249 /**
250 * Sets the name of the remote user. 250 * Sets the name of the remote user.
251 * 251 *
252 * @xfer: The file transfer. 252 * @param xfer The file transfer.
253 * @who: The name of the remote user. 253 * @param who The name of the remote user.
254 */ 254 */
255 void purple_xfer_set_remote_user(PurpleXfer *xfer, const char *who); 255 void purple_xfer_set_remote_user(PurpleXfer *xfer, const char *who);
256 256
257 /** 257 /**
258 * Returns the name of the remote user. 258 * Returns the name of the remote user.
259 * 259 *
260 * @xfer: The file transfer. 260 * @param xfer The file transfer.
261 * 261 *
262 * Returns: The name of the remote user. 262 * @return The name of the remote user.
263 */ 263 */
264 const char *purple_xfer_get_remote_user(const PurpleXfer *xfer); 264 const char *purple_xfer_get_remote_user(const PurpleXfer *xfer);
265 265
266 /** 266 /**
267 * Returns the status of the xfer. 267 * Returns the status of the xfer.
268 * 268 *
269 * @xfer: The file transfer. 269 * @param xfer The file transfer.
270 * 270 *
271 * Returns: The status. 271 * @return The status.
272 */ 272 */
273 PurpleXferStatus purple_xfer_get_status(const PurpleXfer *xfer); 273 PurpleXferStatus purple_xfer_get_status(const PurpleXfer *xfer);
274 274
275 /** 275 /**
276 * Returns true if the file transfer was cancelled. 276 * Returns true if the file transfer was cancelled.
277 * 277 *
278 * @xfer: The file transfer. 278 * @param xfer The file transfer.
279 * 279 *
280 * Returns: Whether or not the transfer was cancelled. 280 * @return Whether or not the transfer was cancelled.
281 */ 281 */
282 gboolean purple_xfer_is_cancelled(const PurpleXfer *xfer); 282 gboolean purple_xfer_is_cancelled(const PurpleXfer *xfer);
283 283
284 /** 284 /**
285 * Returns the completed state for a file transfer. 285 * Returns the completed state for a file transfer.
286 * 286 *
287 * @xfer: The file transfer. 287 * @param xfer The file transfer.
288 * 288 *
289 * Returns: The completed state. 289 * @return The completed state.
290 */ 290 */
291 gboolean purple_xfer_is_completed(const PurpleXfer *xfer); 291 gboolean purple_xfer_is_completed(const PurpleXfer *xfer);
292 292
293 /** 293 /**
294 * Returns the name of the file being sent or received. 294 * Returns the name of the file being sent or received.
295 * 295 *
296 * @xfer: The file transfer. 296 * @param xfer The file transfer.
297 * 297 *
298 * Returns: The filename. 298 * @return The filename.
299 */ 299 */
300 const char *purple_xfer_get_filename(const PurpleXfer *xfer); 300 const char *purple_xfer_get_filename(const PurpleXfer *xfer);
301 301
302 /** 302 /**
303 * Returns the file's destination filename, 303 * Returns the file's destination filename,
304 * 304 *
305 * @xfer: The file transfer. 305 * @param xfer The file transfer.
306 * 306 *
307 * Returns: The destination filename. 307 * @return The destination filename.
308 */ 308 */
309 const char *purple_xfer_get_local_filename(const PurpleXfer *xfer); 309 const char *purple_xfer_get_local_filename(const PurpleXfer *xfer);
310 310
311 /** 311 /**
312 * Returns the number of bytes sent (or received) so far. 312 * Returns the number of bytes sent (or received) so far.
313 * 313 *
314 * @xfer: The file transfer. 314 * @param xfer The file transfer.
315 * 315 *
316 * Returns: The number of bytes sent. 316 * @return The number of bytes sent.
317 */ 317 */
318 goffset purple_xfer_get_bytes_sent(const PurpleXfer *xfer); 318 goffset purple_xfer_get_bytes_sent(const PurpleXfer *xfer);
319 319
320 /** 320 /**
321 * Returns the number of bytes remaining to send or receive. 321 * Returns the number of bytes remaining to send or receive.
322 * 322 *
323 * @xfer: The file transfer. 323 * @param xfer The file transfer.
324 * 324 *
325 * Returns: The number of bytes remaining. 325 * @return The number of bytes remaining.
326 */ 326 */
327 goffset purple_xfer_get_bytes_remaining(const PurpleXfer *xfer); 327 goffset purple_xfer_get_bytes_remaining(const PurpleXfer *xfer);
328 328
329 /** 329 /**
330 * Returns the size of the file being sent or received. 330 * Returns the size of the file being sent or received.
331 * 331 *
332 * @xfer: The file transfer. 332 * @param xfer The file transfer.
333 * 333 *
334 * Returns: The total size of the file. 334 * @return The total size of the file.
335 */ 335 */
336 goffset purple_xfer_get_size(const PurpleXfer *xfer); 336 goffset purple_xfer_get_size(const PurpleXfer *xfer);
337 337
338 /** 338 /**
339 * Returns the current percentage of progress of the transfer. 339 * Returns the current percentage of progress of the transfer.
340 * 340 *
341 * This is a number between 0 (0%) and 1 (100%). 341 * This is a number between 0 (0%) and 1 (100%).
342 * 342 *
343 * @xfer: The file transfer. 343 * @param xfer The file transfer.
344 * 344 *
345 * Returns: The percentage complete. 345 * @return The percentage complete.
346 */ 346 */
347 double purple_xfer_get_progress(const PurpleXfer *xfer); 347 double purple_xfer_get_progress(const PurpleXfer *xfer);
348 348
349 /** 349 /**
350 * Returns the local port number in the file transfer. 350 * Returns the local port number in the file transfer.
351 * 351 *
352 * @xfer: The file transfer. 352 * @param xfer The file transfer.
353 * 353 *
354 * Returns: The port number on this end. 354 * @return The port number on this end.
355 */ 355 */
356 guint16 purple_xfer_get_local_port(const PurpleXfer *xfer); 356 guint16 purple_xfer_get_local_port(const PurpleXfer *xfer);
357 357
358 /** 358 /**
359 * Returns the remote IP address in the file transfer. 359 * Returns the remote IP address in the file transfer.
360 * 360 *
361 * @xfer: The file transfer. 361 * @param xfer The file transfer.
362 * 362 *
363 * Returns: The IP address on the other end. 363 * @return The IP address on the other end.
364 */ 364 */
365 const char *purple_xfer_get_remote_ip(const PurpleXfer *xfer); 365 const char *purple_xfer_get_remote_ip(const PurpleXfer *xfer);
366 366
367 /** 367 /**
368 * Returns the remote port number in the file transfer. 368 * Returns the remote port number in the file transfer.
369 * 369 *
370 * @xfer: The file transfer. 370 * @param xfer The file transfer.
371 * 371 *
372 * Returns: The port number on the other end. 372 * @return The port number on the other end.
373 */ 373 */
374 guint16 purple_xfer_get_remote_port(const PurpleXfer *xfer); 374 guint16 purple_xfer_get_remote_port(const PurpleXfer *xfer);
375 375
376 /** 376 /**
377 * Returns the time the transfer of a file started. 377 * Returns the time the transfer of a file started.
378 * 378 *
379 * @xfer: The file transfer. 379 * @param xfer The file transfer.
380 * 380 *
381 * Returns: The time when the transfer started. 381 * @return The time when the transfer started.
382 */ 382 */
383 time_t purple_xfer_get_start_time(const PurpleXfer *xfer); 383 time_t purple_xfer_get_start_time(const PurpleXfer *xfer);
384 384
385 /** 385 /**
386 * Returns the time the transfer of a file ended. 386 * Returns the time the transfer of a file ended.
387 * 387 *
388 * @xfer: The file transfer. 388 * @param xfer The file transfer.
389 * 389 *
390 * Returns: The time when the transfer ended. 390 * @return The time when the transfer ended.
391 */ 391 */
392 time_t purple_xfer_get_end_time(const PurpleXfer *xfer); 392 time_t purple_xfer_get_end_time(const PurpleXfer *xfer);
393 393
394 /** 394 /**
395 * Sets the socket file descriptor. 395 * Sets the socket file descriptor.
396 * 396 *
397 * @xfer: The file transfer. 397 * @param xfer The file transfer.
398 * @fd: The file descriptor. 398 * @param fd The file descriptor.
399 */ 399 */
400 void purple_xfer_set_fd(PurpleXfer *xfer, int fd); 400 void purple_xfer_set_fd(PurpleXfer *xfer, int fd);
401 401
402 /** 402 /**
403 * Sets the watcher for the file transfer. 403 * Sets the watcher for the file transfer.
404 * 404 *
405 * @xfer: The file transfer. 405 * @param xfer The file transfer.
406 * @watcher: The watcher. 406 * @param watcher The watcher.
407 */ 407 */
408 void purple_xfer_set_watcher(PurpleXfer *xfer, int watcher); 408 void purple_xfer_set_watcher(PurpleXfer *xfer, int watcher);
409 409
410 /** 410 /**
411 * Sets the completed state for the file transfer. 411 * Sets the completed state for the file transfer.
412 * 412 *
413 * @xfer: The file transfer. 413 * @param xfer The file transfer.
414 * @completed: The completed state. 414 * @param completed The completed state.
415 */ 415 */
416 void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed); 416 void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed);
417 417
418 /** 418 /**
419 * Sets the current status for the file transfer. 419 * Sets the current status for the file transfer.
420 * 420 *
421 * @xfer: The file transfer. 421 * @param xfer The file transfer.
422 * @status: The current status. 422 * @param status The current status.
423 */ 423 */
424 void purple_xfer_set_status(PurpleXfer *xfer, PurpleXferStatus status); 424 void purple_xfer_set_status(PurpleXfer *xfer, PurpleXferStatus status);
425 425
426 /** 426 /**
427 * Sets the message for the file transfer. 427 * Sets the message for the file transfer.
428 * 428 *
429 * @xfer: The file transfer. 429 * @param xfer The file transfer.
430 * @message: The message. 430 * @param message The message.
431 */ 431 */
432 void purple_xfer_set_message(PurpleXfer *xfer, const char *message); 432 void purple_xfer_set_message(PurpleXfer *xfer, const char *message);
433 433
434 /** 434 /**
435 * Returns the message for the file transfer. 435 * Returns the message for the file transfer.
436 * 436 *
437 * @xfer: The file transfer. 437 * @param xfer The file transfer.
438 * 438 *
439 * Returns: The message. 439 * @return The message.
440 */ 440 */
441 const char *purple_xfer_get_message(const PurpleXfer *xfer); 441 const char *purple_xfer_get_message(const PurpleXfer *xfer);
442 442
443 /** 443 /**
444 * Sets the filename for the file transfer. 444 * Sets the filename for the file transfer.
445 * 445 *
446 * @xfer: The file transfer. 446 * @param xfer The file transfer.
447 * @filename: The filename. 447 * @param filename The filename.
448 */ 448 */
449 void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename); 449 void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename);
450 450
451 /** 451 /**
452 * Sets the local filename for the file transfer. 452 * Sets the local filename for the file transfer.
453 * 453 *
454 * @xfer: The file transfer. 454 * @param xfer The file transfer.
455 * @filename: The filename 455 * @param filename The filename
456 */ 456 */
457 void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename); 457 void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename);
458 458
459 /** 459 /**
460 * Sets the size of the file in a file transfer. 460 * Sets the size of the file in a file transfer.
461 * 461 *
462 * @xfer: The file transfer. 462 * @param xfer The file transfer.
463 * @size: The size of the file. 463 * @param size The size of the file.
464 */ 464 */
465 void purple_xfer_set_size(PurpleXfer *xfer, goffset size); 465 void purple_xfer_set_size(PurpleXfer *xfer, goffset size);
466 466
467 /** 467 /**
468 * Sets the local port of the file transfer. 468 * Sets the local port of the file transfer.
469 * 469 *
470 * @xfer: The file transfer. 470 * @param xfer The file transfer.
471 * @local_port: The local port. 471 * @param local_port The local port.
472 */ 472 */
473 void purple_xfer_set_local_port(PurpleXfer *xfer, guint16 local_port); 473 void purple_xfer_set_local_port(PurpleXfer *xfer, guint16 local_port);
474 474
475 /** 475 /**
476 * Sets the current working position in the active file transfer. This 476 * Sets the current working position in the active file transfer. This
477 * can be used to jump backward in the file if the protocol detects 477 * can be used to jump backward in the file if the protocol detects
478 * that some bit of data needs to be resent or has been sent twice. 478 * that some bit of data needs to be resent or has been sent twice.
479 * 479 *
480 * It's used for pausing and resuming an oscar file transfer. 480 * It's used for pausing and resuming an oscar file transfer.
481 * 481 *
482 * @xfer: The file transfer. 482 * @param xfer The file transfer.
483 * @bytes_sent: The new current position in the file. If we're 483 * @param bytes_sent The new current position in the file. If we're
484 * sending a file then this is the byte that we will 484 * sending a file then this is the byte that we will
485 * send. If we're receiving a file, this is the 485 * send. If we're receiving a file, this is the
486 * next byte that we expect to receive. 486 * next byte that we expect to receive.
487 */ 487 */
488 void purple_xfer_set_bytes_sent(PurpleXfer *xfer, goffset bytes_sent); 488 void purple_xfer_set_bytes_sent(PurpleXfer *xfer, goffset bytes_sent);
489 489
490 /** 490 /**
491 * Returns the UI operations structure for a file transfer. 491 * Returns the UI operations structure for a file transfer.
492 * 492 *
493 * @xfer: The file transfer. 493 * @param xfer The file transfer.
494 * 494 *
495 * Returns: The UI operations structure. 495 * @return The UI operations structure.
496 */ 496 */
497 PurpleXferUiOps *purple_xfer_get_ui_ops(const PurpleXfer *xfer); 497 PurpleXferUiOps *purple_xfer_get_ui_ops(const PurpleXfer *xfer);
498 498
499 /** 499 /**
500 * Sets the read function for the file transfer. 500 * Sets the read function for the file transfer.
501 * 501 *
502 * @xfer: The file transfer. 502 * @param xfer The file transfer.
503 * @fnc: The read function. 503 * @param fnc The read function.
504 */ 504 */
505 void purple_xfer_set_read_fnc(PurpleXfer *xfer, 505 void purple_xfer_set_read_fnc(PurpleXfer *xfer,
506 gssize (*fnc)(guchar **, size_t, PurpleXfer *)); 506 gssize (*fnc)(guchar **, size_t, PurpleXfer *));
507 507
508 /** 508 /**
509 * Sets the write function for the file transfer. 509 * Sets the write function for the file transfer.
510 * 510 *
511 * @xfer: The file transfer. 511 * @param xfer The file transfer.
512 * @fnc: The write function. 512 * @param fnc The write function.
513 */ 513 */
514 void purple_xfer_set_write_fnc(PurpleXfer *xfer, 514 void purple_xfer_set_write_fnc(PurpleXfer *xfer,
515 gssize (*fnc)(const guchar *, size_t, PurpleXfer *)); 515 gssize (*fnc)(const guchar *, size_t, PurpleXfer *));
516 516
517 /** 517 /**
518 * Sets the acknowledge function for the file transfer. 518 * Sets the acknowledge function for the file transfer.
519 * 519 *
520 * @xfer: The file transfer. 520 * @param xfer The file transfer.
521 * @fnc: The acknowledge function. 521 * @param fnc The acknowledge function.
522 */ 522 */
523 void purple_xfer_set_ack_fnc(PurpleXfer *xfer, 523 void purple_xfer_set_ack_fnc(PurpleXfer *xfer,
524 void (*fnc)(PurpleXfer *, const guchar *, size_t)); 524 void (*fnc)(PurpleXfer *, const guchar *, size_t));
525 525
526 /** 526 /**
527 * Sets the function to be called if the request is denied. 527 * Sets the function to be called if the request is denied.
528 * 528 *
529 * @xfer: The file transfer. 529 * @param xfer The file transfer.
530 * @fnc: The request denied protocol callback. 530 * @param fnc The request denied protocol callback.
531 */ 531 */
532 void purple_xfer_set_request_denied_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 532 void purple_xfer_set_request_denied_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
533 533
534 /** 534 /**
535 * Sets the transfer initialization function for the file transfer. 535 * Sets the transfer initialization function for the file transfer.
536 * 536 *
537 * This function is required, and must call purple_xfer_start() with 537 * This function is required, and must call purple_xfer_start() with
538 * the necessary parameters. This will be called if the file transfer 538 * the necessary parameters. This will be called if the file transfer
539 * is accepted by the user. 539 * is accepted by the user.
540 * 540 *
541 * @xfer: The file transfer. 541 * @param xfer The file transfer.
542 * @fnc: The transfer initialization function. 542 * @param fnc The transfer initialization function.
543 */ 543 */
544 void purple_xfer_set_init_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 544 void purple_xfer_set_init_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
545 545
546 /** 546 /**
547 * Sets the start transfer function for the file transfer. 547 * Sets the start transfer function for the file transfer.
548 * 548 *
549 * @xfer: The file transfer. 549 * @param xfer The file transfer.
550 * @fnc: The start transfer function. 550 * @param fnc The start transfer function.
551 */ 551 */
552 void purple_xfer_set_start_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 552 void purple_xfer_set_start_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
553 553
554 /** 554 /**
555 * Sets the end transfer function for the file transfer. 555 * Sets the end transfer function for the file transfer.
556 * 556 *
557 * @xfer: The file transfer. 557 * @param xfer The file transfer.
558 * @fnc: The end transfer function. 558 * @param fnc The end transfer function.
559 */ 559 */
560 void purple_xfer_set_end_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 560 void purple_xfer_set_end_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
561 561
562 /** 562 /**
563 * Sets the cancel send function for the file transfer. 563 * Sets the cancel send function for the file transfer.
564 * 564 *
565 * @xfer: The file transfer. 565 * @param xfer The file transfer.
566 * @fnc: The cancel send function. 566 * @param fnc The cancel send function.
567 */ 567 */
568 void purple_xfer_set_cancel_send_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 568 void purple_xfer_set_cancel_send_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
569 569
570 /** 570 /**
571 * Sets the cancel receive function for the file transfer. 571 * Sets the cancel receive function for the file transfer.
572 * 572 *
573 * @xfer: The file transfer. 573 * @param xfer The file transfer.
574 * @fnc: The cancel receive function. 574 * @param fnc The cancel receive function.
575 */ 575 */
576 void purple_xfer_set_cancel_recv_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); 576 void purple_xfer_set_cancel_recv_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
577 577
578 /** 578 /**
579 * Reads in data from a file transfer stream. 579 * Reads in data from a file transfer stream.
580 * 580 *
581 * @xfer: The file transfer. 581 * @param xfer The file transfer.
582 * @buffer: The buffer that will be created to contain the data. 582 * @param buffer The buffer that will be created to contain the data.
583 * 583 *
584 * Returns: The number of bytes read, or -1. 584 * @return The number of bytes read, or -1.
585 */ 585 */
586 gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer); 586 gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer);
587 587
588 /** 588 /**
589 * Writes data to a file transfer stream. 589 * Writes data to a file transfer stream.
590 * 590 *
591 * @xfer: The file transfer. 591 * @param xfer The file transfer.
592 * @buffer: The buffer to read the data from. 592 * @param buffer The buffer to read the data from.
593 * @size: The number of bytes to write. 593 * @param size The number of bytes to write.
594 * 594 *
595 * Returns: The number of bytes written, or -1. 595 * @return The number of bytes written, or -1.
596 */ 596 */
597 gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size); 597 gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size);
598 598
599 /** 599 /**
600 * Writes chunk of received file. 600 * Writes chunk of received file.
601 * 601 *
602 * @xfer: The file transfer. 602 * @param xfer The file transfer.
603 * @buffer: The buffer to read the data from. 603 * @param buffer The buffer to read the data from.
604 * @size: The number of bytes to write. 604 * @param size The number of bytes to write.
605 * 605 *
606 * Returns: TRUE on success, FALSE otherwise. 606 * @return TRUE on success, FALSE otherwise.
607 */ 607 */
608 gboolean 608 gboolean
609 purple_xfer_write_file(PurpleXfer *xfer, const guchar *buffer, gsize size); 609 purple_xfer_write_file(PurpleXfer *xfer, const guchar *buffer, gsize size);
610 610
611 /** 611 /**
612 * Writes chunk of file being sent. 612 * Writes chunk of file being sent.
613 * 613 *
614 * @xfer: The file transfer. 614 * @param xfer The file transfer.
615 * @buffer: The buffer to write the data to. 615 * @param buffer The buffer to write the data to.
616 * @size: The size of buffer. 616 * @param size The size of buffer.
617 * 617 *
618 * Returns: Number of bytes written (0 means, the device is busy), or -1 on 618 * @return Number of bytes written (0 means, the device is busy), or -1 on
619 * failure. 619 * failure.
620 */ 620 */
621 gssize 621 gssize
622 purple_xfer_read_file(PurpleXfer *xfer, guchar *buffer, gsize size); 622 purple_xfer_read_file(PurpleXfer *xfer, guchar *buffer, gsize size);
623 623
629 * @a ip and @a port are ignored. 629 * @a ip and @a port are ignored.
630 * 630 *
631 * Passing @a fd as '-1' is a special-case and indicates to the 631 * Passing @a fd as '-1' is a special-case and indicates to the
632 * protocol to facilitate the file transfer itself. 632 * protocol to facilitate the file transfer itself.
633 * 633 *
634 * @xfer: The file transfer. 634 * @param xfer The file transfer.
635 * @fd: The file descriptor for the socket. 635 * @param fd The file descriptor for the socket.
636 * @ip: The IP address to connect to. 636 * @param ip The IP address to connect to.
637 * @port: The port to connect to. 637 * @param port The port to connect to.
638 */ 638 */
639 void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip, guint16 port); 639 void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip, guint16 port);
640 640
641 /** 641 /**
642 * Ends a file transfer. 642 * Ends a file transfer.
643 * 643 *
644 * @xfer: The file transfer. 644 * @param xfer The file transfer.
645 */ 645 */
646 void purple_xfer_end(PurpleXfer *xfer); 646 void purple_xfer_end(PurpleXfer *xfer);
647 647
648 /** 648 /**
649 * Adds a new file transfer to the list of file transfers. Call this only 649 * Adds a new file transfer to the list of file transfers. Call this only
650 * if you are not using purple_xfer_start. 650 * if you are not using purple_xfer_start.
651 * 651 *
652 * @xfer: The file transfer. 652 * @param xfer The file transfer.
653 */ 653 */
654 void purple_xfer_add(PurpleXfer *xfer); 654 void purple_xfer_add(PurpleXfer *xfer);
655 655
656 /** 656 /**
657 * Cancels a file transfer on the local end. 657 * Cancels a file transfer on the local end.
658 * 658 *
659 * @xfer: The file transfer. 659 * @param xfer The file transfer.
660 */ 660 */
661 void purple_xfer_cancel_local(PurpleXfer *xfer); 661 void purple_xfer_cancel_local(PurpleXfer *xfer);
662 662
663 /** 663 /**
664 * Cancels a file transfer from the remote end. 664 * Cancels a file transfer from the remote end.
665 * 665 *
666 * @xfer: The file transfer. 666 * @param xfer The file transfer.
667 */ 667 */
668 void purple_xfer_cancel_remote(PurpleXfer *xfer); 668 void purple_xfer_cancel_remote(PurpleXfer *xfer);
669 669
670 /** 670 /**
671 * Displays a file transfer-related error message. 671 * Displays a file transfer-related error message.
672 * 672 *
673 * This is a wrapper around purple_notify_error(), which automatically 673 * This is a wrapper around purple_notify_error(), which automatically
674 * specifies a title ("File transfer to <i>user</i> failed" or 674 * specifies a title ("File transfer to <i>user</i> failed" or
675 * "File Transfer from <i>user</i> failed"). 675 * "File Transfer from <i>user</i> failed").
676 * 676 *
677 * @type: The type of file transfer. 677 * @param type The type of file transfer.
678 * @account: The account sending or receiving the file. 678 * @param account The account sending or receiving the file.
679 * @who: The user on the other end of the transfer. 679 * @param who The user on the other end of the transfer.
680 * @msg: The message to display. 680 * @param msg The message to display.
681 */ 681 */
682 void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg); 682 void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg);
683 683
684 /** 684 /**
685 * Updates file transfer progress. 685 * Updates file transfer progress.
686 * 686 *
687 * @xfer: The file transfer. 687 * @param xfer The file transfer.
688 */ 688 */
689 void purple_xfer_update_progress(PurpleXfer *xfer); 689 void purple_xfer_update_progress(PurpleXfer *xfer);
690 690
691 /** 691 /**
692 * Displays a file transfer-related message in the conversation window 692 * Displays a file transfer-related message in the conversation window
693 * 693 *
694 * This is a wrapper around purple_conversation_write 694 * This is a wrapper around purple_conversation_write
695 * 695 *
696 * @xfer: The file transfer to which this message relates. 696 * @param xfer The file transfer to which this message relates.
697 * @message: The message to display. 697 * @param message The message to display.
698 * @is_error: Is this an error message?. 698 * @param is_error Is this an error message?.
699 */ 699 */
700 void purple_xfer_conversation_write(PurpleXfer *xfer, const gchar *message, gboolean is_error); 700 void purple_xfer_conversation_write(PurpleXfer *xfer, const gchar *message, gboolean is_error);
701 701
702 /** 702 /**
703 * Allows the UI to signal it's ready to send/receive data (depending on 703 * Allows the UI to signal it's ready to send/receive data (depending on
704 * the direction of the file transfer. Used when the UI is providing 704 * the direction of the file transfer. Used when the UI is providing
705 * read/write/data_not_sent UI ops. 705 * read/write/data_not_sent UI ops.
706 * 706 *
707 * @xfer: The file transfer which is ready. 707 * @param xfer The file transfer which is ready.
708 */ 708 */
709 void purple_xfer_ui_ready(PurpleXfer *xfer); 709 void purple_xfer_ui_ready(PurpleXfer *xfer);
710 710
711 /** 711 /**
712 * Allows the protocol to signal it's ready to send/receive data (depending on 712 * Allows the protocol to signal it's ready to send/receive data (depending on
713 * the direction of the file transfer. Used when the protocol provides read/write 713 * the direction of the file transfer. Used when the protocol provides read/write
714 * ops and cannot/does not provide a raw fd to the core. 714 * ops and cannot/does not provide a raw fd to the core.
715 * 715 *
716 * @xfer: The file transfer which is ready. 716 * @param xfer The file transfer which is ready.
717 */ 717 */
718 void purple_xfer_protocol_ready(PurpleXfer *xfer); 718 void purple_xfer_protocol_ready(PurpleXfer *xfer);
719 719
720 /** 720 /**
721 * Gets the thumbnail data for a transfer 721 * Gets the thumbnail data for a transfer
722 * 722 *
723 * @xfer: The file transfer to get the thumbnail for 723 * @param xfer The file transfer to get the thumbnail for
724 * @len: If not %NULL, the length of the thumbnail data returned 724 * @param len If not @c NULL, the length of the thumbnail data returned
725 * will be set in the location pointed to by this. 725 * will be set in the location pointed to by this.
726 * Returns: The thumbnail data, or NULL if there is no thumbnail 726 * @return The thumbnail data, or NULL if there is no thumbnail
727 */ 727 */
728 gconstpointer purple_xfer_get_thumbnail(const PurpleXfer *xfer, gsize *len); 728 gconstpointer purple_xfer_get_thumbnail(const PurpleXfer *xfer, gsize *len);
729 729
730 /** 730 /**
731 * Gets the mimetype of the thumbnail preview for a transfer 731 * Gets the mimetype of the thumbnail preview for a transfer
732 * 732 *
733 * @xfer: The file transfer to get the mimetype for 733 * @param xfer The file transfer to get the mimetype for
734 * Returns: The mimetype of the thumbnail, or %NULL if not thumbnail is set 734 * @return The mimetype of the thumbnail, or @c NULL if not thumbnail is set
735 */ 735 */
736 const gchar *purple_xfer_get_thumbnail_mimetype(const PurpleXfer *xfer); 736 const gchar *purple_xfer_get_thumbnail_mimetype(const PurpleXfer *xfer);
737 737
738 738
739 /** 739 /**
740 * Sets the thumbnail data for a transfer 740 * Sets the thumbnail data for a transfer
741 * 741 *
742 * @xfer: The file transfer to set the data for 742 * @param xfer The file transfer to set the data for
743 * @thumbnail: A pointer to the thumbnail data, this will be copied 743 * @param thumbnail A pointer to the thumbnail data, this will be copied
744 * @size: The size in bytes of the passed in thumbnail data 744 * @param size The size in bytes of the passed in thumbnail data
745 * @mimetype: The mimetype of the generated thumbnail 745 * @param mimetype The mimetype of the generated thumbnail
746 */ 746 */
747 void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail, 747 void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail,
748 gsize size, const gchar *mimetype); 748 gsize size, const gchar *mimetype);
749 749
750 /** 750 /**
751 * Prepare a thumbnail for a transfer (if the UI supports it) 751 * Prepare a thumbnail for a transfer (if the UI supports it)
752 * will be no-op in case the UI doesn't implement thumbnail creation 752 * will be no-op in case the UI doesn't implement thumbnail creation
753 * 753 *
754 * @xfer: The file transfer to create a thumbnail for 754 * @param xfer The file transfer to create a thumbnail for
755 * @formats: A comma-separated list of mimetypes for image formats 755 * @param formats A comma-separated list of mimetypes for image formats
756 * the protocols can use for thumbnails. 756 * the protocols can use for thumbnails.
757 */ 757 */
758 void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats); 758 void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats);
759 759
760 /** 760 /**
761 * Sets the protocol data for a file transfer. 761 * Sets the protocol data for a file transfer.
762 * 762 *
763 * @xfer: The file transfer. 763 * @param xfer The file transfer.
764 * @proto_data: The protocol data to set for the file transfer. 764 * @param proto_data The protocol data to set for the file transfer.
765 */ 765 */
766 void purple_xfer_set_protocol_data(PurpleXfer *xfer, gpointer proto_data); 766 void purple_xfer_set_protocol_data(PurpleXfer *xfer, gpointer proto_data);
767 767
768 /** 768 /**
769 * Gets the protocol data for a file transfer. 769 * Gets the protocol data for a file transfer.
770 * 770 *
771 * @xfer: The file transfer. 771 * @param xfer The file transfer.
772 * 772 *
773 * Returns: The protocol data for the file transfer. 773 * @return The protocol data for the file transfer.
774 */ 774 */
775 gpointer purple_xfer_get_protocol_data(const PurpleXfer *xfer); 775 gpointer purple_xfer_get_protocol_data(const PurpleXfer *xfer);
776 776
777 /** 777 /**
778 * Set the UI data associated with this file transfer. 778 * Set the UI data associated with this file transfer.
779 * 779 *
780 * @xfer: The file transfer. 780 * @param xfer The file transfer.
781 * @ui_data: A pointer to associate with this file transfer. 781 * @param ui_data A pointer to associate with this file transfer.
782 */ 782 */
783 void purple_xfer_set_ui_data(PurpleXfer *xfer, gpointer ui_data); 783 void purple_xfer_set_ui_data(PurpleXfer *xfer, gpointer ui_data);
784 784
785 /** 785 /**
786 * Get the UI data associated with this file transfer. 786 * Get the UI data associated with this file transfer.
787 * 787 *
788 * @xfer: The file transfer. 788 * @param xfer The file transfer.
789 * 789 *
790 * Returns: The UI data associated with this file transfer. This is a 790 * @return The UI data associated with this file transfer. This is a
791 * convenience field provided to the UIs--it is not 791 * convenience field provided to the UIs--it is not
792 * used by the libpurple core. 792 * used by the libpurple core.
793 */ 793 */
794 gpointer purple_xfer_get_ui_data(const PurpleXfer *xfer); 794 gpointer purple_xfer_get_ui_data(const PurpleXfer *xfer);
795 795
801 /*@{*/ 801 /*@{*/
802 802
803 /** 803 /**
804 * Returns all xfers 804 * Returns all xfers
805 * 805 *
806 * Returns: all current xfers with refs 806 * @return all current xfers with refs
807 */ 807 */
808 GList *purple_xfers_get_all(void); 808 GList *purple_xfers_get_all(void);
809 809
810 /** 810 /**
811 * Returns the handle to the file transfer subsystem 811 * Returns the handle to the file transfer subsystem
812 * 812 *
813 * Returns: The handle 813 * @return The handle
814 */ 814 */
815 void *purple_xfers_get_handle(void); 815 void *purple_xfers_get_handle(void);
816 816
817 /** 817 /**
818 * Initializes the file transfer subsystem 818 * Initializes the file transfer subsystem
825 void purple_xfers_uninit(void); 825 void purple_xfers_uninit(void);
826 826
827 /** 827 /**
828 * Sets the UI operations structure to be used in all purple file transfers. 828 * Sets the UI operations structure to be used in all purple file transfers.
829 * 829 *
830 * @ops: The UI operations structure. 830 * @param ops The UI operations structure.
831 */ 831 */
832 void purple_xfers_set_ui_ops(PurpleXferUiOps *ops); 832 void purple_xfers_set_ui_ops(PurpleXferUiOps *ops);
833 833
834 /** 834 /**
835 * Returns the UI operations structure to be used in all purple file transfers. 835 * Returns the UI operations structure to be used in all purple file transfers.
836 * 836 *
837 * Returns: The UI operations structure. 837 * @return The UI operations structure.
838 */ 838 */
839 PurpleXferUiOps *purple_xfers_get_ui_ops(void); 839 PurpleXferUiOps *purple_xfers_get_ui_ops(void);
840 840
841 /*@}*/ 841 /*@}*/
842 842

Mercurial Repository: pidgin3

mercurial