9130
|
1 /**
|
|
2 * @file cmds.h Commands API
|
|
3 * @ingroup core
|
|
4 *
|
|
5 * Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com
|
|
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_
|
|
24 #define _GAIM_CMDS_H
|
|
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.
|
|
100 * 'W' Matches a single word, and applies the default formatting to it.
|
|
101 * 's' Matches the rest of the arguments after this point, as a single string.
|
|
102 * 'S' Same as 's' but applies the default formatting to the matched string.
|
|
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.
|
|
114 * @param helpstr This is a string describing how to use the command.
|
|
115 * @return A pointer to a GaimCmdId. This is only used for calling gaim_cmd_unregister, which frees it.
|
|
116 * Returns @c NULL on failure.
|
|
117 */
|
|
118 GaimCmdId *gaim_cmd_register(const gchar *cmd, const gchar *args, GaimCmdPriority p, GaimCmdFlag f,
|
|
119 const gchar *prpl_id, GaimCmdFunc func, const gchar *helpstr);
|
|
120
|
|
121 /**
|
|
122 * Unregister a command with the core.
|
|
123 *
|
|
124 * All registered commands must be unregistered, if they're registered by a plugin
|
|
125 * or something else that might go away. Normally this is called when the plugin
|
|
126 * unloads itself.
|
|
127 *
|
|
128 * @param id The GaimCmdId to unregister. It is freed after being unregistered.
|
|
129 */
|
|
130 void gaim_cmd_unregister(GaimCmdId *id);
|
|
131
|
|
132 /**
|
|
133 * Do a command.
|
|
134 *
|
|
135 * Normally the UI calls this to perform a command. This might also be useful
|
|
136 * if aliases are ever implemented.
|
|
137 *
|
|
138 * @param conv The conversation the command was typed in.
|
|
139 * @param cmd The command the user typed (including all arguments) as a single string.
|
|
140 * The caller doesn't have to do any parsing, except removing the command
|
|
141 * prefix, which the core has no knowledge of. cmd should not contain the
|
|
142 * default formatting, but should contain any user supplied formatting.
|
|
143 * @param errormsg If the command failed and errormsg is not NULL, it is filled in with
|
|
144 * the appropriate error message. It should be freed by the caller with
|
|
145 * g_free().
|
|
146 * @return A GaimCmdStatus indicated if the command succeeded or failed.
|
|
147 */
|
|
148 GaimCmdStatus gaim_cmd_do_command(GaimConversation *conv, const gchar *cmd, gchar **errormsg);
|
|
149
|
|
150 /**
|
|
151 * List registered commands.
|
|
152 *
|
|
153 * Returns a GList (which must be freed by the caller) of all commands
|
|
154 * that are valid in the context of conv, or all commands, if conv is
|
|
155 * @c NULL. Don't keep this list around past the main loop, or anything else
|
|
156 * that might unregister a command, as the char*'s used get freed then.
|
|
157 *
|
|
158 * @param conv The conversation, or @c NULL.
|
|
159 * @return A GList of const char*, which must be freed with g_list_free().
|
|
160 */
|
|
161 GList *gaim_cmd_list(GaimConversation *conv);
|
|
162
|
|
163 /**
|
|
164 * Get the help string for a command.
|
|
165 *
|
|
166 * Returns the help strings for a given command in the form of a GList,
|
|
167 * one node for each matching command.
|
|
168 *
|
|
169 * @param conv The conversation, or @c NULL for no context.
|
|
170 * @param cmd The command. No wildcards accepted, but returns help for all
|
|
171 * commands if @c NULL.
|
|
172 * @return A GList of const char*s, which is the help string
|
|
173 * for that command.
|
|
174 */
|
|
175 GList *gaim_cmd_help(GaimConversation *conv, const gchar *cmd);
|
|
176
|
|
177 /*@}*/
|
|
178
|
|
179 #ifdef __cplusplus
|
|
180 }
|
|
181 #endif
|
|
182
|
|
183 #endif /* _GAIM_CMDS_H_ */
|