Mercurial > pidgin.yaz
annotate src/cmds.h @ 10793:ccf5e33e3239
[gaim-migrate @ 12435]
this should fix the infinite looping.
I bet we still infinite loop in the debug window, but the fix for that is
obvious, don't have debug statements in the expose event :P
Someone should double check this code works right in say, rtl languages
and stuff, and genereally look for bugs.
committer: Tailor Script <tailor@pidgin.im>
author | Tim Ringenbach <marv@pidgin.im> |
---|---|
date | Fri, 08 Apr 2005 01:31:50 +0000 |
parents | 19de830330cf |
children | ca559e2b1d0a |
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 #ifndef _GAIM_CMDS_H_ | |
9142
6cf85ec42f50
[gaim-migrate @ 9926]
Christian Hammond <chipx86@chipx86.com>
parents:
9130
diff
changeset
|
23 #define _GAIM_CMDS_H_ |
9130 | 24 |
25 #include "conversation.h" | |
26 | |
10231 | 27 /**************************************************************************/ |
28 /** @name Structures */ | |
29 /**************************************************************************/ | |
9130 | 30 /*@{*/ |
31 | |
9939 | 32 typedef enum _GaimCmdPriority GaimCmdPriority; |
33 typedef enum _GaimCmdFlag GaimCmdFlag; | |
34 typedef enum _GaimCmdStatus GaimCmdStatus; | |
35 typedef enum _GaimCmdRet GaimCmdRet; | |
9130 | 36 |
37 enum _GaimCmdStatus { | |
38 GAIM_CMD_STATUS_OK, | |
39 GAIM_CMD_STATUS_FAILED, | |
40 GAIM_CMD_STATUS_NOT_FOUND, | |
41 GAIM_CMD_STATUS_WRONG_ARGS, | |
42 GAIM_CMD_STATUS_WRONG_PRPL, | |
43 GAIM_CMD_STATUS_WRONG_TYPE, | |
44 }; | |
45 | |
46 enum _GaimCmdRet { | |
47 GAIM_CMD_RET_OK, /**< Everything's okay. Don't look for another command to call. */ | |
48 GAIM_CMD_RET_FAILED, /**< The command failed, but stop looking.*/ | |
49 GAIM_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */ | |
50 }; | |
51 | |
9597 | 52 #define GAIM_CMD_FUNC(func) ((GaimCmdFunc)func) |
53 | |
54 typedef GaimCmdRet (*GaimCmdFunc)(GaimConversation *, const gchar *cmd, | |
55 gchar **args, gchar **error, void *data); | |
9130 | 56 typedef guint GaimCmdId; |
57 | |
58 enum _GaimCmdPriority { | |
59 GAIM_CMD_P_VERY_LOW = -1000, | |
60 GAIM_CMD_P_LOW = 0, | |
61 GAIM_CMD_P_DEFAULT = 1000, | |
62 GAIM_CMD_P_PRPL = 2000, | |
63 GAIM_CMD_P_PLUGIN = 3000, | |
64 GAIM_CMD_P_ALIAS = 4000, | |
65 GAIM_CMD_P_HIGH = 5000, | |
66 GAIM_CMD_P_VERYHIGH = 6000, | |
67 }; | |
68 | |
69 enum _GaimCmdFlag { | |
70 GAIM_CMD_FLAG_IM = 0x01, | |
71 GAIM_CMD_FLAG_CHAT = 0x02, | |
72 GAIM_CMD_FLAG_PRPL_ONLY = 0x04, | |
73 GAIM_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08, | |
74 }; | |
75 | |
76 | |
77 /*@}*/ | |
78 | |
79 #ifdef __cplusplus | |
80 extern "C" { | |
81 #endif | |
82 | |
10231 | 83 /**************************************************************************/ |
84 /** @name Commands API */ | |
85 /**************************************************************************/ | |
9130 | 86 /*@{*/ |
87 | |
88 /** | |
89 * Register a new command with the core. | |
90 * | |
91 * The command will only happen if commands are enabled, | |
92 * which is a UI pref. UIs don't have to support commands at all. | |
93 * | |
94 * @param cmd The command. This should be a UTF8 (or ASCII) string, with no spaces | |
95 * or other white space. | |
96 * @param args This tells Gaim how to parse the arguments to the command for you. | |
97 * If what the user types doesn't match, Gaim will keep looking for another | |
98 * command, unless the flag @c GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed in f. | |
99 * This string contains no whitespace, and uses a single character for each argument. | |
100 * The recognized characters are: | |
101 * 'w' Matches a single word. | |
9175 | 102 * 'W' Matches a single word, with formatting. |
9130 | 103 * 's' Matches the rest of the arguments after this point, as a single string. |
9175 | 104 * 'S' Same as 's' but with formatting. |
9130 | 105 * If args is the empty string, then the command accepts no arguments. |
106 * The args passed to callback func will be a @c NULL terminated array of null | |
107 * terminated strings, and will always match the number of arguments asked for, | |
108 * unless GAIM_CMD_FLAG_ALLOW_WRONG_ARGS is passed. | |
109 * @param p This is the priority. Higher priority commands will be run first, and usually the | |
110 * first command will stop any others from being called. | |
111 * @param f These are the flags. You need to at least pass one of GAIM_CMD_FLAG_IM or | |
112 * GAIM_CMD_FLAG_CHAT (can may pass both) in order for the command to ever actually | |
113 * be called. | |
114 * @param prpl_id This is the prpl's id string. This is only meaningful is the proper flag is set. | |
115 * @param func This is the function to call when someone enters this command. | |
9247 | 116 * @param helpstr This is a whitespace sensitive, UTF-8, HTML string describing how to use the command. |
9256 | 117 * The preferred format of this string shall be the commands name, followed by a space |
9247 | 118 * and any arguments it accpets (if it takes any arguments, otherwise no space), follow |
9256 | 119 * by a colon, two spaces, and a description of the command in sentence form. No slash |
9247 | 120 * before the command name. |
9939 | 121 * @param data User defined data to pass to the GaimCmdFunc |
9343 | 122 * @return A GaimCmdId. This is only used for calling gaim_cmd_unregister. |
10052 | 123 * Returns 0 on failure. |
9130 | 124 */ |
9343 | 125 GaimCmdId gaim_cmd_register(const gchar *cmd, const gchar *args, GaimCmdPriority p, GaimCmdFlag f, |
9597 | 126 const gchar *prpl_id, GaimCmdFunc func, const gchar *helpstr, void *data); |
9130 | 127 |
128 /** | |
129 * Unregister a command with the core. | |
130 * | |
131 * All registered commands must be unregistered, if they're registered by a plugin | |
132 * or something else that might go away. Normally this is called when the plugin | |
133 * unloads itself. | |
134 * | |
9343 | 135 * @param id The GaimCmdId to unregister. |
9130 | 136 */ |
9343 | 137 void gaim_cmd_unregister(GaimCmdId id); |
9130 | 138 |
139 /** | |
140 * Do a command. | |
141 * | |
142 * Normally the UI calls this to perform a command. This might also be useful | |
143 * if aliases are ever implemented. | |
144 * | |
145 * @param conv The conversation the command was typed in. | |
9175 | 146 * @param cmdline The command the user typed (including all arguments) as a single string. |
9130 | 147 * The caller doesn't have to do any parsing, except removing the command |
9597 | 148 * prefix, which the core has no knowledge of. cmd should not contain any |
149 * formatting, and should be in plain text (no html entities). | |
9175 | 150 * @param markup This is the same as cmd, but is the formatted version. It should be in |
151 * HTML, with < > and &, at least, escaped to html entities, and should | |
152 * include both the default formatting and any extra manual formatting. | |
10788
19de830330cf
[gaim-migrate @ 12429]
Luke Schierer <lschiere@pidgin.im>
parents:
10231
diff
changeset
|
153 * @param errormsg If the command failed errormsg is filled in with the appropriate error |
19de830330cf
[gaim-migrate @ 12429]
Luke Schierer <lschiere@pidgin.im>
parents:
10231
diff
changeset
|
154 * message. It must be freed by the caller with g_free(). |
9130 | 155 * @return A GaimCmdStatus indicated if the command succeeded or failed. |
156 */ | |
9175 | 157 GaimCmdStatus gaim_cmd_do_command(GaimConversation *conv, const gchar *cmdline, |
158 const gchar *markup, gchar **errormsg); | |
9130 | 159 |
160 /** | |
161 * List registered commands. | |
162 * | |
163 * Returns a GList (which must be freed by the caller) of all commands | |
164 * that are valid in the context of conv, or all commands, if conv is | |
165 * @c NULL. Don't keep this list around past the main loop, or anything else | |
166 * that might unregister a command, as the char*'s used get freed then. | |
167 * | |
168 * @param conv The conversation, or @c NULL. | |
169 * @return A GList of const char*, which must be freed with g_list_free(). | |
170 */ | |
171 GList *gaim_cmd_list(GaimConversation *conv); | |
172 | |
173 /** | |
174 * Get the help string for a command. | |
175 * | |
176 * Returns the help strings for a given command in the form of a GList, | |
177 * one node for each matching command. | |
178 * | |
179 * @param conv The conversation, or @c NULL for no context. | |
180 * @param cmd The command. No wildcards accepted, but returns help for all | |
181 * commands if @c NULL. | |
182 * @return A GList of const char*s, which is the help string | |
183 * for that command. | |
184 */ | |
185 GList *gaim_cmd_help(GaimConversation *conv, const gchar *cmd); | |
186 | |
187 /*@}*/ | |
188 | |
189 #ifdef __cplusplus | |
190 } | |
191 #endif | |
192 | |
193 #endif /* _GAIM_CMDS_H_ */ |