Mercurial > pidgin
comparison src/cmds.h @ 9130:933a19e3a6b3
[gaim-migrate @ 9908]
This puts the core in charge of irc-style /commands, which is way cool. Tim did most of the work, I've just been keeping it in sync with CVS, and slowly adding more commands to jabber.
committer: Tailor Script <tailor@pidgin.im>
author | Nathan Walp <nwalp@pidgin.im> |
---|---|
date | Sun, 30 May 2004 19:34:21 +0000 |
parents | |
children | 6cf85ec42f50 |
comparison
equal
deleted
inserted
replaced
9129:3e94a77ee0c7 | 9130:933a19e3a6b3 |
---|---|
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_ */ |