libyahoo2/yahoo2.h

   1 /*
   2  * libyahoo2: yahoo2.h
   3  *
   4  * Copyright (C) 2002-2004, Philip S Tellis <philip.tellis AT gmx.net>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19  *
  20  */
  21
  22 #ifndef YAHOO2_H
  23 #define YAHOO2_H
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 #include "yahoo2_types.h"
  30
  31 /* returns the socket descriptor object for a given pager connection. shouldn't be needed */
  32         void *yahoo_get_fd(int id);
  33
  34 /* says how much logging to do */
  35 /* see yahoo2_types.h for the different values */
  36         int yahoo_set_log_level(enum yahoo_log_level level);
  37         enum yahoo_log_level yahoo_get_log_level(void);
  38
  39 /* these functions should be self explanatory */
  40 /* who always means the buddy you're acting on */
  41 /* id is the successful value returned by yahoo_init */
  42
  43 /* init returns a connection id used to identify the connection hereon */
  44 /* or 0 on failure */
  45 /* you must call init before calling any other function */
  46 /*
  47  * The optional parameters to init are key/value pairs that specify
  48  * server settings to use.  This list must be NULL terminated - even
  49  * if the list is empty.  If a parameter isn't set, a default value
  50  * will be used.  Parameter keys are strings, parameter values are
  51  * either strings or ints, depending on the key.  Values passed in
  52  * are copied, so you can use const/auto/static/pointers/whatever
  53  * you want.  Parameters are:
  54  *      NAME                    TYPE            DEFAULT
  55  *      pager_host              char *          scs.msg.yahoo.com
  56  *      pager_port              int             5050
  57  *      filetransfer_host       char *          filetransfer.msg.yahoo.com
  58  *      filetransfer_port       int             80
  59  *      webcam_host             char *          webcam.yahoo.com
  60  *      webcam_port             int             5100
  61  *      webcam_description      char *          ""
  62  *      local_host              char *          ""
  63  *      conn_type               int             Y_WCM_DSL
  64  *
  65  * You should set at least local_host if you intend to use webcams
  66  */
  67         int yahoo_init_with_attributes(const char *username,
  68                 const char *password, ...);
  69
  70 /* yahoo_init does the same as yahoo_init_with_attributes, assuming defaults
  71  * for all attributes */
  72         int yahoo_init(const char *username, const char *password);
  73
  74 /* release all resources held by this session */
  75 /* you need to call yahoo_close for a session only if
  76  * yahoo_logoff is never called for it (ie, it was never logged in) */
  77         void yahoo_close(int id);
  78 /* login logs in to the server */
  79 /* initial is of type enum yahoo_status.  see yahoo2_types.h */
  80         void yahoo_login(int id, int initial);
  81         void yahoo_logoff(int id);
  82 /* reloads status of all buddies */
  83         void yahoo_refresh(int id);
  84 /* activates/deactivates an identity */
  85         void yahoo_set_identity_status(int id, const char *identity,
  86                 int active);
  87 /* regets the entire buddy list from the server */
  88         void yahoo_get_list(int id);
  89 /* download buddy contact information from your yahoo addressbook */
  90         void yahoo_get_yab(int id);
  91 /* add/modify an address book entry.  if yab->dbid is set, it will */
  92 /* modify that entry else it creates a new entry */
  93         void yahoo_set_yab(int id, struct yab *yab);
  94         void yahoo_keepalive(int id);
  95         void yahoo_chat_keepalive(int id);
  96
  97 /* from is the identity you're sending from.  if NULL, the default is used */
  98 /* utf8 is whether msg is a utf8 string or not. */
  99         void yahoo_send_im(int id, const char *from, const char *who,
 100                 const char *msg, int utf8, int picture);
 101         void yahoo_send_buzz(int id, const char *from, const char *who);
 102 /* if type is true, send typing notice, else send stopped typing notice */
 103         void yahoo_send_typing(int id, const char *from, const char *who,
 104                 int typ);
 105
 106 /* used to set away/back status. */
 107 /* away says whether the custom message is an away message or a sig */
 108         void yahoo_set_away(int id, enum yahoo_status state, const char *msg,
 109                 int away);
 110
 111         void yahoo_add_buddy(int id, const char *who, const char *group,
 112                 const char *msg);
 113         void yahoo_remove_buddy(int id, const char *who, const char *group);
 114         void yahoo_confirm_buddy(int id, const char *who, int reject,
 115                 const char *msg);
 116         void yahoo_stealth_buddy(int id, const char *who, int unstealth);
 117 /* if unignore is true, unignore, else ignore */
 118         void yahoo_ignore_buddy(int id, const char *who, int unignore);
 119         void yahoo_change_buddy_group(int id, const char *who,
 120                 const char *old_group, const char *new_group);
 121         void yahoo_group_rename(int id, const char *old_group,
 122                 const char *new_group);
 123
 124         void yahoo_conference_invite(int id, const char *from, YList *who,
 125                 const char *room, const char *msg);
 126         void yahoo_conference_addinvite(int id, const char *from,
 127                 const char *who, const char *room, const YList *members,
 128                 const char *msg);
 129         void yahoo_conference_decline(int id, const char *from, YList *who,
 130                 const char *room, const char *msg);
 131         void yahoo_conference_message(int id, const char *from, YList *who,
 132                 const char *room, const char *msg, int utf8);
 133         void yahoo_conference_logon(int id, const char *from, YList *who,
 134                 const char *room);
 135         void yahoo_conference_logoff(int id, const char *from, YList *who,
 136                 const char *room);
 137
 138 /* Get a list of chatrooms */
 139         void yahoo_get_chatrooms(int id, int chatroomid);
 140 /* join room with specified roomname and roomid */
 141         void yahoo_chat_logon(int id, const char *from, const char *room,
 142                 const char *roomid);
 143 /* Send message "msg" to room with specified roomname, msgtype is 1-normal message or 2-/me mesage */
 144         void yahoo_chat_message(int id, const char *from, const char *room,
 145                 const char *msg, const int msgtype, const int utf8);
 146 /* Log off chat */
 147         void yahoo_chat_logoff(int id, const char *from);
 148
 149 /* requests a webcam feed */
 150 /* who is the person who's webcam you would like to view */
 151 /* if who is null, then you're the broadcaster */
 152         void yahoo_webcam_get_feed(int id, const char *who);
 153         void yahoo_webcam_close_feed(int id, const char *who);
 154
 155 /* sends an image when uploading */
 156 /* image points to a JPEG-2000 image, length is the length of the image */
 157 /* in bytes. The timestamp is the time in milliseconds since we started the */
 158 /* webcam. */
 159         void yahoo_webcam_send_image(int id, unsigned char *image,
 160                 unsigned int length, unsigned int timestamp);
 161
 162 /* this function should be called if we want to allow a user to watch the */
 163 /* webcam. Who is the user we want to accept. */
 164 /* Accept user (accept = 1), decline user (accept = 0) */
 165         void yahoo_webcam_accept_viewer(int id, const char *who, int accept);
 166
 167 /* send an invitation to a user to view your webcam */
 168         void yahoo_webcam_invite(int id, const char *who);
 169
 170 /* will set up a connection and initiate file transfer.
 171  * callback will be called with the fd that you should write
 172  * the file data to
 173  */
 174         void yahoo_send_file(int id, const char *who, const char *msg,
 175                 const char *name, unsigned long size,
 176                 yahoo_get_fd_callback callback, void *data);
 177
 178 /*
 179  * Respond to a file transfer request. Be sure to provide the callback data
 180  * since that is your only chance to recognize future callbacks
 181  */
 182         void yahoo_send_file_transfer_response(int client_id, int response,
 183                 char *id, void *data);
 184
 185
 186 /* send a search request
 187  */
 188         void yahoo_search(int id, enum yahoo_search_type t, const char *text,
 189                 enum yahoo_search_gender g, enum yahoo_search_agerange ar,
 190                 int photo, int yahoo_only);
 191
 192 /* continue last search
 193  * should be called if only (start+found >= total)
 194  *
 195  * where the above three are passed to ext_yahoo_got_search_result
 196  */
 197         void yahoo_search_again(int id, int start);
 198
 199 /* these should be called when input is available on a fd */
 200 /* registered by ext_yahoo_add_handler */
 201 /* if these return negative values, errno may be set */
 202         int yahoo_read_ready(int id, void *fd, void *data);
 203         int yahoo_write_ready(int id, void *fd, void *data);
 204
 205 /* utility functions. these do not hit the server */
 206         enum yahoo_status yahoo_current_status(int id);
 207         const YList *yahoo_get_buddylist(int id);
 208         const YList *yahoo_get_ignorelist(int id);
 209         const YList *yahoo_get_identities(int id);
 210 /* 'which' could be y, t, c or login.  This may change in later versions. */
 211         const char *yahoo_get_cookie(int id, const char *which);
 212
 213 /* returns the url used to get user profiles - you must append the user id */
 214 /* as of now this is http://profiles.yahoo.com/ */
 215 /* You'll have to do urlencoding yourself, but see yahoo_httplib.h first */
 216         const char *yahoo_get_profile_url(void);
 217
 218         void yahoo_buddyicon_request(int id, const char *who);
 219
 220 #include "yahoo_httplib.h"
 221
 222 #ifdef __cplusplus
 223 }
 224 #endif
 225 #endif