src/prpl.h

   1 /**
   2  * @file prpl.h Protocol Plugin functions
   3  * @ingroup core
   4  *
   5  * gaim
   6  *
   7  * Copyright (C) 1998-1999, Mark Spencer <markster@marko.net>
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  22  */
  23
  24 /* this file should be all that prpls need to include. therefore, by including
  25  * this file, they should get glib, proxy, gaim_connection, prpl, etc. */
  26
  27 #ifndef _GAIM_PRPL_H_
  28 #define _GAIM_PRPL_H_
  29
  30 #include "core.h"
  31 #include "proxy.h"
  32 #include "multi.h"
  33
  34 /**************************************************************************/
  35 /** @name Basic Protocol Information                                      */
  36 /**************************************************************************/
  37 /*@{*/
  38
  39 /**
  40  * Protocol types and numbers.
  41  *
  42  * Do not assume a new protocol number without talking to
  43  * Rob Flynn or Sean Egan first!
  44  */
  45 typedef enum
  46 {
  47         PROTO_TOC = 0,     /**< AIM TOC protocol          */
  48         PROTO_OSCAR,       /**< AIM OSCAR protocol        */
  49         PROTO_YAHOO,       /**< Yahoo Messenger protocol  */
  50         PROTO_ICQ,         /**< Outdated ICQ protocol     */
  51         PROTO_MSN,         /**< MSN Messenger protocol    */
  52         PROTO_IRC,         /**< IRC protocol              */
  53         PROTO_FTP,         /**< FTP protocol              */
  54         PROTO_VGATE,       /**< VGATE protocol            */
  55         PROTO_JABBER,      /**< Jabber protocol           */
  56         PROTO_NAPSTER,     /**< Napster/OpenNAP protocol  */
  57         PROTO_ZEPHYR,      /**< MIT Zephyr protocol       */
  58         PROTO_GADUGADU,    /**< Gadu-Gadu protocol        */
  59         PROTO_SAMETIME,    /**< SameTime protocol         */
  60         PROTO_TLEN,        /**< TLEN protocol             */
  61         PROTO_RVP,         /**< RVP protocol              */
  62         PROTO_BACKRUB,     /**< Instant Massager protocol */
  63         PROTO_UNTAKEN      /**< Untaken protocol number   */
  64
  65 } GaimProtocol;
  66
  67 /** Default protocol plugin description */
  68 #define PRPL_DESC(x) \
  69                 "Allows gaim to use the " x " protocol.\n\n"        \
  70                 "Now that you have loaded this protocol, use the "  \
  71                 "Account Editor to add an account that uses this "  \
  72                 "protocol. You can access the Account Editor from " \
  73                 "the \"Accounts\" button on the login window or "   \
  74                 "in the \"Tools\" menu in the buddy list window."
  75
  76 /** Default protocol */
  77 #define DEFAULT_PROTO   PROTO_OSCAR
  78
  79 /*@}*/
  80
  81 /**
  82  * Protocol options
  83  *
  84  * These should all be stuff that some plugins can do and others can't.
  85  */
  86 typedef enum
  87 {
  88         /**
  89          * TOC and Oscar send HTML-encoded messages;
  90          * most other protocols don't.
  91          */
  92 #if 0
  93         #define OPT_PROTO_HTML            0x00000001 this should be per-connection */
  94 #endif
  95
  96         /**
  97          * Synchronize the time between the local computer and the server.
  98          *
  99          * TOC and Oscar have signon time, and the server's time needs
 100          * to be adjusted to match your computer's time.
 101          *
 102          * We wouldn't need this if everyone used NTP.
 103          */
 104         OPT_PROTO_CORRECT_TIME = 0x00000002,
 105
 106         /**
 107          * Use a unique name, not an alias, for chat rooms.
 108          *
 109          * Jabber lets you choose what name you want for chat.
 110          * So it shouldn't be pulling the alias for when you're in chat;
 111          * it gets annoying.
 112          */
 113         OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
 114
 115         /**
 116          * Chat rooms have topics.
 117          *
 118          * IRC and Jabber support this.
 119          */
 120         OPT_PROTO_CHAT_TOPIC = 0x00000008,
 121
 122         /**
 123          * Don't require passwords for sign-in.
 124          *
 125          * Zephyr doesn't require passwords, so there's no need for
 126          * a password prompt.
 127          */
 128         OPT_PROTO_NO_PASSWORD = 0x00000010,
 129
 130         /**
 131          * Notify on new mail.
 132          *
 133          * MSN and Yahoo notify you when you have new mail.
 134          */
 135         OPT_PROTO_MAIL_CHECK = 0x00000020,
 136
 137         /**
 138          * Buddy icon support.
 139          *
 140          * Oscar and Jabber have buddy icons.
 141          */
 142         OPT_PROTO_BUDDY_ICON = 0x00000040,
 143
 144         /**
 145          * Images in IMs.
 146          *
 147          * Oscar lets you send images in direct IMs.
 148          */
 149         OPT_PROTO_IM_IMAGE = 0x00000080,
 150
 151         /**
 152          * Allow passwords to be optional.
 153          *
 154          * Passwords in IRC are optional, and are needed for certain
 155          * functionality.
 156          */
 157         OPT_PROTO_PASSWORD_OPTIONAL = 0x00000100,
 158
 159 } GaimProtocolOptions;
 160
 161 /** Custom away message. */
 162 #define GAIM_AWAY_CUSTOM _("Custom")
 163
 164 /**
 165  * Protocol plugin initialization function.
 166  */
 167 typedef void (*proto_init)(struct prpl *);
 168
 169 /**
 170  * A protocol plugin structure.
 171  *
 172  * Every protocol plugin initializes this structure. It is the gateway
 173  * between gaim and the protocol plugin.
 174  */
 175 struct prpl
 176 {
 177         GaimProtocol protocol;        /**< The protocol type.         */
 178         GaimProtocolOptions options;  /**< Protocol options.          */
 179         struct gaim_plugin *plug;     /**< The base plugin structure. */
 180         char *name;
 181
 182         /**
 183          * Returns the base icon name for the given buddy and account.
 184          * If buddy is NULL, it will return the name to use for the account's icon
 185          */
 186         const char *(* list_icon)(struct gaim_account *account, struct buddy *buddy);
 187
 188         /**
 189          * Fills the four char**'s with string identifiers for "emblems" that the UI will
 190          * interpret and display as relevant
 191          */
 192         void (* list_emblems)(struct buddy *buddy, char **se, char **sw, char **nw, char **ne);
 193
 194         /**
 195          * Gets a short string representing this buddy's status.  This will be shown
 196          * on the buddy list.
 197          */
 198         char *(* status_text)(struct buddy *buddy);
 199
 200         /**
 201          * Gets a string to put in the buddy list tooltip.
 202          */
 203         char *(* tooltip_text)(struct buddy *buddy);
 204
 205         GList *(* away_states)(struct gaim_connection *gc);
 206         GList *(* actions)(struct gaim_connection *gc);
 207         /* user_splits is a GList of g_malloc'd struct proto_user_split */
 208         GList *user_splits;
 209         /* user_opts is a GList* of g_malloc'd struct proto_user_opts */
 210         GList *user_opts;
 211         GList *(* buddy_menu)(struct gaim_connection *, char *);
 212         GList *(* chat_info)(struct gaim_connection *);
 213
 214         /* All the server-related functions */
 215
 216         /*
 217          * A lot of these (like get_dir) are protocol-dependent and should
 218          * be removed. ones like set_dir (which is also protocol-dependent)
 219          * can stay though because there's a dialog (i.e. the prpl says you
 220          * can set your dir info, the ui shows a dialog and needs to call
 221          * set_dir in order to set it)
 222          */
 223         void (* login)          (struct gaim_account *);
 224         void (* close)          (struct gaim_connection *);
 225         int  (* send_im)        (struct gaim_connection *, char *who, char *message,
 226                                                  int len, int away);
 227         void (* set_info)       (struct gaim_connection *, char *info);
 228         int  (* send_typing)    (struct gaim_connection *, char *name, int typing);
 229         void (* get_info)       (struct gaim_connection *, char *who);
 230         void (* set_away)       (struct gaim_connection *, char *state, char *message);
 231         void (* get_away)       (struct gaim_connection *, char *who);
 232         void (* set_dir)        (struct gaim_connection *, const char *first,
 233                                                            const char *middle,
 234                                                            const char *last,
 235                                                            const char *maiden,
 236                                                            const char *city,
 237                                                            const char *state,
 238                                                            const char *country,
 239                                                            int web);
 240         void (* get_dir)        (struct gaim_connection *, char *who);
 241         void (* dir_search)     (struct gaim_connection *, const char *first,
 242                                                            const char *middle,
 243                                                            const char *last,
 244                                                            const char *maiden,
 245                                                            const char *city,
 246                                                            const char *state,
 247                                                            const char *country,
 248                                                            const char *email);
 249         void (* set_idle)       (struct gaim_connection *, int idletime);
 250         void (* change_passwd)  (struct gaim_connection *, const char *old,
 251                                                          const char *new);
 252         void (* add_buddy)      (struct gaim_connection *, const char *name);
 253         void (* add_buddies)    (struct gaim_connection *, GList *buddies);
 254         void (* remove_buddy)   (struct gaim_connection *, char *name, char *group);
 255         void (* remove_buddies) (struct gaim_connection *, GList *buddies,
 256                                                          const char *group);
 257         void (* add_permit)     (struct gaim_connection *, const char *name);
 258         void (* add_deny)       (struct gaim_connection *, const char *name);
 259         void (* rem_permit)     (struct gaim_connection *, const char *name);
 260         void (* rem_deny)       (struct gaim_connection *, const char *name);
 261         void (* set_permit_deny)(struct gaim_connection *);
 262         void (* warn)           (struct gaim_connection *, char *who, int anonymous);
 263         void (* join_chat)      (struct gaim_connection *, GList *data);
 264         void (* chat_invite)    (struct gaim_connection *, int id,
 265                                                          const char *who, const char *message);
 266         void (* chat_leave)     (struct gaim_connection *, int id);
 267         void (* chat_whisper)   (struct gaim_connection *, int id,
 268                                                          char *who, char *message);
 269         int  (* chat_send)      (struct gaim_connection *, int id, char *message);
 270         void (* keepalive)      (struct gaim_connection *);
 271
 272         /* new user registration */
 273         void (* register_user)  (struct gaim_account *);
 274
 275         /* get "chat buddy" info and away message */
 276         void (* get_cb_info)    (struct gaim_connection *, int, char *who);
 277         void (* get_cb_away)    (struct gaim_connection *, int, char *who);
 278
 279         /* save/store buddy's alias on server list/roster */
 280         void (* alias_buddy)    (struct gaim_connection *, const char *who,
 281                                                          const char *alias);
 282
 283         /* change a buddy's group on a server list/roster */
 284         void (* group_buddy)    (struct gaim_connection *, const char *who,
 285                                                          const char *old_group, const char *new_group);
 286
 287         /* rename a group on a server list/roster */
 288         void (* rename_group)   (struct gaim_connection *, const char *old_group,
 289                                                          const char *new_group, GList *members);
 290
 291         void (* buddy_free)     (struct buddy *);
 292
 293         /* this is really bad. */
 294         void (* convo_closed)   (struct gaim_connection *, char *who);
 295
 296         char *(* normalize)(const char *);
 297 };
 298
 299 /** A list of all loaded protocol plugins. */
 300 extern GSList *protocols;
 301
 302 /** The number of accounts using a given protocol plugin. */
 303 extern int prpl_accounts[];
 304
 305 /**
 306  * Initializes static protocols.
 307  *
 308  * This is mostly just for main.c, when it initializes the protocols.
 309  */
 310 void static_proto_init();
 311
 312 /**
 313  * Loads a protocol plugin.
 314  *
 315  * @param prpl The initial protocol plugin structure.
 316  *
 317  * @return @c TRUE if the protocol was loaded, or @c FALSE otherwise.
 318  */
 319 gboolean load_prpl(struct prpl *prpl);
 320
 321 /**
 322  * Loads a statically compiled protocol plugin.
 323  *
 324  * @param pi The initialization function.
 325  */
 326 void load_protocol(proto_init pi);
 327
 328 /**
 329  * Unloads a protocol plugin.
 330  *
 331  * @param prpl The protocol plugin to unload.
 332  */
 333 extern void unload_protocol(struct prpl *prpl);
 334
 335 /**
 336  * Compares two protocol plugins, based off their protocol plugin number.
 337  *
 338  * @param a The first protocol plugin.
 339  * @param b The second protocol plugin.
 340  *
 341  * @return <= 1 if the first plugin's number is smaller than the second;
 342  *         0 if the first plugin's number is equal to the second; or
 343  *         >= 1 if the first plugin's number is greater than the second.
 344  */
 345 gint proto_compare(struct prpl *a, struct prpl *b);
 346
 347 /**
 348  * Finds a protocol plugin structure of the specified type.
 349  *
 350  * @param type The protocol plugin type.
 351  */
 352 struct prpl *find_prpl(GaimProtocol type);
 353
 354 /**
 355  * Creates a menu of all protocol plugins and their protocol-specific
 356  * actions.
 357  *
 358  * @note This should be UI-specific code, or rewritten in such a way as to
 359  *       not use any any GTK code.
 360  */
 361 void do_proto_menu();
 362
 363 /**
 364  * Shows a message saying that somebody added you as a buddy, and asks
 365  * if you would like to do the same.
 366  *
 367  * @param gc    The gaim connection.
 368  * @param id    The ID of the user.
 369  * @param who   The username.
 370  * @param alias The user's alias.
 371  * @param msg   The message to go along with the request.
 372  */
 373 void show_got_added(struct gaim_connection *gc, const char *id,
 374                                         const char *who, const char *alias, const char *msg);
 375
 376 /**
 377  * Closes do_ask_dialogs when the associated plugin is unloaded.
 378  *
 379  * @param module The module.
 380  */
 381 void do_ask_cancel_by_handle(GModule *module);
 382
 383 /**
 384  * Asks the user a question and acts on the response.
 385  *
 386  * @param prim    The primary question.
 387  * @param sec     The secondary question.
 388  * @param data    The data to be passed to a callback.
 389  * @param yestext The text for the Yes button.
 390  * @param doit    The callback function to call when the Yes button is clicked.
 391  * @param notext  The text for the No button.
 392  * @param dont    The callback function to call when the No button is clicked.
 393  * @param handle  The module handle to associate with this dialog, or @c NULL.
 394  * @param modal   @c TRUE if the dialog should be modal; @c FALSE otherwise.
 395  */
 396 void do_ask_dialog(const char *prim, const char *sec, void *data,
 397                                    char *yestext, void *doit, char *notext, void *dont,
 398                                    GModule *handle, gboolean modal);
 399
 400 /**
 401  * Prompts the user for data.
 402  *
 403  * @param text The text to present to the user.
 404  * @param def  The default data, or @c NULL.
 405  * @param data The data to be passed to the callback.
 406  * @param doit The callback function to call when the Accept button is clicked.
 407  * @param dont The callback function to call when the Cancel button is clicked.
 408  */
 409 void do_prompt_dialog(const char *text, const char *sdef, void *data,
 410                                           void *doit, void *dont);
 411
 412 /**
 413  * Called to notify the user that the account has new mail.
 414  *
 415  * If @a count is less than 0, the dialog will display the the sender
 416  * and the subject, if available. If @a count is greater than 0, it will
 417  * display how many messages the user has.
 418  *
 419  * @param gc      The gaim connection.
 420  * @param count   The number of new e-mails.
 421  * @param from    The sender, or @c NULL.
 422  * @param subject The subject, or @c NULL.
 423  * @param url     The URL to go to to read the new mail.
 424  */
 425 void connection_has_mail(struct gaim_connection *gc, int count,
 426                                                  const char *from, const char *subject,
 427                                                  const char *url);
 428
 429 /**
 430  * Retrieves and sets the new buddy icon for a user.
 431  *
 432  * @param gc   The gaim connection.
 433  * @param who  The user.
 434  * @param data The icon data.
 435  * @param len  The length of @a data.
 436  */
 437 void set_icon_data(struct gaim_connection *gc, const char *who, void *data, int len);
 438
 439 /**
 440  * Retrieves the buddy icon data for a user.
 441  *
 442  * @param gc  The gaim connection.
 443  * @param who The user.
 444  * @param len The returned length of the data.
 445  *
 446  * @return The buddy icon data.
 447  */
 448 void *get_icon_data(struct gaim_connection *gc, const char *who, int *len);
 449
 450 /* stuff to load/unload PRPLs as necessary */
 451
 452 /**
 453  * Increments the reference count on a protocol plugin.
 454  *
 455  * @param prpl The protocol plugin.
 456  *
 457  * @return @c TRUE if the protocol plugin is loaded, or @c FALSE otherwise.
 458  */
 459 gboolean ref_protocol(struct prpl *prpl);
 460
 461 /**
 462  * Decrements the reference count on a protocol plugin.
 463  *
 464  * When the reference count hits 0, the protocol plugin is unloaded.
 465  */
 466 void unref_protocol(struct prpl *prpl);
 467
 468 #endif /* _PRPL_H_ */