2 * @file cmds.h Commands API
4 * @see @ref cmd-signals
7 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
24 #ifndef _PURPLE_CMDS_H_
25 #define _PURPLE_CMDS_H_
27 #include "conversation.h"
29 /**************************************************************************/
30 /** @name Structures */
31 /**************************************************************************/
34 /** The possible results of running a command with purple_cmd_do_command(). */
35 typedef enum _PurpleCmdStatus {
37 PURPLE_CMD_STATUS_FAILED,
38 PURPLE_CMD_STATUS_NOT_FOUND,
39 PURPLE_CMD_STATUS_WRONG_ARGS,
40 PURPLE_CMD_STATUS_WRONG_PRPL,
41 PURPLE_CMD_STATUS_WRONG_TYPE
44 /** Commands registered with the core return one of these values when run.
45 * Normally, a command will want to return one of the first two; in some
46 * unusual cases, you might want to have several functions called for a
47 * particular command; in this case, they should return
48 * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
49 * commands with the same name.
51 typedef enum _PurpleCmdRet {
52 PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */
53 PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/
54 PURPLE_CMD_RET_CONTINUE /**< Continue, looking for other commands with the same name to call. */
57 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
59 /** A function implementing a command, as passed to purple_cmd_register().
61 * @todo document the arguments to these functions.
63 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
64 gchar **args, gchar **error, void *data);
65 /** A unique integer representing a command registered with
66 * purple_cmd_register(), which can subsequently be passed to
67 * purple_cmd_unregister() to unregister that command.
69 typedef guint PurpleCmdId;
71 typedef enum _PurpleCmdPriority {
72 PURPLE_CMD_P_VERY_LOW = -1000,
74 PURPLE_CMD_P_DEFAULT = 1000,
75 PURPLE_CMD_P_PRPL = 2000,
76 PURPLE_CMD_P_PLUGIN = 3000,
77 PURPLE_CMD_P_ALIAS = 4000,
78 PURPLE_CMD_P_HIGH = 5000,
79 PURPLE_CMD_P_VERY_HIGH = 6000
82 /** Flags used to set various properties of commands. Every command should
83 * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
84 * order to be even slighly useful.
86 * @see purple_cmd_register
88 typedef enum _PurpleCmdFlag {
89 /** Command is usable in IMs. */
90 PURPLE_CMD_FLAG_IM = 0x01,
91 /** Command is usable in multi-user chats. */
92 PURPLE_CMD_FLAG_CHAT = 0x02,
93 /** Command is usable only for a particular prpl. */
94 PURPLE_CMD_FLAG_PRPL_ONLY = 0x04,
95 /** Incorrect arguments to this command should be accepted anyway. */
96 PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08
106 /**************************************************************************/
107 /** @name Commands API */
108 /**************************************************************************/
112 * Register a new command with the core.
114 * The command will only happen if commands are enabled,
115 * which is a UI pref. UIs don't have to support commands at all.
117 * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces
118 * or other white space.
119 * @param args A string of characters describing to libpurple how to parse this
120 * command's arguments. If what the user types doesn't match this
121 * pattern, libpurple will keep looking for another command, unless
122 * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f.
123 * This string should contain no whitespace, and use a single
124 * character for each argument. The recognized characters are:
126 * <li><tt>'w'</tt>: Matches a single word.</li>
127 * <li><tt>'W'</tt>: Matches a single word, with formatting.</li>
128 * <li><tt>'s'</tt>: Matches the rest of the arguments after this
129 * point, as a single string.</li>
130 * <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li>
132 * If args is the empty string, then the command accepts no arguments.
133 * The args passed to the callback @a func will be a @c NULL
134 * terminated array of @c NULL terminated strings, and will always
135 * match the number of arguments asked for, unless
136 * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
137 * @param p This is the priority. Higher priority commands will be run first,
138 * and usually the first command will stop any others from being
140 * @param f Flags specifying various options about this command, combined with
141 * <tt>|</tt> (bitwise OR). You need to at least pass one of
142 * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
143 * order for the command to ever actually be called.
144 * @param prpl_id If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id
145 * of the prpl to which the command applies (such as
146 * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter
147 * is ignored; pass @c NULL (or a humourous string of your
149 * @param func This is the function to call when someone enters this command.
150 * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to
151 * use the command. The preferred format of this string is the
152 * command's name, followed by a space and any arguments it
153 * accepts (if it takes any arguments, otherwise no space),
154 * followed by a colon, two spaces, and a description of the
155 * command in sentence form. Do not include a slash before the
157 * @param data User defined data to pass to the #PurpleCmdFunc @a f.
158 * @return A #PurpleCmdId, which is only used for calling
159 * #purple_cmd_unregister, or @a 0 on failure.
161 PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
162 const gchar *prpl_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
165 * Unregister a command with the core.
167 * All registered commands must be unregistered, if they're registered by a plugin
168 * or something else that might go away. Normally this is called when the plugin
171 * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
173 void purple_cmd_unregister(PurpleCmdId id);
178 * Normally the UI calls this to perform a command. This might also be useful
179 * if aliases are ever implemented.
181 * @param conv The conversation the command was typed in.
182 * @param cmdline The command the user typed (including all arguments) as a single string.
183 * The caller doesn't have to do any parsing, except removing the command
184 * prefix, which the core has no knowledge of. cmd should not contain any
185 * formatting, and should be in plain text (no html entities).
186 * @param markup This is the same as cmd, but is the formatted version. It should be in
187 * HTML, with < > and &, at least, escaped to html entities, and should
188 * include both the default formatting and any extra manual formatting.
189 * @param errormsg If the command failed errormsg is filled in with the appropriate error
190 * message. It must be freed by the caller with g_free().
191 * @return A #PurpleCmdStatus indicating if the command succeeded or failed.
193 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
194 const gchar *markup, gchar **errormsg);
197 * List registered commands.
199 * Returns a <tt>GList</tt> (which must be freed by the caller) of all commands
200 * that are valid in the context of @a conv, or all commands, if @a conv is @c
201 * NULL. Don't keep this list around past the main loop, or anything else that
202 * might unregister a command, as the <tt>const char *</tt>'s used get freed
205 * @param conv The conversation, or @c NULL.
206 * @return A @c GList of <tt>const char *</tt>, which must be freed with
207 * <tt>g_list_free()</tt>.
209 GList *purple_cmd_list(PurpleConversation *conv);
212 * Get the help string for a command.
214 * Returns the help strings for a given command in the form of a GList,
215 * one node for each matching command.
217 * @param conv The conversation, or @c NULL for no context.
218 * @param cmd The command. No wildcards accepted, but returns help for all
219 * commands if @c NULL.
220 * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string
223 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
226 * Get the handle for the commands API
230 gpointer purple_cmds_get_handle(void);
233 * Initialize the commands subsystem.
236 void purple_cmds_init(void);
239 * Uninitialize the commands subsystem.
242 void purple_cmds_uninit(void);
250 #endif /* _PURPLE_CMDS_H_ */