README for libyahoo2 ==================== * Using the library Ok, here's a short, quick intro on how to use the library. Full documentation will come later. First include the two headers. #include #include yahoo2.h contains functions that you can call. The data structures used are defined in yahoo2_types.h, which is included by yahoo2.h yahoo2_callbacks.h contains prototypes for functions that you *must* implement. *All* these functions must be implemented by your code. You can choose at configure time whether these are implemented as callback functions or as a callback structure. If compiled as a callback structure, you must call yahoo_register_callbacks before doing anything else. What each function is supposed to do and return is documented in yahoo2_callbacks.h Ok, assuming you've implemented all those functions to do what they're supposed to do, this is the process flow: 1. Login Before logging in, you must initialise the connection by calling yahoo_init and passing the username and password of the account. yahoo_init returns a connection id that will be used to identify this connection for all other calls. You may use yahoo_init_with_attributes if you need to set any server settings. int yahoo_init(const char *username, const char *password); int yahoo_init_with_attributes(const char *username, const char *password, ...); The optional parameters to init are key/value pairs that specify server settings to use. This list must be NULL terminated - even if the list is empty. If a parameter isn't set, a default value will be used. Parameter keys are strings, parameter values are either strings or ints, depending on the key. Values passed in are copied, so you can use const/auto/static/ pointers/whatever you want. Parameters are: NAME TYPE DEFAULT DESCRIPTION ------------------- ------- --------------------------- -------------- pager_host char * scs.msg.yahoo.com pager_port int 5050 filetransfer_host char * filetransfer.msg.yahoo.com filetransfer_port int 80 webcam_host char * webcam.yahoo.com webcam_port int 5100 webcam_description char * "" Webcam description local_host char * "" local IP address regardless of whether you're behind a firewall or not conn_type int Y_WCM_DSL see yahoo2_types.h You should set at least local_host if you intend to use webcams yahoo_init uses default values for all of the above. Remember to close the connection by calling yahoo_close when you no longer need it. This will free all resources allocated to the connection. void yahoo_close(int id); After initialising, you may call yahoo_login, with the id and the initial login status. void yahoo_login(int id, int initial); The initial status is one of enum yahoo_status (NOTE, only INVISIBLE and ONLINE are known to work at all times). When the login procedure is complete, the library will call ext_yahoo_login_response with a status code. See yahoo2_types for an enumeration of these codes. The buddy list and cookies will not be available at the time when ext_yahoo_login_response is called. You should wait for ext_yahoo_got_buddies and ext_yahoo_got_cookies. 2. Buddies and Addressbook When the library receives the buddy list from the server, it will call ext_yahoo_got_buddies with the buddy list as a parameter. The library will call ext_yahoo_got_ignore when it receives the ignore list. - To get the buddy list at any other time, make a call to yahoo_get_buddylist, and use the return value of that call. - Similarly, for the ignorelist, call yahoo_get_ignorelist. These lists will be returned from the library's cache. To force a reload from the server, make a call to yahoo_get_list. Buddy nicknames and other contact information is stored in your yahoo address book. To retrieve this information, call yahoo_get_yab. call yahoo_set_yab to create or modify an addressbook entry. Call these functions only after ext_yahoo_got_cookies has been called. - To refresh the status of all buddies, make a call to yahoo_refresh. - To add a buddy, call yahoo_add_buddy: void yahoo_add_buddy(id, char *who, char *group); You can add a buddy to multiple groups by calling this function once for each group. - To remove a buddy, call yahoo_remove_buddy: void yahoo_remove_buddy(id, char *who, char *group); Remove buddy removes the buddy from the specified group. To completely remove a buddy, call this function for all groups that the buddy is in. - If a buddy adds you, and you do nothing, that buddy is accpeted (that's the way the protocol works). If you want to reject the buddy, make a call to yahoo_reject_buddy: void yahoo_reject_buddy(id, char * who, char *msg); where msg is the rejection message. - To change a buddy's group, call yahoo_change_buddy_group: void yahoo_change_buddy_group(id, char * who, char *old_group, char *new_group); - To ignore/unignore a buddy, call yahoo_ignore_buddy: void yahoo_ignore_buddy(id, char *who, int unignore); If unignore is TRUE, the buddy is unignored, if it is FALSE, the buddy is ignored. - You can also rename a group with: void yahoo_group_rename(id, char *old_group, char *new_group); 3. Sending an IM To send an IM, make a call to yahoo_send_im void yahoo_send_im(int id, char * from, char *who, char *what, int utf8); id is the id that the connection is identified with, who is who you want to message, what is the message to be sent. The parameter from is the identity that you want to use to send the message. If this is NULL, your default identity will be used. utf8 is a boolean field that specifies whether the message you're sending has been encoded in utf8 or not. libyahoo2 will not do the encoding for you - you have to do it yourself. You may use the utility functions y_str_to_utf8 and y_utf8_to_str in yahoo_util to do this encoding. You must free the pointers returned by these functions. UTF8 encoding may also be used in messages received. It is not sent or received for invitations/rejection messages. You can also send typing notifications with yahoo_send_typing. 4. Changing your status To change your status on the server, call yahoo_set_away. void yahoo_set_away(id, enum yahoo_status status, char *msg, int away); id is the identifying id, status is your new status. msg is a custom status message in case status == YAHOO_STATUS_CUSTOM and away is a flag that says whether the custom message is an away message or just a regular signature (this affects the kind of icon against your name in the official Yahoo Messenger client). 5. Conferencing To start a conference, call yahoo_conference_invite with a list of initial members, the room name, and a welcome message. To add more people to the conference after it has started, call yahoo_conference_addinvite. If someone adds you to the conference, you can either accept by calling yahoo_conference_logon, or decline by calling yahoo_conference_decline You can log off from the conference by calling yahoo_conference_logoff. Send a message by calling yahoo_conference_message. The parameter from is the identity that you want to use to send the message. If this is NULL, your default identity will be used. NOTE: Except for yahoo_conference_addinvite, all conference functions take the list of members as an argument. Have a look at yahoo2_callbacks.h for conference callbacks. Beware that there's a chance you could get a conf_userjoin even before you get an invitation to that conference. 6. File Transfer To send a file, call yahoo_send_file(id, who, msg, name, size). This will set up the initial file send connection and return a unix file descriptor that you must write to. You then write the file's contents to this fd. Receiving a file is similar. You will receive a call to ext_yahoo_got_file with the file's url as one of the parameters. When you are ready to start downloading the file, make a call to yahoo_get_url_handle: fd = yahoo_get_url_handle(id, url, &fname, &fsize); fname and fsize are used to store the file's name and size Yahoo's file transfer is implemented using HTTP. It can either be peer to peer or via the yahoo file transfer servers. The latter is used in case a peer to peer connection cannot be set up - for example, in the case of a firewall. libyahoo2 supports both types of file transfer for receiving, but only sends files using the yahoo file transfer server. If anyone's interested in implementing peer to peer file send, this is how it happens. First a PEERTOPEER packet is sent to check if it is possible. This will mark the connection between these two hosts as p2p compatible. No further PEERTOPEER packets will be sent between these two hosts for the duration that the connection is alive. After the first P2P packet, the initiater will start an HTTP server on some port (really any port), and send the url across to the other end. After this, the first host will always play the part of the server for all file transfers. If a transfer is from the server, it uses GET, if it is from the client to the server, it uses POST. There is no encoding used for POST. You'll still have to study it a bit, but IMO the major complexity is in putting a http server in the lib, and whether we want to do that. 7. Webcam To make a request for a webcam feed, call yahoo_webcam_get_feed with the user's yahoo id. You call this function in response to someone's webcam invitation as well. void yahoo_webcam_get_feed(int id, const char *who); The response may take a while as there's a lot of work done from the time you make a request till the time you start receiving a feed. There is no feedback from the library during this time. The function returns immediately. To close an open feed, simply call yahoo_webcam_close_feed void yahoo_webcam_close_feed(int id, const char *who); NOTE: it is possible to have two open webcam feeds with a single user if you open a second without closing the first. Results are unpredictable if you call close on a non-unique id/who combination. Webcam broadcast has not been fully tested. To invite a user to view your webcam, call yahoo_webcam_invite with the user's yahoo_id void yahoo_webcam_invite(int id, const char *who); To close this user's connection, call yahoo_webcam_close_feed. To accept/reject a request from a user to view your webcam, call yahoo_webcam_accept_viewer: void yahoo_webcam_accept_viewer(int id, const char *who, int accept); accept may be 1 or 0. Consult yahoo2_callbacks for the callbacks that are called on webcam events. You will require to be able to decode jpeg2000 images to view the webcam feed. You could use a library like GraphicsMagick (BSD Licence) or jasper (possibly non-Free) to do this. 8. Yahoo Chat To retrieve a list of yahoo chatrooms, call yahoo_get_chatrooms. The response callback will return the xml for the chatrooms. You must parse this yourself. To log in to a chat room, call yahoo_chat_logon, and to log off, call yahoo_chat_logoff. To send a chat message, call yahoo_chat_message. Chatting is similar to conferencing. Consult yahoo2_callbacks.h for the list of chat callbacks. 9. Callbacks The library may request you to register io handlers using ext_yahoo_add_handler. Whenever an input condition occurs, you must call one of the callback functions. For a read condition, call yahoo_read_ready, for a write condition, call yahoo_write_ready. ext_yahoo_connect_async is an asynchronous connect call. It will register a callback function that must be called when the connect completes. This callback is of type yahoo_connect_callback. Consult yahoo2_callbacks.h for full details on what your async connect should return. You must also call yahoo_keepalive at regular intervals (10 minutes?) to keep the connection alive. 10. Identities libyahoo2 will now get your identities from the server (if you don't know what that is, then you aren't using it). Use yahoo_get_identities to get your list of identities. libyahoo2 will also call ext_got_identities when it first gets the list of identities. To activate/deactivate an identity, call yahoo_set_identity_status: yahoo_set_identity_status(id, char * identity, int active); If active is non-zero, activate the identity, else deactivate it. If you try to activate/deactivate an identity that isn't yours, you'll get a call back to ext_yahoo_error with a custom error message. This message is from the yahoo servers. Don't complain to me about it. I know it sucks that we can't do translation of these strings. 11. Search To search for contacts, use the two functions: yahoo_search(id, type, text, gender, agerange, photo, yahoo_only); and yahoo_search_again(id, int start); The first is used for a first time search. Check yahoo2_types.h for valid values for each of the parameters. text is a text string to search for. The search results are returned through ext_yahoo_got_search_result. Results are limited to 20 per query, so if you want to continue the search, call yahoo_search_again to get 20 more results. You may specify the start value, or use -1 to just get the next 20 results. 12. Other functions You can call yahoo_get_cookie to get the cookies for your connection. I think these can be used when starting a browser to get information from the yahoo servers. See the comments in yahoo2.h for more information. You can also call yahoo_urldecode and yahoo_urlencode utility functions to url decode/encode a given string. This will be useful for getting the filename from a url in the file receive code. * Platforms libyahoo2 is known to compile on: - Debian 2.2 (linux 2.4) i386, Alpha, PPC RS/6000 and Sparc Ultra60 - Redhat 6.0, 7.1 and 7.3 (linux 2.2 and 2.4) - MacOS X 10.1 PPC - G4 - FreeBSD 4.6-Stable - Sun Solaris (8) Thanks to Sourceforge's compile farms for letting me test it there * Copyright libyahoo2 is Copyright (C) 2002-2004 Philip S Tellis Portions of this code was taken and adapted from the yahoo module for gaim released under the GNU GPL. This code is also released under the GNU GPL. This code is derivitive of Gaim copyright (C) 1998-1999, Mark Spencer 1998-1999, Adam Fritzler 1998-2002, Rob Flynn 2000-2002, Eric Warmenhoven 2001-2002, Brian Macke 2001, Anand Biligiri S 2001, Valdis Kletnieks 2002, Sean Egan 2002, Toby Gray This library also uses code from other libraries, namely: Portions from libfaim copyright 1998, 1999 Adam Fritzler Portions of Sylpheed copyright 2000-2002 Hiroyuki Yamamoto * Licence 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. You should have received a copy of the GNU General Public License along with this program in the file named Copying; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * Warranty 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.