diff options
Diffstat (limited to 'tools/_deprecated/Yahoo/src/libyahoo2/Docs/README')
| -rw-r--r-- | tools/_deprecated/Yahoo/src/libyahoo2/Docs/README | 442 |
1 files changed, 0 insertions, 442 deletions
diff --git a/tools/_deprecated/Yahoo/src/libyahoo2/Docs/README b/tools/_deprecated/Yahoo/src/libyahoo2/Docs/README deleted file mode 100644 index 281de5c7c3..0000000000 --- a/tools/_deprecated/Yahoo/src/libyahoo2/Docs/README +++ /dev/null @@ -1,442 +0,0 @@ -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.
-
|