/* * libyahoo2: yahoo2_callbacks.h * * Copyright (C) 2002-2004, Philip S Tellis * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * */ /* * The functions in this file *must* be defined in your client program * If you want to use a callback structure instead of direct functions, * then you must define USE_STRUCT_CALLBACKS in all files that #include * this one. * * Register the callback structure by calling yahoo_register_callbacks - * declared in this file and defined in libyahoo2.c */ #ifndef YAHOO2_CALLBACKS_H #define YAHOO2_CALLBACKS_H #ifdef __cplusplus extern "C" { #endif #include "yahoo2_types.h" /* * yahoo2_callbacks.h * * Callback interface for libyahoo2 */ typedef enum { YAHOO_INPUT_READ = 1 << 0, YAHOO_INPUT_WRITE = 1 << 1, YAHOO_INPUT_EXCEPTION = 1 << 2 } yahoo_input_condition; /* * A callback function called when an asynchronous connect completes. * * Params: * fd - The file descriptor that has been connected, or -1 on error * error - The value of errno set by the call to connect or 0 if no error * Set both fd and error to 0 if the connect was cancelled by the * user * callback_data - the callback_data passed to the ext_yahoo_connect_async * function */ typedef void (*yahoo_connect_callback)(int fd, int error, void *callback_data); /* * The following functions need to be implemented in the client * interface. They will be called by the library when each * event occurs. */ /* * should we use a callback structure or directly call functions * if you want the structure, you *must* define USE_STRUCT_CALLBACKS * both when you compile the library, and when you compile your code * that uses the library */ #ifdef USE_STRUCT_CALLBACKS #define YAHOO_CALLBACK_TYPE(x) (*x) struct yahoo_callbacks { #else #define YAHOO_CALLBACK_TYPE(x) x #endif /* * Name: ext_yahoo_login_response * Called when the login process is complete * Params: * id - the id that identifies the server connection * succ - enum yahoo_login_status * url - url to reactivate account if locked */ void YAHOO_CALLBACK_TYPE(ext_yahoo_login_response)(int id, int succ, const char *url); /* * Name: ext_yahoo_got_buddies * Called when the contact list is got from the server * Params: * id - the id that identifies the server connection * buds - the buddy list */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_buddies)(int id, YList * buds); /* * Name: ext_yahoo_got_ignore * Called when the ignore list is got from the server * Params: * id - the id that identifies the server connection * igns - the ignore list */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_ignore)(int id, YList * igns); /* * Name: ext_yahoo_got_identities * Called when the contact list is got from the server * Params: * id - the id that identifies the server connection * ids - the identity list */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_identities)(int id, YList * ids); /* * Name: ext_yahoo_got_cookies * Called when the cookie list is got from the server * Params: * id - the id that identifies the server connection */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_cookies)(int id); /* * Name: ext_yahoo_got_ping * Called when the ping packet is received from the server * Params: * id - the id that identifies the server connection * errormsg - optional error message */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_ping)(int id, const char *errormsg); /* * Name: ext_yahoo_status_changed * Called when remote user's status changes. * Params: * id - the id that identifies the server connection * who - the handle of the remote user * stat - status code (enum yahoo_status) * msg - the message if stat == YAHOO_STATUS_CUSTOM * away - whether the contact is away or not (YAHOO_STATUS_CUSTOM) * idle - this is the number of seconds he is idle [if he is idle] * mobile - this is set for mobile users/buddies * TODO: add support for pager, chat, and game states */ void YAHOO_CALLBACK_TYPE(ext_yahoo_status_changed)(int id, const char *who, int stat, const char *msg, int away, int idle, int mobile); /* * Name: ext_yahoo_got_im * Called when remote user sends you a message. * Params: * id - the id that identifies the server connection * me - the identity the message was sent to * who - the handle of the remote user * msg - the message - NULL if stat == 2 * tm - timestamp of message if offline * stat - message status - 0 * 1 * 2 == error sending message * 5 * utf8 - whether the message is encoded as utf8 or not */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_im)(int id, const char *me, const char *who, const char *msg, long tm, int stat, int utf8); /* * Name: ext_yahoo_got_conf_invite * Called when remote user sends you a conference invitation. * Params: * id - the id that identifies the server connection * me - the identity the invitation was sent to * who - the user inviting you * room - the room to join * msg - the message * members - the initial members of the conference (null terminated list) */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_conf_invite)(int id, const char *me, const char *who, const char *room, const char *msg, YList *members); /* * Name: ext_yahoo_conf_userdecline * Called when someone declines to join the conference. * Params: * id - the id that identifies the server connection * me - the identity in the conference * who - the user who has declined * room - the room * msg - the declining message */ void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userdecline)(int id, const char *me, const char *who, const char *room, const char *msg); /* * Name: ext_yahoo_conf_userjoin * Called when someone joins the conference. * Params: * id - the id that identifies the server connection * me - the identity in the conference * who - the user who has joined * room - the room joined */ void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userjoin)(int id, const char *me, const char *who, const char *room); /* * Name: ext_yahoo_conf_userleave * Called when someone leaves the conference. * Params: * id - the id that identifies the server connection * me - the identity in the conference * who - the user who has left * room - the room left */ void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_userleave)(int id, const char *me, const char *who, const char *room); /* * Name: ext_yahoo_chat_cat_xml * Called when ? * Params: * id - the id that identifies the server connection * xml - ? */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_cat_xml)(int id, const char *xml); /* * Name: ext_yahoo_chat_join * Called when joining the chatroom. * Params: * id - the id that identifies the server connection * me - the identity in the chatroom * room - the room joined, used in all other chat calls, freed by * library after call * topic - the topic of the room, freed by library after call * members - the initial members of the chatroom (null terminated YList * of yahoo_chat_member's) Must be freed by the client * fd - the socket where the connection is coming from (for tracking) */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_join)(int id, const char *me, const char *room, const char *topic, YList *members, int fd); /* * Name: ext_yahoo_chat_userjoin * Called when someone joins the chatroom. * Params: * id - the id that identifies the server connection * me - the identity in the chatroom * room - the room joined * who - the user who has joined, Must be freed by the client */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_userjoin)(int id, const char *me, const char *room, struct yahoo_chat_member *who); /* * Name: ext_yahoo_chat_userleave * Called when someone leaves the chatroom. * Params: * id - the id that identifies the server connection * me - the identity in the chatroom * room - the room left * who - the user who has left (Just the User ID) */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_userleave)(int id, const char *me, const char *room, const char *who); /* * Name: ext_yahoo_chat_message * Called when someone messages in the chatroom. * Params: * id - the id that identifies the server connection * me - the identity in the chatroom * room - the room * who - the user who messaged (Just the user id) * msg - the message * msgtype - 1 = Normal message * 2 = /me type message * utf8 - whether the message is utf8 encoded or not */ void 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); /* * * Name: ext_yahoo_chat_yahoologout * called when yahoo disconnects your chat session * Note this is called whenver a disconnect happens, client or server * requested. Care should be taken to make sure you know the origin * of the disconnect request before doing anything here (auto-join's etc) * Params: * id - the id that identifies this connection * me - the identity in the chatroom * Returns: * nothing. */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_yahoologout)(int id, const char *me); /* * * Name: ext_yahoo_chat_yahooerror * called when yahoo sends back an error to you * Note this is called whenver chat message is sent into a room * in error (fd not connected, room doesn't exists etc) * Care should be taken to make sure you know the origin * of the error before doing anything about it. * Params: * id - the id that identifies this connection * me - the identity in the chatroom * Returns: * nothing. */ void YAHOO_CALLBACK_TYPE(ext_yahoo_chat_yahooerror)(int id, const char *me); /* * Name: ext_yahoo_conf_message * Called when someone messages in the conference. * Params: * id - the id that identifies the server connection * me - the identity the conf message was sent to * who - the user who messaged * room - the room * msg - the message * utf8 - whether the message is utf8 encoded or not */ void YAHOO_CALLBACK_TYPE(ext_yahoo_conf_message)(int id, const char *me, const char *who, const char *room, const char *msg, int utf8); /* * Name: ext_yahoo_got_file * Called when someone sends you a file * Params: * id - the id that identifies the server connection * me - the identity the file was sent to * who - the user who sent the file * url - the file url * expires - the expiry date of the file on the server (timestamp) * msg - the message * fname- the file name if direct transfer * fsize- the file size if direct transfer */ void 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); /* * Name: ext_yahoo_contact_auth_request * Called when a contact wants to add you to his/her contact list * Params: * id - the id that identifies the server connection * myid - the identity s/he added * who - who did it * msg - any message sent */ void YAHOO_CALLBACK_TYPE(ext_yahoo_contact_auth_request)(int id, const char *myid, const char *who, const char *msg); /* * Name: ext_yahoo_contact_added * Called when a contact is added to your list * Params: * id - the id that identifies the server connection * myid - the identity he was added to * who - who was added * msg - any message sent */ void YAHOO_CALLBACK_TYPE(ext_yahoo_contact_added)(int id, const char *myid, const char *who, const char *msg); /* * Name: ext_yahoo_rejected * Called when a contact rejects your add * Params: * id - the id that identifies the server connection * who - who rejected you * msg - any message sent */ void YAHOO_CALLBACK_TYPE(ext_yahoo_rejected)(int id, const char *who, const char *msg); /* * Name: ext_yahoo_typing_notify * Called when remote user starts or stops typing. * Params: * id - the id that identifies the server connection * me - the handle of the identity the notification is sent to * who - the handle of the remote user * stat - 1 if typing, 0 if stopped typing */ void YAHOO_CALLBACK_TYPE(ext_yahoo_typing_notify)(int id, const char *me, const char *who, int stat); /* * Name: ext_yahoo_game_notify * Called when remote user starts or stops a game. * Params: * id - the id that identifies the server connection * me - the handle of the identity the notification is sent to * who - the handle of the remote user * stat - 1 if game, 0 if stopped gaming */ void YAHOO_CALLBACK_TYPE(ext_yahoo_game_notify)(int id, const char *me, const char *who, int stat); /* * Name: ext_yahoo_mail_notify * Called when you receive mail, or with number of messages * Params: * id - the id that identifies the server connection * from - who the mail is from - NULL if only mail count * subj - the subject of the mail - NULL if only mail count * cnt - mail count - 0 if new mail notification */ void YAHOO_CALLBACK_TYPE(ext_yahoo_mail_notify)(int id, const char *from, const char *subj, int cnt); /* * Name: ext_yahoo_system_message * System message * Params: * id - the id that identifies the server connection * msg - the message */ void YAHOO_CALLBACK_TYPE(ext_yahoo_system_message)(int id, const char *msg); /* * Name: ext_yahoo_got_buddyicon * Buddy icon received * Params: * id - the id that identifies the server connection * me - the handle of the identity the notification is sent to * who - the person the buddy icon is for * url - the url to use to load the icon * checksum - the checksum of the icon content */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_buddyicon)(int id, const char *me, const char *who, const char *url, int checksum); /* * Name: ext_yahoo_got_buddyicon_checksum * Buddy icon checksum received * Params: * id - the id that identifies the server connection * me - the handle of the identity the notification is sent to * who - the yahoo id of the buddy icon checksum is for * checksum - the checksum of the icon content */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_buddyicon_checksum)(int id, const char *me,const char *who, int checksum); /* * Name: ext_yahoo_got_buddyicon_request * Buddy icon request received * Params: * id - the id that identifies the server connection * me - the handle of the identity the notification is sent to * who - the yahoo id of the buddy that requested the buddy icon */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_buddyicon_request)(int id, const char *me, const char *who); /* * Name: ext_yahoo_got_buddyicon_request * Buddy icon request received * Params: * id - the id that identifies the server connection * url - remote url, the uploaded buddy icon can be fetched from */ void YAHOO_CALLBACK_TYPE(ext_yahoo_buddyicon_uploaded)(int id, const char *url); /* * Name: ext_yahoo_got_webcam_image * Called when you get a webcam update * An update can either be receiving an image, a part of an image or * just an update with a timestamp * Params: * id - the id that identifies the server connection * who - the user who's webcam we're viewing * image - image data * image_size - length of the image in bytes * real_size - actual length of image data * timestamp - milliseconds since the webcam started * * If the real_size is smaller then the image_size then only part of * the image has been read. This function will keep being called till * the total amount of bytes in image_size has been read. The image * received is in JPEG-2000 Code Stream Syntax (ISO/IEC 15444-1). * The size of the image will be either 160x120 or 320x240. * Each webcam image contains a timestamp. This timestamp should be * used to keep the image in sync since some images can take longer * to transport then others. When image_size is 0 we can still receive * a timestamp to stay in sync */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_webcam_image)(int id, const char * who, const unsigned char *image, unsigned int image_size, unsigned int real_size, unsigned int timestamp); /* * Name: ext_yahoo_webcam_invite * Called when you get a webcam invitation * Params: * id - the id that identifies the server connection * me - identity the invitation is to * from - who the invitation is from */ void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_invite)(int id, const char *me, const char *from); /* * Name: ext_yahoo_webcam_invite_reply * Called when you get a response to a webcam invitation * Params: * id - the id that identifies the server connection * me - identity the invitation response is to * from - who the invitation response is from * accept - 0 (decline), 1 (accept) */ void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_invite_reply)(int id, const char *me, const char *from, int accept); /* * Name: ext_yahoo_webcam_closed * Called when the webcam connection closed * Params: * id - the id that identifies the server connection * who - the user who we where connected to * reason - reason why the connection closed * 1 = user stopped broadcasting * 2 = user cancelled viewing permission * 3 = user declines permission * 4 = user does not have webcam online */ void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_closed)(int id, const char *who, int reason); /* * Name: ext_yahoo_got_search_result * Called when the search result received from server * Params: * id - the id that identifies the server connection * found - total number of results returned in the current result set * start - offset from where the current result set starts * total - total number of results available (start + found <= total) * contacts - the list of results as a YList of yahoo_found_contact * these will be freed after this function returns, so * if you need to use the information, make a copy */ void YAHOO_CALLBACK_TYPE(ext_yahoo_got_search_result)(int id, int found, int start, int total, YList *contacts); /* * Name: ext_yahoo_error * Called on error. * Params: * id - the id that identifies the server connection * err - the error message * fatal- whether this error is fatal to the connection or not * num - Which error is this */ void YAHOO_CALLBACK_TYPE(ext_yahoo_error)(int id, const char *err, int fatal, int num); /* * Name: ext_yahoo_webcam_viewer * Called when a viewer disconnects/connects/requests to connect * Params: * id - the id that identifies the server connection * who - the viewer * connect - 0=disconnect 1=connect 2=request */ void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_viewer)(int id, const char *who, int connect); /* * Name: ext_yahoo_webcam_data_request * Called when you get a request for webcam images * Params: * id - the id that identifies the server connection * send - whether to send images or not */ void YAHOO_CALLBACK_TYPE(ext_yahoo_webcam_data_request)(int id, int send); /* * Name: ext_yahoo_log * Called to log a message. * Params: * fmt - the printf formatted message * Returns: * 0 */ int YAHOO_CALLBACK_TYPE(ext_yahoo_log)(const char *fmt, ...); /* * Name: ext_yahoo_add_handler * Add a listener for the fd. Must call yahoo_read_ready * when a YAHOO_INPUT_READ fd is ready and yahoo_write_ready * when a YAHOO_INPUT_WRITE fd is ready. * Params: * id - the id that identifies the server connection * fd - the fd on which to listen * cond - the condition on which to call the callback * data - callback data to pass to yahoo_*_ready * * Returns: a tag to be used when removing the handler */ int YAHOO_CALLBACK_TYPE(ext_yahoo_add_handler)(int id, int fd, yahoo_input_condition cond, void *data); /* * Name: ext_yahoo_remove_handler * Remove the listener for the fd. * Params: * id - the id that identifies the connection * tag - the handler tag to remove */ void YAHOO_CALLBACK_TYPE(ext_yahoo_remove_handler)(int id, int tag); /* * Name: ext_yahoo_connect * Connect to a host:port * Params: * host - the host to connect to * port - the port to connect on * Returns: * a unix file descriptor to the socket */ int YAHOO_CALLBACK_TYPE(ext_yahoo_connect)(const char *host, int port); /* * Name: ext_yahoo_connect_async * Connect to a host:port asynchronously. This function should return * immediately returing a tag used to identify the connection handler, * or a pre-connect error (eg: host name lookup failure). * Once the connect completes (successfully or unsuccessfully), callback * should be called (see the signature for yahoo_connect_callback). * The callback may safely be called before this function returns, but * it should not be called twice. * Params: * id - the id that identifies this connection * host - the host to connect to * port - the port to connect on * callback - function to call when connect completes * callback_data - data to pass to the callback function * Returns: * a unix file descriptor to the socket */ int YAHOO_CALLBACK_TYPE(ext_yahoo_connect_async)(int id, const char *host, int port, yahoo_connect_callback callback, void *callback_data); #ifdef USE_STRUCT_CALLBACKS }; /* * if using a callback structure, call yahoo_register_callbacks * before doing anything else */ void yahoo_register_callbacks(struct yahoo_callbacks * tyc); #undef YAHOO_CALLBACK_TYPE #endif #ifdef __cplusplus } #endif #endif