pidgin: src/prpl.h comparison

comparison src/prpl.h @ 4557:53ce3af93edb

[gaim-migrate @ 4837] - Documented prpl.h. - Moved #defines into enums. Sean likes it. You should too! committer: Tailor Script <tailor@pidgin.im>

author	Christian Hammond <chipx86@chipx86.com>
date	Sat, 08 Feb 2003 00:26:16 +0000
parents	7521e29658bc
children	7e1591c6d0d8

comparison

equal deleted inserted replaced

-:f7f0c7fef6be
+:53ce3af93edb
-/*
+/**
+* @file prpl.h Protocol Plugin functions
+*
 * gaim
 *
 * Copyright (C) 1998-1999, Mark Spencer <markster@marko.net>
 *
 * This program is free software; you can redistribute it and/or modify
 */
 /* 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_
+#ifndef _GAIM_PRPL_H_
-#define _PRPL_H_
+#define _GAIM_PRPL_H_
 #include "core.h"
 #include "proxy.h"
 #include "multi.h"
-#define PROTO_TOC	0
+/**************************************************************************/
-#define PROTO_OSCAR	1
+/** @name Basic Protocol Information                                      */
-#define PROTO_YAHOO	2
+/**************************************************************************/
-#define PROTO_ICQ	3
+/*@{*/
-#define PROTO_MSN	4
-#define PROTO_IRC	5
+/**
-#define PROTO_FTP	6
+* Protocol types and numbers.
-#define PROTO_VGATE	7
+*
-#define PROTO_JABBER	8
+* Do not assume a new protocol number without talking to
-#define PROTO_NAPSTER	9
+* Rob Flynn or Sean Egan first!
-#define PROTO_ZEPHYR   10
+*/
-#define PROTO_GADUGADU 11
+typedef enum
-#define PROTO_SAMETIME 12
+{
-#define PROTO_TLEN     13
+	PROTO_TOC = 0,     /**< AIM TOC protocol          */
-#define PROTO_RVP      14
+	PROTO_OSCAR,       /**< AIM OSCAR protocol        */
-#define PROTO_BACKRUB  15
+	PROTO_YAHOO,       /**< Yahoo Messenger protocol  */
-#define PROTO_UNTAKEN  16
+	PROTO_ICQ,         /**< Outdated ICQ protocol     */
+	PROTO_MSN,         /**< MSN Messenger protocol    */
-/* DON'T TAKE AN UNASSIGNED NUMBER! Talk to Rob or Sean if you'd like
+	PROTO_IRC,         /**< IRC protocol              */
-* to create a new PRPL. */
+	PROTO_FTP,         /**< FTP protocol              */
+	PROTO_VGATE,       /**< VGATE protocol            */
-#define PRPL_DESC(x)	"Allows gaim to use the " x " protocol.\n\n" \
+	PROTO_JABBER,      /**< Jabber protocol           */
-			"Now that you have loaded this protocol, use the " \
+	PROTO_NAPSTER,     /**< Napster/OpenNAP protocol  */
-			"Account Editor to add an account that uses this " \
+	PROTO_ZEPHYR,      /**< MIT Zephyr protocol       */
-			"protocol. You can access the Account Editor from " \
+	PROTO_GADUGADU,    /**< Gadu-Gadu protocol        */
-			"the \"Accounts\" button on the login window or " \
+	PROTO_SAMETIME,    /**< SameTime protocol         */
-			"in the \"Tools\" menu in the buddy list window."
+	PROTO_TLEN,        /**< TLEN protocol             */
+	PROTO_RVP,         /**< RVP protocol              */
+	PROTO_BACKRUB,     /**< Instant Massager protocol */
+	PROTO_UNTAKEN      /**< Untaken protocol number   */
+} 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
+* Protocol options
-* your computer's time. We wouldn't need this if everyone used NTP. */
+*
-#define OPT_PROTO_CORRECT_TIME      0x00000002
+* These should all be stuff that some plugins can do and others can't.
-/* 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. */
+typedef enum
-#define OPT_PROTO_UNIQUE_CHATNAME   0x00000004
+{
-/* IRC, Jabber let you have chat room topics */
+	/**
-#define OPT_PROTO_CHAT_TOPIC        0x00000008
+	 * TOC and Oscar send HTML-encoded messages;
-/* Zephyr doesn't require passwords, so there's no need for a password prompt */
+	 * most other protocols don't.
-#define OPT_PROTO_NO_PASSWORD       0x00000010
+	 */
-/* MSN and Yahoo notify you when you have new mail */
+//	#define OPT_PROTO_HTML            0x00000001 this should be per-connection */
-#define OPT_PROTO_MAIL_CHECK        0x00000020
-/* Oscar and Jabber have buddy icons */
+	/**
-#define OPT_PROTO_BUDDY_ICON        0x00000040
+	 * Synchronize the time between the local computer and the server.
-/* Oscar lets you send images in direct IMs */
+	 *
-#define OPT_PROTO_IM_IMAGE          0x00000080
+	 * TOC and Oscar have signon time, and the server's time needs
-/* Passwords in IRC are optional, and are needed for certain functionality. */
+	 * to be adjusted to match your computer's time.
-#define OPT_PROTO_PASSWORD_OPTIONAL 0x00000100
+	 *
+	 * 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;
+* A protocol plugin structure.
-	int options;
+*
-	struct gaim_plugin *plug;
+* 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 */
+	/** Returns the XPM associated with the given user class. */
-	/* char *checkbox; this should be per-connection */
-	/* 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);
 	/* user_opts is a GList* of g_malloc'd struct proto_user_opts */
 	GList *user_opts;
 	GList *(* buddy_menu)(struct gaim_connection *, char *);
 	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
+	 * A lot of these (like get_dir) are protocol-dependent and should
-	 * (i.e. the prpl says you can set your dir info, the ui shows a dialog and needs to call
+	 * be removed. ones like set_dir (which is also protocol-dependent)
-	 * set_dir in order to set it) */
+	 * 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);
 	void (* set_away)	(struct gaim_connection *, char *state, char *message);
 	void (* get_away)       (struct gaim_connection *, char *who);
 							   const char *city,
 							   const char *state,
 							   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);
 	void (* rem_deny)	(struct gaim_connection *, const char *name);
 	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 *);
 	/* new user registration */
 	void (* register_user)	(struct gaim_account *);
 	/* get "chat buddy" info and away message */
 	void (* get_cb_info)	(struct gaim_connection *, int, char *who);
 	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 *);
 	/* this is really bad. */
 	void (* convo_closed)   (struct gaim_connection *, char *who);
 	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 what should actually load the protocol. pass it the protocol's initializer */
+* This is mostly just for main.c, when it initializes the protocols.
-extern gboolean load_prpl(struct prpl *);
+*/
-extern void load_protocol(proto_init);
+void static_proto_init();
-extern void unload_protocol(struct prpl *);
-extern gint proto_compare(struct prpl *, struct prpl *);
+/**
+* Loads a protocol plugin.
-extern struct prpl *find_prpl(int);
+*
-extern void do_proto_menu();
+* @param prpl The initial protocol plugin structure.
+*
-extern void show_got_added(struct gaim_connection *, const char *,
+* @return @c TRUE if the protocol was loaded, or @c FALSE otherwise.
-			   const char *, const char *, const char *);
+*/
+gboolean load_prpl(struct prpl *prpl);
-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 *);
+* Loads a statically compiled protocol plugin.
+*
-extern void connection_has_mail(struct gaim_connection *, int, const char *, const char *, const char *);
+* @param pi The initialization function.
+*/
-extern void set_icon_data(struct gaim_connection *, char *, void *, int);
+void load_protocol(proto_init pi);
-extern void *get_icon_data(struct gaim_connection *, char *, int *);
+/**
+* Unloads a protocol plugin.
+*
+* @param prpl The protocol plugin to unload.
+*/
+extern void unload_protocol(struct prpl *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);
+/**
+* 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);
+/**
+* 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);
+/**
+* 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);
+/**
+* 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);
+/**
+* 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_ */

Mercurial > pidgin

comparison src/prpl.h @ 4557:53ce3af93edb