diff options
Diffstat (limited to 'protocols/Yahoo/src/libyahoo2/Docs/README')
| -rw-r--r-- | protocols/Yahoo/src/libyahoo2/Docs/README | 442 |
1 files changed, 442 insertions, 0 deletions
diff --git a/protocols/Yahoo/src/libyahoo2/Docs/README b/protocols/Yahoo/src/libyahoo2/Docs/README new file mode 100644 index 0000000000..281de5c7c3 --- /dev/null +++ b/protocols/Yahoo/src/libyahoo2/Docs/README @@ -0,0 +1,442 @@ +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 <libyahoo2/yahoo2.h>
+#include <libyahoo2/yahoo2_callbacks.h>
+
+
+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 <http://gaim.sourceforge.net>
+copyright (C) 1998-1999, Mark Spencer <markster@marko.net>
+ 1998-1999, Adam Fritzler <afritz@marko.net>
+ 1998-2002, Rob Flynn <rob@marko.net>
+ 2000-2002, Eric Warmenhoven <eric@warmenhoven.org>
+ 2001-2002, Brian Macke <macke@strangelove.net>
+ 2001, Anand Biligiri S <abiligiri@users.sf.net>
+ 2001, Valdis Kletnieks
+ 2002, Sean Egan <bj91704@binghamton.edu>
+ 2002, Toby Gray <toby.gray@ntlworld.com>
+
+This library also uses code from other libraries, namely:
+ Portions from libfaim copyright 1998, 1999 Adam Fritzler
+ <afritz@auk.cx>
+ Portions of Sylpheed copyright 2000-2002 Hiroyuki Yamamoto
+ <hiro-y@kcn.ne.jp>
+
+
+* 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.
+
|