# HG changeset patch # User Christian Hammond # Date 1044663976 0 # Node ID 53ce3af93edb58f20467bd87028be54b214f4bee # Parent f7f0c7fef6bef19d821a39bb355604e5e5f010a4 [gaim-migrate @ 4837] - Documented prpl.h. - Moved #defines into enums. Sean likes it. You should too! committer: Tailor Script diff -r f7f0c7fef6be -r 53ce3af93edb src/prpl.c --- a/src/prpl.c Fri Feb 07 23:57:15 2003 +0000 +++ b/src/prpl.c Sat Feb 08 00:26:16 2003 +0000 @@ -47,14 +47,14 @@ void *data; }; -struct prpl *find_prpl(int prot) +struct prpl *find_prpl(GaimProtocol type) { GSList *e = protocols; struct prpl *r; while (e) { r = (struct prpl *)e->data; - if (r->protocol == prot) + if (r->protocol == type) return r; e = e->next; } diff -r f7f0c7fef6be -r 53ce3af93edb src/prpl.h --- a/src/prpl.h Fri Feb 07 23:57:15 2003 +0000 +++ b/src/prpl.h Sat Feb 08 00:26:16 2003 +0000 @@ -1,4 +1,6 @@ -/* +/** + * @file prpl.h Protocol Plugin functions + * * gaim * * Copyright (C) 1998-1999, Mark Spencer @@ -22,79 +24,160 @@ /* this file should be all that prpls need to include. therefore, by including * this file, they should get glib, proxy, gaim_connection, prpl, etc. */ -#ifndef _PRPL_H_ -#define _PRPL_H_ +#ifndef _GAIM_PRPL_H_ +#define _GAIM_PRPL_H_ #include "core.h" #include "proxy.h" #include "multi.h" -#define PROTO_TOC 0 -#define PROTO_OSCAR 1 -#define PROTO_YAHOO 2 -#define PROTO_ICQ 3 -#define PROTO_MSN 4 -#define PROTO_IRC 5 -#define PROTO_FTP 6 -#define PROTO_VGATE 7 -#define PROTO_JABBER 8 -#define PROTO_NAPSTER 9 -#define PROTO_ZEPHYR 10 -#define PROTO_GADUGADU 11 -#define PROTO_SAMETIME 12 -#define PROTO_TLEN 13 -#define PROTO_RVP 14 -#define PROTO_BACKRUB 15 -#define PROTO_UNTAKEN 16 +/**************************************************************************/ +/** @name Basic Protocol Information */ +/**************************************************************************/ +/*@{*/ -/* DON'T TAKE AN UNASSIGNED NUMBER! Talk to Rob or Sean if you'd like - * to create a new PRPL. */ +/** + * Protocol types and numbers. + * + * Do not assume a new protocol number without talking to + * Rob Flynn or Sean Egan first! + */ +typedef enum +{ + PROTO_TOC = 0, /**< AIM TOC protocol */ + PROTO_OSCAR, /**< AIM OSCAR protocol */ + PROTO_YAHOO, /**< Yahoo Messenger protocol */ + PROTO_ICQ, /**< Outdated ICQ protocol */ + PROTO_MSN, /**< MSN Messenger protocol */ + PROTO_IRC, /**< IRC protocol */ + PROTO_FTP, /**< FTP protocol */ + PROTO_VGATE, /**< VGATE protocol */ + PROTO_JABBER, /**< Jabber protocol */ + PROTO_NAPSTER, /**< Napster/OpenNAP protocol */ + PROTO_ZEPHYR, /**< MIT Zephyr protocol */ + PROTO_GADUGADU, /**< Gadu-Gadu protocol */ + PROTO_SAMETIME, /**< SameTime protocol */ + PROTO_TLEN, /**< TLEN protocol */ + PROTO_RVP, /**< RVP protocol */ + PROTO_BACKRUB, /**< Instant Massager protocol */ + PROTO_UNTAKEN /**< Untaken protocol number */ -#define PRPL_DESC(x) "Allows gaim to use the " x " protocol.\n\n" \ - "Now that you have loaded this protocol, use the " \ - "Account Editor to add an account that uses this " \ - "protocol. You can access the Account Editor from " \ - "the \"Accounts\" button on the login window or " \ - "in the \"Tools\" menu in the buddy list window." +} GaimProtocol; +/** Default protocol plugin description */ +#define PRPL_DESC(x) \ + "Allows gaim to use the " x " protocol.\n\n" \ + "Now that you have loaded this protocol, use the " \ + "Account Editor to add an account that uses this " \ + "protocol. You can access the Account Editor from " \ + "the \"Accounts\" button on the login window or " \ + "in the \"Tools\" menu in the buddy list window." + +/** Default protocol */ #define DEFAULT_PROTO PROTO_OSCAR -/* These should all be stuff that some plugins can do and others can't */ -/* TOC/Oscar send HTML-encoded messages; most other protocols don't */ -/* #define OPT_PROTO_HTML 0x00000001 this should be per-connection */ -/* TOC/Oscar have signon time, and the server's time needs to be adjusted to match - * your computer's time. We wouldn't need this if everyone used NTP. */ -#define OPT_PROTO_CORRECT_TIME 0x00000002 -/* Jabber lets you choose what name you want for chat. So it shouldn't be pulling - * the alias for when you're in chat; it gets annoying. */ -#define OPT_PROTO_UNIQUE_CHATNAME 0x00000004 -/* IRC, Jabber let you have chat room topics */ -#define OPT_PROTO_CHAT_TOPIC 0x00000008 -/* Zephyr doesn't require passwords, so there's no need for a password prompt */ -#define OPT_PROTO_NO_PASSWORD 0x00000010 -/* MSN and Yahoo notify you when you have new mail */ -#define OPT_PROTO_MAIL_CHECK 0x00000020 -/* Oscar and Jabber have buddy icons */ -#define OPT_PROTO_BUDDY_ICON 0x00000040 -/* Oscar lets you send images in direct IMs */ -#define OPT_PROTO_IM_IMAGE 0x00000080 -/* Passwords in IRC are optional, and are needed for certain functionality. */ -#define OPT_PROTO_PASSWORD_OPTIONAL 0x00000100 +/*@}*/ + +/** + * Protocol options + * + * These should all be stuff that some plugins can do and others can't. + */ +typedef enum +{ + /** + * TOC and Oscar send HTML-encoded messages; + * most other protocols don't. + */ +// #define OPT_PROTO_HTML 0x00000001 this should be per-connection */ + + /** + * Synchronize the time between the local computer and the server. + * + * TOC and Oscar have signon time, and the server's time needs + * to be adjusted to match your computer's time. + * + * We wouldn't need this if everyone used NTP. + */ + OPT_PROTO_CORRECT_TIME = 0x00000002, + + /** + * Use a unique name, not an alias, for chat rooms. + * + * Jabber lets you choose what name you want for chat. + * So it shouldn't be pulling the alias for when you're in chat; + * it gets annoying. + */ + OPT_PROTO_UNIQUE_CHATNAME = 0x00000004, + + /** + * Chat rooms have topics. + * + * IRC and Jabber support this. + */ + OPT_PROTO_CHAT_TOPIC = 0x00000008, + /** + * Don't require passwords for sign-in. + * + * Zephyr doesn't require passwords, so there's no need for + * a password prompt. + */ + OPT_PROTO_NO_PASSWORD = 0x00000010, + + /** + * Notify on new mail. + * + * MSN and Yahoo notify you when you have new mail. + */ + OPT_PROTO_MAIL_CHECK = 0x00000020, + + /** + * Buddy icon support. + * + * Oscar and Jabber have buddy icons. + */ + OPT_PROTO_BUDDY_ICON = 0x00000040, + + /** + * Images in IMs. + * + * Oscar lets you send images in direct IMs. + */ + OPT_PROTO_IM_IMAGE = 0x00000080, + + /** + * Allow passwords to be optional. + * + * Passwords in IRC are optional, and are needed for certain + * functionality. + */ + OPT_PROTO_PASSWORD_OPTIONAL = 0x00000100, + +} GaimProtocolOptions; + +/** Custom away message. */ #define GAIM_AWAY_CUSTOM "Custom" +/** + * Protocol plugin initialization function. + */ typedef void (*proto_init)(struct prpl *); -struct prpl { - int protocol; - int options; - struct gaim_plugin *plug; +/** + * A protocol plugin structure. + * + * Every protocol plugin initializes this structure. It is the gateway + * between gaim and the protocol plugin. + */ +struct prpl +{ + GaimProtocol protocol; /**< The protocol type. */ + GaimProtocolOptions options; /**< Protocol options. */ + struct gaim_plugin *plug; /**< The base plugin structure. */ char *name; - /* for ICQ and Yahoo, who have off/on per-conversation options */ - /* char *checkbox; this should be per-connection */ - - /* returns the XPM associated with the given user class */ + /** Returns the XPM associated with the given user class. */ char **(* list_icon)(int); GList *(* away_states)(struct gaim_connection *gc); GList *(* actions)(struct gaim_connection *gc); @@ -104,16 +187,19 @@ GList *(* edit_buddy_menu)(struct gaim_connection *, char *); GList *(* chat_info)(struct gaim_connection *); - /* all the server-related functions */ + /* All the server-related functions */ - /* a lot of these (like get_dir) are protocol-dependent and should be removed. ones like - * set_dir (which is also protocol-dependent) can stay though because there's a dialog - * (i.e. the prpl says you can set your dir info, the ui shows a dialog and needs to call - * set_dir in order to set it) */ - + /* + * A lot of these (like get_dir) are protocol-dependent and should + * be removed. ones like set_dir (which is also protocol-dependent) + * can stay though because there's a dialog (i.e. the prpl says you + * can set your dir info, the ui shows a dialog and needs to call + * set_dir in order to set it) + */ void (* login) (struct gaim_account *); void (* close) (struct gaim_connection *); - int (* send_im) (struct gaim_connection *, char *who, char *message, int len, int away); + int (* send_im) (struct gaim_connection *, char *who, char *message, + int len, int away); void (* set_info) (struct gaim_connection *, char *info); int (* send_typing) (struct gaim_connection *, char *name, int typing); void (* get_info) (struct gaim_connection *, char *who); @@ -137,11 +223,13 @@ const char *country, const char *email); void (* set_idle) (struct gaim_connection *, int idletime); - void (* change_passwd) (struct gaim_connection *, const char *old, const char *new); + void (* change_passwd) (struct gaim_connection *, const char *old, + const char *new); void (* add_buddy) (struct gaim_connection *, const char *name); void (* add_buddies) (struct gaim_connection *, GList *buddies); void (* remove_buddy) (struct gaim_connection *, char *name, char *group); - void (* remove_buddies) (struct gaim_connection *, GList *buddies, const char *group); + void (* remove_buddies) (struct gaim_connection *, GList *buddies, + const char *group); void (* add_permit) (struct gaim_connection *, const char *name); void (* add_deny) (struct gaim_connection *, const char *name); void (* rem_permit) (struct gaim_connection *, const char *name); @@ -149,9 +237,11 @@ void (* set_permit_deny)(struct gaim_connection *); void (* warn) (struct gaim_connection *, char *who, int anonymous); void (* join_chat) (struct gaim_connection *, GList *data); - void (* chat_invite) (struct gaim_connection *, int id, const char *who, const char *message); + void (* chat_invite) (struct gaim_connection *, int id, + const char *who, const char *message); void (* chat_leave) (struct gaim_connection *, int id); - void (* chat_whisper) (struct gaim_connection *, int id, char *who, char *message); + void (* chat_whisper) (struct gaim_connection *, int id, + char *who, char *message); int (* chat_send) (struct gaim_connection *, int id, char *message); void (* keepalive) (struct gaim_connection *); @@ -163,13 +253,16 @@ void (* get_cb_away) (struct gaim_connection *, int, char *who); /* save/store buddy's alias on server list/roster */ - void (* alias_buddy) (struct gaim_connection *, const char *who, const char *alias); + void (* alias_buddy) (struct gaim_connection *, const char *who, + const char *alias); /* change a buddy's group on a server list/roster */ - void (* group_buddy) (struct gaim_connection *, const char *who, const char *old_group, const char *new_group); + void (* group_buddy) (struct gaim_connection *, const char *who, + const char *old_group, const char *new_group); /* rename a group on a server list/roster */ - void (* rename_group) (struct gaim_connection *, const char *old_group, const char *new_group, GList *members); + void (* rename_group) (struct gaim_connection *, const char *old_group, + const char *new_group, GList *members); void (* buddy_free) (struct buddy *); @@ -179,35 +272,173 @@ char *(* normalize)(const char *); }; +/** A list of all loaded protocol plugins. */ extern GSList *protocols; + +/** The number of accounts using a given protocol plugin. */ extern int prpl_accounts[]; -/* this is mostly just for aim.c, when it initializes the protocols */ -extern void static_proto_init(); +/** + * Initializes static protocols. + * + * This is mostly just for main.c, when it initializes the protocols. + */ +void static_proto_init(); + +/** + * Loads a protocol plugin. + * + * @param prpl The initial protocol plugin structure. + * + * @return @c TRUE if the protocol was loaded, or @c FALSE otherwise. + */ +gboolean load_prpl(struct prpl *prpl); + +/** + * Loads a statically compiled protocol plugin. + * + * @param pi The initialization function. + */ +void load_protocol(proto_init pi); + +/** + * Unloads a protocol plugin. + * + * @param prpl The protocol plugin to unload. + */ +extern void unload_protocol(struct prpl *prpl); -/* this is what should actually load the protocol. pass it the protocol's initializer */ -extern gboolean load_prpl(struct prpl *); -extern void load_protocol(proto_init); -extern void unload_protocol(struct prpl *); -extern gint proto_compare(struct prpl *, struct prpl *); +/** + * Compares two protocol plugins, based off their protocol plugin number. + * + * @param a The first protocol plugin. + * @param b The second protocol plugin. + * + * @return <= 1 if the first plugin's number is smaller than the second; + * 0 if the first plugin's number is equal to the second; or + * >= 1 if the first plugin's number is greater than the second. + */ +gint proto_compare(struct prpl *a, struct prpl *b); + +/** + * Finds a protocol plugin structure of the specified type. + * + * @param type The protocol plugin type. + */ +struct prpl *find_prpl(GaimProtocol type); -extern struct prpl *find_prpl(int); -extern void do_proto_menu(); +/** + * Creates a menu of all protocol plugins and their protocol-specific + * actions. + * + * @note This should be UI-specific code, or rewritten in such a way as to + * not use any any GTK code. + */ +void do_proto_menu(); + +/** + * Shows a message saying that somebody added you as a buddy, and asks + * if you would like to do the same. + * + * @param gc The gaim connection. + * @param id The ID of the user. + * @param who The username. + * @param alias The user's alias. + * @param msg The message to go along with the request. + */ +void show_got_added(struct gaim_connection *gc, const char *id, + const char *who, const char *alias, const char *msg); -extern void show_got_added(struct gaim_connection *, const char *, - const char *, const char *, const char *); +/** + * Closes do_ask_dialogs when the associated plugin is unloaded. + * + * @param module The module. + */ +void do_ask_cancel_by_handle(GModule *module); + +/** + * Asks the user a question and acts on the response. + * + * @param prim The primary question. + * @param sec The secondary question. + * @param data The data to be passed to a callback. + * @param yestext The text for the Yes button. + * @param doit The callback function to call when the Yes button is clicked. + * @param notext The text for the No button. + * @param dont The callback function to call when the No button is clicked. + * @param handle The module handle to associate with this dialog, or @c NULL. + * @param modal @c TRUE if the dialog should be modal; @c FALSE otherwise. + */ +void do_ask_dialog(const char *prim, const char *sec, void *data, + char *yestext, void *doit, char *notext, void *dont, + GModule *handle, gboolean modal); + +/** + * Prompts the user for data. + * + * @param text The text to present to the user. + * @param def The default data, or @c NULL. + * @param data The data to be passed to the callback. + * @param doit The callback function to call when the Accept button is clicked. + * @param dont The callback function to call when the Cancel button is clicked. + */ +void do_prompt_dialog(const char *text, const char *sdef, void *data, + void *doit, void *dont); -extern void do_ask_cancel_by_handle(GModule *); -extern void do_ask_dialog(const char *, const char *, void *, char*, void *, char *, void *, GModule *, gboolean); -extern void do_prompt_dialog(const char *, const char *, void *, void *, void *); +/** + * Called to notify the user that the account has new mail. + * + * If @a count is less than 0, the dialog will display the the sender + * and the subject, if available. If @a count is greater than 0, it will + * display how many messages the user has. + * + * @param gc The gaim connection. + * @param count The number of new e-mails. + * @param from The sender, or @c NULL. + * @param subject The subject, or @c NULL. + * @param url The URL to go to to read the new mail. + */ +void connection_has_mail(struct gaim_connection *gc, int count, + const char *from, const char *subject, + const char *url); -extern void connection_has_mail(struct gaim_connection *, int, const char *, const char *, const char *); +/** + * Retrieves and sets the new buddy icon for a user. + * + * @param gc The gaim connection. + * @param who The user. + * @param data The icon data. + * @param len The length of @a data. + */ +void set_icon_data(struct gaim_connection *gc, char *who, void *data, int len); -extern void set_icon_data(struct gaim_connection *, char *, void *, int); -extern void *get_icon_data(struct gaim_connection *, char *, int *); +/** + * Retrieves the buddy icon data for a user. + * + * @param gc The gaim connection. + * @param who The user. + * @param len The returned length of the data. + * + * @return The buddy icon data. + */ +void *get_icon_data(struct gaim_connection *gc, char *who, int *len); /* stuff to load/unload PRPLs as necessary */ -extern gboolean ref_protocol(struct prpl *p); -extern void unref_protocol(struct prpl *p); + +/** + * Increments the reference count on a protocol plugin. + * + * @param prpl The protocol plugin. + * + * @return @c TRUE if the protocol plugin is loaded, or @c FALSE otherwise. + */ +gboolean ref_protocol(struct prpl *prpl); + +/** + * Decrements the reference count on a protocol plugin. + * + * When the reference count hits 0, the protocol plugin is unloaded. + */ +void unref_protocol(struct prpl *prpl); #endif /* _PRPL_H_ */