Mercurial > pidgin

comparison libpurple/cmds.h @ 20133:baf144ea4f9b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Let's document more of cmds.h!
author Will Thompson <will.thompson@collabora.co.uk>
date Tue, 18 Sep 2007 19:08:56 +0000
parents 6bf32c9e15a7
children 7d0ef1e3ac4f
comparison
equal deleted inserted replaced
20106:bacfbe346b47 20133:baf144ea4f9b
65 PURPLE_CMD_P_ALIAS = 4000, 65 PURPLE_CMD_P_ALIAS = 4000,
66 PURPLE_CMD_P_HIGH = 5000, 66 PURPLE_CMD_P_HIGH = 5000,
67 PURPLE_CMD_P_VERY_HIGH = 6000, 67 PURPLE_CMD_P_VERY_HIGH = 6000,
68 }; 68 };
69 69
70 /** Flags used to set various properties of commands. Every command should
71 * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
72 * order to be even slighly useful.
73 *
74 * @see purple_cmd_register
75 */
70 enum _PurpleCmdFlag { 76 enum _PurpleCmdFlag {
77 /** Command is usable in IMs. */
71 PURPLE_CMD_FLAG_IM = 0x01, 78 PURPLE_CMD_FLAG_IM = 0x01,
79 /** Command is usable in multi-user chats. */
72 PURPLE_CMD_FLAG_CHAT = 0x02, 80 PURPLE_CMD_FLAG_CHAT = 0x02,
81 /** Command is usable only for a particular prpl. */
73 PURPLE_CMD_FLAG_PRPL_ONLY = 0x04, 82 PURPLE_CMD_FLAG_PRPL_ONLY = 0x04,
83 /** Incorrect arguments to this command should be accepted anyway. */
74 PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08, 84 PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08,
75 }; 85 };
76 86
77 87
78 /*@}*/ 88 /*@}*/
90 * Register a new command with the core. 100 * Register a new command with the core.
91 * 101 *
92 * The command will only happen if commands are enabled, 102 * The command will only happen if commands are enabled,
93 * which is a UI pref. UIs don't have to support commands at all. 103 * which is a UI pref. UIs don't have to support commands at all.
94 * 104 *
95 * @param cmd The command. This should be a UTF8 (or ASCII) string, with no spaces 105 * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces
96 * or other white space. 106 * or other white space.
97 * @param args This tells Purple how to parse the arguments to the command for you. 107 * @param args A string of characters describing to libpurple how to parse this
98 * If what the user types doesn't match, Purple will keep looking for another 108 * command's arguments. If what the user types doesn't match this
99 * command, unless the flag @c PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in f. 109 * pattern, libpurple will keep looking for another command, unless
100 * This string contains no whitespace, and uses a single character for each argument. 110 * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f.
101 * The recognized characters are: 111 * This string should contain no whitespace, and use a single
102 * 'w' Matches a single word. 112 * character for each argument. The recognized characters are:
103 * 'W' Matches a single word, with formatting. 113 * <ul>
104 * 's' Matches the rest of the arguments after this point, as a single string. 114 * <li><tt>'w'</tt>: Matches a single word.</li>
105 * 'S' Same as 's' but with formatting. 115 * <li><tt>'W'</tt>: Matches a single word, with formatting.</li>
116 * <li><tt>'s'</tt>: Matches the rest of the arguments after this
117 * point, as a single string.</li>
118 * <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li>
119 * </ul>
106 * If args is the empty string, then the command accepts no arguments. 120 * If args is the empty string, then the command accepts no arguments.
107 * The args passed to callback func will be a @c NULL terminated array of null 121 * The args passed to the callback @a func will be a @c NULL
108 * terminated strings, and will always match the number of arguments asked for, 122 * terminated array of @c NULL terminated strings, and will always
109 * unless PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed. 123 * match the number of arguments asked for, unless
110 * @param p This is the priority. Higher priority commands will be run first, and usually the 124 * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
111 * first command will stop any others from being called. 125 * @param p This is the priority. Higher priority commands will be run first,
112 * @param f These are the flags. You need to at least pass one of PURPLE_CMD_FLAG_IM or 126 * and usually the first command will stop any others from being
113 * PURPLE_CMD_FLAG_CHAT (can may pass both) in order for the command to ever actually 127 * called.
114 * be called. 128 * @param f Flags specifying various options about this command, combined with
115 * @param prpl_id This is the prpl's id string. This is only meaningful if the proper flag is set. 129 * <tt>|</tt> (bitwise OR). You need to at least pass one of
130 * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
131 * order for the command to ever actually be called.
132 * @param prpl_id If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id
133 * of the prpl to which the command applies (such as
134 * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter
135 * is ignored; pass @c NULL (or a humourous string of your
136 * choice!).
116 * @param func This is the function to call when someone enters this command. 137 * @param func This is the function to call when someone enters this command.
117 * @param helpstr This is a whitespace sensitive, UTF-8, HTML string describing how to use the command. 138 * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to
118 * The preferred format of this string shall be the commands name, followed by a space 139 * use the command. The preferred format of this string is the
119 * and any arguments it accepts (if it takes any arguments, otherwise no space), followed 140 * command's name, followed by a space and any arguments it
120 * by a colon, two spaces, and a description of the command in sentence form. No slash 141 * accepts (if it takes any arguments, otherwise no space),
121 * before the command name. 142 * followed by a colon, two spaces, and a description of the
122 * @param data User defined data to pass to the PurpleCmdFunc 143 * command in sentence form. Do not include a slash before the
123 * @return A PurpleCmdId. This is only used for calling purple_cmd_unregister. 144 * command name.
124 * Returns 0 on failure. 145 * @param data User defined data to pass to the #PurpleCmdFunc @a f.
146 * @return A #PurpleCmdId, which is only used for calling
147 * #purple_cmd_unregister, or @a 0 on failure.
125 */ 148 */
126 PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f, 149 PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
127 const gchar *prpl_id, PurpleCmdFunc func, const gchar *helpstr, void *data); 150 const gchar *prpl_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
128 151
129 /** 152 /**
131 * 154 *
132 * All registered commands must be unregistered, if they're registered by a plugin 155 * All registered commands must be unregistered, if they're registered by a plugin
133 * or something else that might go away. Normally this is called when the plugin 156 * or something else that might go away. Normally this is called when the plugin
134 * unloads itself. 157 * unloads itself.
135 * 158 *
136 * @param id The PurpleCmdId to unregister. 159 * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
137 */ 160 */
138 void purple_cmd_unregister(PurpleCmdId id); 161 void purple_cmd_unregister(PurpleCmdId id);
139 162
140 /** 163 /**
141 * Do a command. 164 * Do a command.
151 * @param markup This is the same as cmd, but is the formatted version. It should be in 174 * @param markup This is the same as cmd, but is the formatted version. It should be in
152 * HTML, with < > and &, at least, escaped to html entities, and should 175 * HTML, with < > and &, at least, escaped to html entities, and should
153 * include both the default formatting and any extra manual formatting. 176 * include both the default formatting and any extra manual formatting.
154 * @param errormsg If the command failed errormsg is filled in with the appropriate error 177 * @param errormsg If the command failed errormsg is filled in with the appropriate error
155 * message. It must be freed by the caller with g_free(). 178 * message. It must be freed by the caller with g_free().
156 * @return A PurpleCmdStatus indicated if the command succeeded or failed. 179 * @return A #PurpleCmdStatus indicated if the command succeeded or failed.
157 */ 180 */
158 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline, 181 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
159 const gchar *markup, gchar **errormsg); 182 const gchar *markup, gchar **errormsg);
160 183
161 /** 184 /**
162 * List registered commands. 185 * List registered commands.
163 * 186 *
164 * Returns a GList (which must be freed by the caller) of all commands 187 * Returns a <tt>GList</tt> (which must be freed by the caller) of all commands
165 * that are valid in the context of conv, or all commands, if conv is 188 * that are valid in the context of @a conv, or all commands, if @a conv is @c
166 * @c NULL. Don't keep this list around past the main loop, or anything else 189 * NULL. Don't keep this list around past the main loop, or anything else that
167 * that might unregister a command, as the char*'s used get freed then. 190 * might unregister a command, as the <tt>const char *</tt>'s used get freed
191 * then.
168 * 192 *
169 * @param conv The conversation, or @c NULL. 193 * @param conv The conversation, or @c NULL.
170 * @return A GList of const char*, which must be freed with g_list_free(). 194 * @return A @c GList of <tt>const char *</tt>, which must be freed with
195 * <tt>g_list_free()</tt>.
171 */ 196 */
172 GList *purple_cmd_list(PurpleConversation *conv); 197 GList *purple_cmd_list(PurpleConversation *conv);
173 198
174 /** 199 /**
175 * Get the help string for a command. 200 * Get the help string for a command.
178 * one node for each matching command. 203 * one node for each matching command.
179 * 204 *
180 * @param conv The conversation, or @c NULL for no context. 205 * @param conv The conversation, or @c NULL for no context.
181 * @param cmd The command. No wildcards accepted, but returns help for all 206 * @param cmd The command. No wildcards accepted, but returns help for all
182 * commands if @c NULL. 207 * commands if @c NULL.
183 * @return A GList of const char*s, which is the help string 208 * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string
184 * for that command. 209 * for that command.
185 */ 210 */
186 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd); 211 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
187 212
188 /*@}*/ 213 /*@}*/