source: protocols/yahoo/yahoo2_callbacks.h @ d11dd2f

Last change on this file since d11dd2f was cfc8d58, checked in by Wilmer van der Gaast <wilmer@…>, at 2007-04-16T04:31:52Z

Updating the Yahoo! module. This seems to fix handling of incoming away
states/messages, should fix some issues with group chats, and unfortunately
also adds some crap which I don't want to clean up for now.

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