source: protocols/yahoo/yahoo2_callbacks.h @ ca0981a

/*
 * libyahoo2: yahoo2_callbacks.h
 *
 * Copyright (C) 2002-2004, Philip S Tellis <philip.tellis AT gmx.net>
 *
 * 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