source: protocols/yahoo/yahoo2_callbacks.h @ 881fd4e

Last change on this file since 881fd4e was b7d3cc34, checked in by Wilmer van der Gaast <wilmer@…>, at 2005-11-06T18:23:18Z

Initial repository (0.99 release tree)

  • Property mode set to 100644
File size: 18.4 KB
Line 
1/*
2 * libyahoo2: yahoo2_callbacks.h
3 *
4 * Copyright (C) 2002-2004, Philip S Tellis <philip.tellis AT gmx.net>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program 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
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19 *
20 */
21
22/*
23 * The functions in this file *must* be defined in your client program
24 * If you want to use a callback structure instead of direct functions,
25 * then you must define USE_STRUCT_CALLBACKS in all files that #include
26 * this one.
27 *
28 * Register the callback structure by calling yahoo_register_callbacks -
29 * declared in this file and defined in libyahoo2.c
30 */
31
32
33
34#ifndef YAHOO2_CALLBACKS_H
35#define YAHOO2_CALLBACKS_H
36
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41#include "yahoo2_types.h"
42
43/*
44 * yahoo2_callbacks.h
45 *
46 * Callback interface for libyahoo2
47 */
48
49typedef enum {
50        YAHOO_INPUT_READ = 1 << 0,
51        YAHOO_INPUT_WRITE = 1 << 1,
52        YAHOO_INPUT_EXCEPTION = 1 << 2
53} yahoo_input_condition;
54
55/*
56 * A callback function called when an asynchronous connect completes.
57 *
58 * Params:
59 *     fd    - The file descriptor that has been connected, or -1 on error
60 *     error - The value of errno set by the call to connect or 0 if no error
61 *             Set both fd and error to 0 if the connect was cancelled by the
62 *             user
63 *     callback_data - the callback_data passed to the ext_yahoo_connect_async
64 *             function
65 */
66typedef void (*yahoo_connect_callback)(int fd, int error, void *callback_data);
67
68
69
70/*
71 * The following functions need to be implemented in the client
72 * interface.  They will be called by the library when each
73 * event occurs.
74 */
75
76/*
77 * should we use a callback structure or directly call functions
78 * if you want the structure, you *must* define USE_STRUCT_CALLBACKS
79 * both when you compile the library, and when you compile your code
80 * that uses the library
81 */
82
83#ifdef USE_STRUCT_CALLBACKS
84#define YAHOO_CALLBACK_TYPE(x)  (*x)
85struct yahoo_callbacks {
86#else
87#define YAHOO_CALLBACK_TYPE(x)  x
88#endif
89
90/*
91 * Name: ext_yahoo_login_response
92 *      Called when the login process is complete
93 * Params:
94 *      id   - the id that identifies the server connection
95 *      succ - enum yahoo_login_status
96 *      url  - url to reactivate account if locked
97 */
98void YAHOO_CALLBACK_TYPE(ext_yahoo_login_response)(int id, int succ, char *url);
99
100
101
102
103/*
104 * Name: ext_yahoo_got_buddies
105 *      Called when the contact list is got from the server
106 * Params:
107 *      id   - the id that identifies the server connection
108 *      buds - the buddy list
109 */
110void YAHOO_CALLBACK_TYPE(ext_yahoo_got_buddies)(int id, YList * buds);
111
112
113
114
115/*
116 * Name: ext_yahoo_got_ignore
117 *      Called when the ignore list is got from the server
118 * Params:
119 *      id   - the id that identifies the server connection
120 *      igns - the ignore list
121 */
122void YAHOO_CALLBACK_TYPE(ext_yahoo_got_ignore)(int id, YList * igns);
123
124
125
126
127
128/*
129 * Name: ext_yahoo_got_identities
130 *      Called when the contact list is got from the server
131 * Params:
132 *      id   - the id that identifies the server connection
133 *      ids  - the identity list
134 */
135void YAHOO_CALLBACK_TYPE(ext_yahoo_got_identities)(int id, YList * ids);
136
137
138
139
140
141/*
142 * Name: ext_yahoo_got_cookies
143 *      Called when the cookie list is got from the server
144 * Params:
145 *      id   - the id that identifies the server connection
146 */
147void YAHOO_CALLBACK_TYPE(ext_yahoo_got_cookies)(int id);
148
149
150
151
152/*
153 * Name: ext_yahoo_status_changed
154 *      Called when remote user's status changes.
155 * Params:
156 *      id   - the id that identifies the server connection
157 *      who  - the handle of the remote user
158 *      stat - status code (enum yahoo_status)
159 *      msg  - the message if stat == YAHOO_STATUS_CUSTOM
160 *      away - whether the contact is away or not (YAHOO_STATUS_CUSTOM)
161 *             for YAHOO_STATUS_IDLE, this is the number of seconds he is idle
162 */
163void YAHOO_CALLBACK_TYPE(ext_yahoo_status_changed)(int id, char *who, int stat, char *msg, int away);
164
165
166
167
168/*
169 * Name: ext_yahoo_got_im
170 *      Called when remote user sends you a message.
171 * Params:
172 *      id   - the id that identifies the server connection
173 *      who  - the handle of the remote user
174 *      msg  - the message - NULL if stat == 2
175 *      tm   - timestamp of message if offline
176 *      stat - message status - 0
177 *                              1
178 *                              2 == error sending message
179 *                              5
180 *      utf8 - whether the message is encoded as utf8 or not
181 */
182void YAHOO_CALLBACK_TYPE(ext_yahoo_got_im)(int id, char *who, char *msg, long tm, int stat, int utf8);
183
184
185
186
187/*
188 * Name: ext_yahoo_got_conf_invite
189 *      Called when remote user sends you a conference invitation.
190 * Params:
191 *      id   - the id that identifies the server connection
192 *      who  - the user inviting you
193 *      room - the room to join
194 *      msg  - the message
195 *      members - the initial members of the conference (null terminated list)
196 */
197void YAHOO_CALLBACK_TYPE(ext_yahoo_got_conf_invite)(int id, char *who, char *room, char *msg, YList *members);
198
199
200
201
202/*
203 * Name: ext_yahoo_conf_userdecline
204 *      Called when someone declines to join the conference.
205 * Params:
206 *      id   - the id that identifies the server connection
207 *      who  - the user who has declined
208 *      room - the room
209 *      msg  - the declining message
210 */
211void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userdecline)(int id, char *who, char *room, char *msg);
212
213
214
215
216/*
217 * Name: ext_yahoo_conf_userjoin
218 *      Called when someone joins the conference.
219 * Params:
220 *      id   - the id that identifies the server connection
221 *      who  - the user who has joined
222 *      room - the room joined
223 */
224void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userjoin)(int id, char *who, char *room);
225
226
227
228
229/*
230 * Name: ext_yahoo_conf_userleave
231 *      Called when someone leaves the conference.
232 * Params:
233 *      id   - the id that identifies the server connection
234 *      who  - the user who has left
235 *      room - the room left
236 */
237void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userleave)(int id, char *who, char *room);
238
239
240
241
242
243
244/*
245 * Name: ext_yahoo_chat_cat_xml
246 *      Called when joining the chatroom.
247 * Params:
248 *      id      - the id that identifies the server connection
249 *      room    - the room joined, used in all other chat calls, freed by
250 *                library after call
251 *      topic   - the topic of the room, freed by library after call
252 *      members - the initial members of the chatroom (null terminated YList of
253 *                yahoo_chat_member's) Must be freed by the client
254 */
255void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_cat_xml)(int id, char *xml);
256
257
258
259
260
261
262
263/*
264 * Name: ext_yahoo_chat_join
265 *      Called when joining the chatroom.
266 * Params:
267 *      id      - the id that identifies the server connection
268 *      room    - the room joined, used in all other chat calls, freed by
269 *                library after call
270 *      topic   - the topic of the room, freed by library after call
271 *      members - the initial members of the chatroom (null terminated YList
272 *                of yahoo_chat_member's) Must be freed by the client
273 *      fd      - the socket where the connection is coming from (for tracking)
274 */
275void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_join)(int id, char *room, char *topic, YList *members, int fd);
276
277
278
279
280
281
282/*
283 * Name: ext_yahoo_chat_userjoin
284 *      Called when someone joins the chatroom.
285 * Params:
286 *      id   - the id that identifies the server connection
287 *      room - the room joined
288 *      who  - the user who has joined, Must be freed by the client
289 */
290void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_userjoin)(int id, char *room, struct yahoo_chat_member *who);
291
292
293
294
295/*
296 * Name: ext_yahoo_chat_userleave
297 *      Called when someone leaves the chatroom.
298 * Params:
299 *      id   - the id that identifies the server connection
300 *      room - the room left
301 *      who  - the user who has left (Just the User ID)
302 */
303void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_userleave)(int id, char *room, char *who);
304
305
306
307
308/*
309 * Name: ext_yahoo_chat_message
310 *      Called when someone messages in the chatroom.
311 * Params:
312 *      id   - the id that identifies the server connection
313 *      room - the room
314 *      who  - the user who messaged (Just the user id)
315 *      msg  - the message
316 *      msgtype  - 1 = Normal message
317 *                 2 = /me type message
318 *      utf8 - whether the message is utf8 encoded or not
319 */
320void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_message)(int id, char *who, char *room, char *msg, int msgtype, int utf8);
321
322/*
323 *
324 * Name: ext_yahoo_chat_yahoologout
325 *      called when yahoo disconnects your chat session
326 *      Note this is called whenver a disconnect happens, client or server
327 *      requested. Care should be taken to make sure you know the origin
328 *      of the disconnect request before doing anything here (auto-join's etc)
329 * Params:
330 *      id   - the id that identifies this connection
331 * Returns:
332 *      nothing.
333 */
334void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_yahoologout)(int id);
335
336/*
337 *
338 * Name: ext_yahoo_chat_yahooerror
339 *      called when yahoo sends back an error to you
340 *      Note this is called whenver chat message is sent into a room
341 *      in error (fd not connected, room doesn't exists etc)
342 *      Care should be taken to make sure you know the origin
343 *      of the error before doing anything about it.
344 * Params:
345 *      id   - the id that identifies this connection
346 * Returns:
347 *      nothing.
348 */
349
350void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_yahooerror)(int id);
351
352/*
353 * Name: ext_yahoo_conf_message
354 *      Called when someone messages in the conference.
355 * Params:
356 *      id   - the id that identifies the server connection
357 *      who  - the user who messaged
358 *      room - the room
359 *      msg  - the message
360 *      utf8 - whether the message is utf8 encoded or not
361 */
362void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_message)(int id, char *who, char *room, char *msg, int utf8);
363
364
365
366
367/*
368 * Name: ext_yahoo_got_file
369 *      Called when someone sends you a file
370 * Params:
371 *      id   - the id that identifies the server connection
372 *      who  - the user who sent the file
373 *      url  - the file url
374 *      expires  - the expiry date of the file on the server (timestamp)
375 *      msg  - the message
376 *      fname- the file name if direct transfer
377 *      fsize- the file size if direct transfer
378 */
379void YAHOO_CALLBACK_TYPE(ext_yahoo_got_file)(int id, char *who, char *url, long expires, char *msg, char *fname, unsigned long fesize);
380
381
382
383
384/*
385 * Name: ext_yahoo_contact_added
386 *      Called when a contact is added to your list
387 * Params:
388 *      id   - the id that identifies the server connection
389 *      myid - the identity he was added to
390 *      who  - who was added
391 *      msg  - any message sent
392 */
393void YAHOO_CALLBACK_TYPE(ext_yahoo_contact_added)(int id, char *myid, char *who, char *msg);
394
395
396
397
398/*
399 * Name: ext_yahoo_rejected
400 *      Called when a contact rejects your add
401 * Params:
402 *      id   - the id that identifies the server connection
403 *      who  - who rejected you
404 *      msg  - any message sent
405 */
406void YAHOO_CALLBACK_TYPE(ext_yahoo_rejected)(int id, char *who, char *msg);
407
408
409
410
411/*
412 * Name: ext_yahoo_typing_notify
413 *      Called when remote user starts or stops typing.
414 * Params:
415 *      id   - the id that identifies the server connection
416 *      who  - the handle of the remote user
417 *      stat - 1 if typing, 0 if stopped typing
418 */
419void YAHOO_CALLBACK_TYPE(ext_yahoo_typing_notify)(int id, char *who, int stat);
420
421
422
423
424/*
425 * Name: ext_yahoo_game_notify
426 *      Called when remote user starts or stops a game.
427 * Params:
428 *      id   - the id that identifies the server connection
429 *      who  - the handle of the remote user
430 *      stat - 1 if game, 0 if stopped gaming
431 */
432void YAHOO_CALLBACK_TYPE(ext_yahoo_game_notify)(int id, char *who, int stat);
433
434
435
436
437/*
438 * Name: ext_yahoo_mail_notify
439 *      Called when you receive mail, or with number of messages
440 * Params:
441 *      id   - the id that identifies the server connection
442 *      from - who the mail is from - NULL if only mail count
443 *      subj - the subject of the mail - NULL if only mail count
444 *      cnt  - mail count - 0 if new mail notification
445 */
446void YAHOO_CALLBACK_TYPE(ext_yahoo_mail_notify)(int id, char *from, char *subj, int cnt);
447
448
449
450
451/*
452 * Name: ext_yahoo_system_message
453 *      System message
454 * Params:
455 *      id   - the id that identifies the server connection
456 *      msg  - the message
457 */
458void YAHOO_CALLBACK_TYPE(ext_yahoo_system_message)(int id, char *msg);
459
460
461
462
463
464
465
466
467
468
469
470/*
471 * Name: ext_yahoo_got_webcam_image
472 *      Called when you get a webcam update
473 *      An update can either be receiving an image, a part of an image or
474 *      just an update with a timestamp
475 * Params:
476 *      id         - the id that identifies the server connection
477 *      who        - the user who's webcam we're viewing
478 *      image      - image data
479 *      image_size - length of the image in bytes
480 *      real_size  - actual length of image data
481 *      timestamp  - milliseconds since the webcam started
482 *
483 *      If the real_size is smaller then the image_size then only part of
484 *      the image has been read. This function will keep being called till
485 *      the total amount of bytes in image_size has been read. The image
486 *      received is in JPEG-2000 Code Stream Syntax (ISO/IEC 15444-1).
487 *      The size of the image will be either 160x120 or 320x240.
488 *      Each webcam image contains a timestamp. This timestamp should be
489 *      used to keep the image in sync since some images can take longer
490 *      to transport then others. When image_size is 0 we can still receive
491 *      a timestamp to stay in sync
492 */
493void YAHOO_CALLBACK_TYPE(ext_yahoo_got_webcam_image)(int id, const char * who,
494                const unsigned char *image, unsigned int image_size, unsigned int real_size,
495                unsigned int timestamp);
496
497
498
499
500/*
501 * Name: ext_yahoo_webcam_invite
502 *      Called when you get a webcam invitation
503 * Params:
504 *      id   - the id that identifies the server connection
505 *      from - who the invitation is from
506 */
507void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_invite)(int id, char *from);
508
509
510
511
512/*
513 * Name: ext_yahoo_webcam_invite_reply
514 *      Called when you get a response to a webcam invitation
515 * Params:
516 *      id   - the id that identifies the server connection
517 *      from - who the invitation response is from
518 *      accept - 0 (decline), 1 (accept)
519 */
520void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_invite_reply)(int id, char *from, int accept);
521
522
523
524/*
525 * Name: ext_yahoo_webcam_closed
526 *      Called when the webcam connection closed
527 * Params:
528 *      id   - the id that identifies the server connection
529 *      who  - the user who we where connected to
530 *      reason - reason why the connection closed
531 *               1 = user stopped broadcasting
532 *               2 = user cancelled viewing permission
533 *               3 = user declines permission
534 *               4 = user does not have webcam online
535 */
536void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_closed)(int id, char *who, int reason);
537
538
539/*
540 * Name: ext_yahoo_got_search_result
541 *      Called when the search result received from server
542 * Params:
543 *      id       - the id that identifies the server connection
544 *      found    - total number of results returned in the current result set
545 *      start    - offset from where the current result set starts
546 *      total    - total number of results available (start + found <= total)
547 *      contacts - the list of results as a YList of yahoo_found_contact
548 *                 these will be freed after this function returns, so
549 *                 if you need to use the information, make a copy
550 */
551void YAHOO_CALLBACK_TYPE(ext_yahoo_got_search_result)(int id, int found, int start, int total, YList *contacts);
552
553
554
555/*
556 * Name: ext_yahoo_error
557 *      Called on error.
558 * Params:
559 *      id   - the id that identifies the server connection
560 *      err  - the error message
561 *      fatal- whether this error is fatal to the connection or not
562 */
563void YAHOO_CALLBACK_TYPE(ext_yahoo_error)(int id, char *err, int fatal);
564
565
566
567
568/*
569 * Name: ext_yahoo_webcam_viewer
570 *      Called when a viewer disconnects/connects/requests to connect
571 * Params:
572 *      id  - the id that identifies the server connection
573 *      who - the viewer
574 *      connect - 0=disconnect 1=connect 2=request
575 */
576void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_viewer)(int id, char *who, int connect);
577
578
579
580
581/*
582 * Name: ext_yahoo_webcam_data_request
583 *      Called when you get a request for webcam images
584 * Params:
585 *      id   - the id that identifies the server connection
586 *      send - whether to send images or not
587 */
588void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_data_request)(int id, int send);
589
590
591
592
593/*
594 * Name: ext_yahoo_log
595 *      Called to log a message.
596 * Params:
597 *      fmt  - the printf formatted message
598 * Returns:
599 *      0
600 */
601int YAHOO_CALLBACK_TYPE(ext_yahoo_log)(char *fmt, ...);
602
603
604
605
606
607
608
609
610/*
611 * Name: ext_yahoo_add_handler
612 *      Add a listener for the fd.  Must call yahoo_read_ready
613 *      when a YAHOO_INPUT_READ fd is ready and yahoo_write_ready
614 *      when a YAHOO_INPUT_WRITE fd is ready.
615 * Params:
616 *      id   - the id that identifies the server connection
617 *      fd   - the fd on which to listen
618 *      cond - the condition on which to call the callback
619 *      data - callback data to pass to yahoo_*_ready
620 *     
621 * Returns: a tag to be used when removing the handler
622 */
623int YAHOO_CALLBACK_TYPE(ext_yahoo_add_handler)(int id, int fd, yahoo_input_condition cond, void *data);
624
625
626
627
628/*
629 * Name: ext_yahoo_remove_handler
630 *      Remove the listener for the fd.
631 * Params:
632 *      id   - the id that identifies the connection
633 *      tag  - the handler tag to remove
634 */
635void YAHOO_CALLBACK_TYPE(ext_yahoo_remove_handler)(int id, int tag);
636
637
638
639
640
641/*
642 * Name: ext_yahoo_connect
643 *      Connect to a host:port
644 * Params:
645 *      host - the host to connect to
646 *      port - the port to connect on
647 * Returns:
648 *      a unix file descriptor to the socket
649 */
650int YAHOO_CALLBACK_TYPE(ext_yahoo_connect)(char *host, int port);
651
652
653
654
655
656
657
658
659/*
660 * Name: ext_yahoo_connect_async
661 *      Connect to a host:port asynchronously.  This function should return
662 *      immediately returing a tag used to identify the connection handler,
663 *      or a pre-connect error (eg: host name lookup failure).
664 *      Once the connect completes (successfully or unsuccessfully), callback
665 *      should be called (see the signature for yahoo_connect_callback).
666 *      The callback may safely be called before this function returns, but
667 *      it should not be called twice.
668 * Params:
669 *      id   - the id that identifies this connection
670 *      host - the host to connect to
671 *      port - the port to connect on
672 *      callback - function to call when connect completes
673 *      callback_data - data to pass to the callback function
674 * Returns:
675 *      a unix file descriptor to the socket
676 */
677int YAHOO_CALLBACK_TYPE(ext_yahoo_connect_async)(int id, char *host, int port, 
678                yahoo_connect_callback callback, void *callback_data);
679
680#ifdef USE_STRUCT_CALLBACKS
681};
682
683/*
684 * if using a callback structure, call yahoo_register_callbacks
685 * before doing anything else
686 */
687void yahoo_register_callbacks(struct yahoo_callbacks * tyc);
688       
689#undef YAHOO_CALLBACK_TYPE
690
691#endif
692
693#ifdef __cplusplus
694}
695#endif
696
697#endif
Note: See TracBrowser for help on using the repository browser.