Mercurial > pidgin.yaz
annotate src/cmds.h @ 9308:b3bda982996b
[gaim-migrate @ 10116]
Yikes.
committer: Tailor Script <tailor@pidgin.im>
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Sat, 19 Jun 2004 04:57:43 +0000 |
parents | 848aeb69250d |
children | 5f6ba17ef9f5 |
rev | line source |
---|---|
9130 | 1 /** |
2 * @file cmds.h Commands API | |
3 * @ingroup core | |
4 * | |
9143
9e3d4722d86e
[gaim-migrate @ 9927]
Christian Hammond <chipx86@chipx86.com>
parents:
9142
diff
changeset
|
5 * Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com> |
9130 | 6 * |
7 * This program is free software; you can redistribute it and/or modify | |
8 * it under the terms of the GNU General Public License as published by | |
9 * the Free Software Foundation; either version 2 of the License, or | |
10 * (at your option) any later version. | |
11 * | |
12 * This program is distributed in the hope that it will be useful, | |
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 * GNU General Public License for more details. | |
16 * | |
17 * You should have received a copy of the GNU General Public License | |
18 * along with this program; if not, write to the Free Software | |
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
20 * | |
21 */ | |
22 | |
23 #ifndef _GAIM_CMDS_H_ | |
9142
6cf85ec42f50
[gaim-migrate @ 9926]
Christian Hammond <chipx86@chipx86.com>
parents:
9130
diff
changeset
|
24 #define _GAIM_CMDS_H_ |
9130 | 25 |
26 #include "conversation.h" | |
27 | |
28 /************************************************************************** | |
29 * @name Structures | |
30 **************************************************************************/ | |
31 /*@{*/ | |
32 | |
33 typedef enum _GaimCmdPriority GaimCmdPriority; | |
34 typedef enum _GaimCmdFlag GaimCmdFlag; | |
35 typedef enum _GaimCmdStatus GaimCmdStatus; | |
36 typedef enum _GaimCmdRet GaimCmdRet; | |
37 | |
38 enum _GaimCmdStatus { | |
39 GAIM_CMD_STATUS_OK, | |
40 GAIM_CMD_STATUS_FAILED, | |
41 GAIM_CMD_STATUS_NOT_FOUND, | |
42 GAIM_CMD_STATUS_WRONG_ARGS, | |
43 GAIM_CMD_STATUS_WRONG_PRPL, | |
44 GAIM_CMD_STATUS_WRONG_TYPE, | |
45 }; | |
46 | |
47 enum _GaimCmdRet { | |
48 GAIM_CMD_RET_OK, /**< Everything's okay. Don't look for another command to call. */ | |
49 GAIM_CMD_RET_FAILED, /**< The command failed, but stop looking.*/ | |
50 GAIM_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */ | |
51 }; | |
52 | |
53 typedef GaimCmdRet (*GaimCmdFunc)(GaimConversation *, const gchar *cmd, gchar **args, gchar **error); | |
54 typedef guint GaimCmdId; | |
55 | |
56 enum _GaimCmdPriority { | |
57 GAIM_CMD_P_VERY_LOW = -1000, | |
58 GAIM_CMD_P_LOW = 0, | |
59 GAIM_CMD_P_DEFAULT = 1000, | |
60 GAIM_CMD_P_PRPL = 2000, | |
61 GAIM_CMD_P_PLUGIN = 3000, | |
62 GAIM_CMD_P_ALIAS = 4000, | |
63 GAIM_CMD_P_HIGH = 5000, | |
64 GAIM_CMD_P_VERYHIGH = 6000, | |
65 }; | |
66 | |
67 enum _GaimCmdFlag { | |
68 GAIM_CMD_FLAG_IM = 0x01, | |
69 GAIM_CMD_FLAG_CHAT = 0x02, | |
70 GAIM_CMD_FLAG_PRPL_ONLY = 0x04, | |
71 GAIM_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08, | |
72 }; | |
73 | |
74 | |
75 /*@}*/ | |
76 | |
77 #ifdef __cplusplus | |
78 extern "C" { | |
79 #endif | |
80 | |
81 /************************************************************************** | |
82 * @name Commands API | |
83 **************************************************************************/ | |
84 /*@{*/ | |
85 | |
86 /** | |
87 * Register a new command with the core. | |
88 * | |
89 * The command will only happen if commands are enabled, | |
90 * which is a UI pref. UIs don't have to support commands at all. | |
91 * | |
92 * @param cmd The command. This should be a UTF8 (or ASCII) string, with no spaces | |
93 * or other white space. | |
94 * @param args This tells Gaim how to parse the arguments to the command for you. | |
95 * If what the user types doesn't match, Gaim will keep looking for another | |
96 * command, unless the flag @c GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed in f. | |
97 * This string contains no whitespace, and uses a single character for each argument. | |
98 * The recognized characters are: | |
99 * 'w' Matches a single word. | |
9175 | 100 * 'W' Matches a single word, with formatting. |
9130 | 101 * 's' Matches the rest of the arguments after this point, as a single string. |
9175 | 102 * 'S' Same as 's' but with formatting. |
9130 | 103 * If args is the empty string, then the command accepts no arguments. |
104 * The args passed to callback func will be a @c NULL terminated array of null | |
105 * terminated strings, and will always match the number of arguments asked for, | |
106 * unless GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed. | |
107 * @param p This is the priority. Higher priority commands will be run first, and usually the | |
108 * first command will stop any others from being called. | |
109 * @param f These are the flags. You need to at least pass one of GAIM_CMD_FLAG_IM or | |
110 * GAIM_CMD_FLAG_CHAT (can may pass both) in order for the command to ever actually | |
111 * be called. | |
112 * @param prpl_id This is the prpl's id string. This is only meaningful is the proper flag is set. | |
113 * @param func This is the function to call when someone enters this command. | |
9247 | 114 * @param helpstr This is a whitespace sensitive, UTF-8, HTML string describing how to use the command. |
9256 | 115 * The preferred format of this string shall be the commands name, followed by a space |
9247 | 116 * and any arguments it accpets (if it takes any arguments, otherwise no space), follow |
9256 | 117 * by a colon, two spaces, and a description of the command in sentence form. No slash |
9247 | 118 * before the command name. |
9130 | 119 * @return A pointer to a GaimCmdId. This is only used for calling gaim_cmd_unregister, which frees it. |
120 * Returns @c NULL on failure. | |
121 */ | |
122 GaimCmdId *gaim_cmd_register(const gchar *cmd, const gchar *args, GaimCmdPriority p, GaimCmdFlag f, | |
123 const gchar *prpl_id, GaimCmdFunc func, const gchar *helpstr); | |
124 | |
125 /** | |
126 * Unregister a command with the core. | |
127 * | |
128 * All registered commands must be unregistered, if they're registered by a plugin | |
129 * or something else that might go away. Normally this is called when the plugin | |
130 * unloads itself. | |
131 * | |
132 * @param id The GaimCmdId to unregister. It is freed after being unregistered. | |
133 */ | |
134 void gaim_cmd_unregister(GaimCmdId *id); | |
135 | |
136 /** | |
137 * Do a command. | |
138 * | |
139 * Normally the UI calls this to perform a command. This might also be useful | |
140 * if aliases are ever implemented. | |
141 * | |
142 * @param conv The conversation the command was typed in. | |
9175 | 143 * @param cmdline The command the user typed (including all arguments) as a single string. |
9130 | 144 * The caller doesn't have to do any parsing, except removing the command |
145 * prefix, which the core has no knowledge of. cmd should not contain the | |
9175 | 146 * any formatting, and should be in plain text (no html entities). |
147 * @param markup This is the same as cmd, but is the formatted version. It should be in | |
148 * HTML, with < > and &, at least, escaped to html entities, and should | |
149 * include both the default formatting and any extra manual formatting. | |
9130 | 150 * @param errormsg If the command failed and errormsg is not NULL, it is filled in with |
151 * the appropriate error message. It should be freed by the caller with | |
152 * g_free(). | |
153 * @return A GaimCmdStatus indicated if the command succeeded or failed. | |
154 */ | |
9175 | 155 GaimCmdStatus gaim_cmd_do_command(GaimConversation *conv, const gchar *cmdline, |
156 const gchar *markup, gchar **errormsg); | |
9130 | 157 |
158 /** | |
159 * List registered commands. | |
160 * | |
161 * Returns a GList (which must be freed by the caller) of all commands | |
162 * that are valid in the context of conv, or all commands, if conv is | |
163 * @c NULL. Don't keep this list around past the main loop, or anything else | |
164 * that might unregister a command, as the char*'s used get freed then. | |
165 * | |
166 * @param conv The conversation, or @c NULL. | |
167 * @return A GList of const char*, which must be freed with g_list_free(). | |
168 */ | |
169 GList *gaim_cmd_list(GaimConversation *conv); | |
170 | |
171 /** | |
172 * Get the help string for a command. | |
173 * | |
174 * Returns the help strings for a given command in the form of a GList, | |
175 * one node for each matching command. | |
176 * | |
177 * @param conv The conversation, or @c NULL for no context. | |
178 * @param cmd The command. No wildcards accepted, but returns help for all | |
179 * commands if @c NULL. | |
180 * @return A GList of const char*s, which is the help string | |
181 * for that command. | |
182 */ | |
183 GList *gaim_cmd_help(GaimConversation *conv, const gchar *cmd); | |
184 | |
185 /*@}*/ | |
186 | |
187 #ifdef __cplusplus | |
188 } | |
189 #endif | |
190 | |
191 #endif /* _GAIM_CMDS_H_ */ |