annotate libpurple/cmds.h @ 20566:3ef40e8de6ab

Fix some crashes with animated smileys. Fixes #3179, #938, #3134, #2872, #1594
author Daniel Atallah <daniel.atallah@gmail.com>
date Thu, 20 Sep 2007 03:05:54 +0000
parents baf144ea4f9b
children 7d0ef1e3ac4f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
1 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
2 * @file cmds.h Commands API
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
3 * @ingroup core
20074
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
4 */
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
5
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
6 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
7 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
8 * This program is free software; you can redistribute it and/or modify
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
9 * it under the terms of the GNU General Public License as published by
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
10 * the Free Software Foundation; either version 2 of the License, or
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
11 * (at your option) any later version.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
12 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
13 * This program is distributed in the hope that it will be useful,
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
16 * GNU General Public License for more details.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
17 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
18 * You should have received a copy of the GNU General Public License
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
19 * along with this program; if not, write to the Free Software
19680
44b4e8bd759b The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
parents: 15823
diff changeset
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
21 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
22 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
23 #ifndef _PURPLE_CMDS_H_
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
24 #define _PURPLE_CMDS_H_
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
25
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
26 #include "conversation.h"
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
27
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
28 /**************************************************************************/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
29 /** @name Structures */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
30 /**************************************************************************/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
31 /*@{*/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
32
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
33 typedef enum _PurpleCmdPriority PurpleCmdPriority;
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
34 typedef enum _PurpleCmdFlag PurpleCmdFlag;
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
35 typedef enum _PurpleCmdStatus PurpleCmdStatus;
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
36 typedef enum _PurpleCmdRet PurpleCmdRet;
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
37
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
38 enum _PurpleCmdStatus {
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
39 PURPLE_CMD_STATUS_OK,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
40 PURPLE_CMD_STATUS_FAILED,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
41 PURPLE_CMD_STATUS_NOT_FOUND,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
42 PURPLE_CMD_STATUS_WRONG_ARGS,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
43 PURPLE_CMD_STATUS_WRONG_PRPL,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
44 PURPLE_CMD_STATUS_WRONG_TYPE,
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
45 };
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
46
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
47 enum _PurpleCmdRet {
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
48 PURPLE_CMD_RET_OK, /**< Everything's okay. Don't look for another command to call. */
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
49 PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
50 PURPLE_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
51 };
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
52
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
53 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
54
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
55 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
56 gchar **args, gchar **error, void *data);
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
57 typedef guint PurpleCmdId;
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
58
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
59 enum _PurpleCmdPriority {
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
60 PURPLE_CMD_P_VERY_LOW = -1000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
61 PURPLE_CMD_P_LOW = 0,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
62 PURPLE_CMD_P_DEFAULT = 1000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
63 PURPLE_CMD_P_PRPL = 2000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
64 PURPLE_CMD_P_PLUGIN = 3000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
65 PURPLE_CMD_P_ALIAS = 4000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
66 PURPLE_CMD_P_HIGH = 5000,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
67 PURPLE_CMD_P_VERY_HIGH = 6000,
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
68 };
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
69
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
70 /** Flags used to set various properties of commands. Every command should
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
71 * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
72 * order to be even slighly useful.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
73 *
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
74 * @see purple_cmd_register
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
75 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
76 enum _PurpleCmdFlag {
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
77 /** Command is usable in IMs. */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
78 PURPLE_CMD_FLAG_IM = 0x01,
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
79 /** Command is usable in multi-user chats. */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
80 PURPLE_CMD_FLAG_CHAT = 0x02,
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
81 /** Command is usable only for a particular prpl. */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
82 PURPLE_CMD_FLAG_PRPL_ONLY = 0x04,
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
83 /** Incorrect arguments to this command should be accepted anyway. */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
84 PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08,
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
85 };
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
86
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
87
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
88 /*@}*/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
89
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
90 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
91 extern "C" {
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
92 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
93
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
94 /**************************************************************************/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
95 /** @name Commands API */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
96 /**************************************************************************/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
97 /*@{*/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
98
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
99 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
100 * Register a new command with the core.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
101 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
102 * The command will only happen if commands are enabled,
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
103 * which is a UI pref. UIs don't have to support commands at all.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
104 *
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
105 * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
106 * or other white space.
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
107 * @param args A string of characters describing to libpurple how to parse this
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
108 * command's arguments. If what the user types doesn't match this
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
109 * pattern, libpurple will keep looking for another command, unless
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
110 * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
111 * This string should contain no whitespace, and use a single
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
112 * character for each argument. The recognized characters are:
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
113 * <ul>
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
114 * <li><tt>'w'</tt>: Matches a single word.</li>
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
115 * <li><tt>'W'</tt>: Matches a single word, with formatting.</li>
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
116 * <li><tt>'s'</tt>: Matches the rest of the arguments after this
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
117 * point, as a single string.</li>
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
118 * <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li>
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
119 * </ul>
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
120 * If args is the empty string, then the command accepts no arguments.
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
121 * The args passed to the callback @a func will be a @c NULL
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
122 * terminated array of @c NULL terminated strings, and will always
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
123 * match the number of arguments asked for, unless
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
124 * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
125 * @param p This is the priority. Higher priority commands will be run first,
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
126 * and usually the first command will stop any others from being
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
127 * called.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
128 * @param f Flags specifying various options about this command, combined with
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
129 * <tt>|</tt> (bitwise OR). You need to at least pass one of
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
130 * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
131 * order for the command to ever actually be called.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
132 * @param prpl_id If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
133 * of the prpl to which the command applies (such as
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
134 * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
135 * is ignored; pass @c NULL (or a humourous string of your
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
136 * choice!).
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
137 * @param func This is the function to call when someone enters this command.
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
138 * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
139 * use the command. The preferred format of this string is the
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
140 * command's name, followed by a space and any arguments it
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
141 * accepts (if it takes any arguments, otherwise no space),
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
142 * followed by a colon, two spaces, and a description of the
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
143 * command in sentence form. Do not include a slash before the
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
144 * command name.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
145 * @param data User defined data to pass to the #PurpleCmdFunc @a f.
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
146 * @return A #PurpleCmdId, which is only used for calling
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
147 * #purple_cmd_unregister, or @a 0 on failure.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
148 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
149 PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
150 const gchar *prpl_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
151
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
152 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
153 * Unregister a command with the core.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
154 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
155 * All registered commands must be unregistered, if they're registered by a plugin
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
156 * or something else that might go away. Normally this is called when the plugin
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
157 * unloads itself.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
158 *
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
159 * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
160 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
161 void purple_cmd_unregister(PurpleCmdId id);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
162
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
163 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
164 * Do a command.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
165 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
166 * Normally the UI calls this to perform a command. This might also be useful
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
167 * if aliases are ever implemented.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
168 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
169 * @param conv The conversation the command was typed in.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
170 * @param cmdline The command the user typed (including all arguments) as a single string.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
171 * The caller doesn't have to do any parsing, except removing the command
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
172 * prefix, which the core has no knowledge of. cmd should not contain any
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
173 * formatting, and should be in plain text (no html entities).
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
174 * @param markup This is the same as cmd, but is the formatted version. It should be in
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
175 * HTML, with < > and &, at least, escaped to html entities, and should
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
176 * include both the default formatting and any extra manual formatting.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
177 * @param errormsg If the command failed errormsg is filled in with the appropriate error
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
178 * message. It must be freed by the caller with g_free().
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
179 * @return A #PurpleCmdStatus indicated if the command succeeded or failed.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
180 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
181 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
182 const gchar *markup, gchar **errormsg);
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
183
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
184 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
185 * List registered commands.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
186 *
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
187 * Returns a <tt>GList</tt> (which must be freed by the caller) of all commands
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
188 * that are valid in the context of @a conv, or all commands, if @a conv is @c
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
189 * NULL. Don't keep this list around past the main loop, or anything else that
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
190 * might unregister a command, as the <tt>const char *</tt>'s used get freed
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
191 * then.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
192 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
193 * @param conv The conversation, or @c NULL.
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
194 * @return A @c GList of <tt>const char *</tt>, which must be freed with
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
195 * <tt>g_list_free()</tt>.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
196 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
197 GList *purple_cmd_list(PurpleConversation *conv);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
198
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
199 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
200 * Get the help string for a command.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
201 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
202 * Returns the help strings for a given command in the form of a GList,
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
203 * one node for each matching command.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
204 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
205 * @param conv The conversation, or @c NULL for no context.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
206 * @param cmd The command. No wildcards accepted, but returns help for all
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
207 * commands if @c NULL.
20133
baf144ea4f9b Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents: 20074
diff changeset
208 * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
209 * for that command.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
210 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
211 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
212
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
213 /*@}*/
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
214
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
215 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
216 }
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
217 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
218
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15374
diff changeset
219 #endif /* _PURPLE_CMDS_H_ */