1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/cmds.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,250 @@
1.4 +/**
1.5 + * @file cmds.h Commands API
1.6 + * @ingroup core
1.7 + * @see @ref cmd-signals
1.8 + */
1.9 +
1.10 +/* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify
1.13 + * it under the terms of the GNU General Public License as published by
1.14 + * the Free Software Foundation; either version 2 of the License, or
1.15 + * (at your option) any later version.
1.16 + *
1.17 + * This program is distributed in the hope that it will be useful,
1.18 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.19 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.20 + * GNU General Public License for more details.
1.21 + *
1.22 + * You should have received a copy of the GNU General Public License
1.23 + * along with this program; if not, write to the Free Software
1.24 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.25 + *
1.26 + */
1.27 +#ifndef _PURPLE_CMDS_H_
1.28 +#define _PURPLE_CMDS_H_
1.29 +
1.30 +#include "conversation.h"
1.31 +
1.32 +/**************************************************************************/
1.33 +/** @name Structures */
1.34 +/**************************************************************************/
1.35 +/*@{*/
1.36 +
1.37 +/** The possible results of running a command with purple_cmd_do_command(). */
1.38 +typedef enum _PurpleCmdStatus {
1.39 + PURPLE_CMD_STATUS_OK,
1.40 + PURPLE_CMD_STATUS_FAILED,
1.41 + PURPLE_CMD_STATUS_NOT_FOUND,
1.42 + PURPLE_CMD_STATUS_WRONG_ARGS,
1.43 + PURPLE_CMD_STATUS_WRONG_PRPL,
1.44 + PURPLE_CMD_STATUS_WRONG_TYPE
1.45 +} PurpleCmdStatus;
1.46 +
1.47 +/** Commands registered with the core return one of these values when run.
1.48 + * Normally, a command will want to return one of the first two; in some
1.49 + * unusual cases, you might want to have several functions called for a
1.50 + * particular command; in this case, they should return
1.51 + * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
1.52 + * commands with the same name.
1.53 + */
1.54 +typedef enum _PurpleCmdRet {
1.55 + PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */
1.56 + PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/
1.57 + PURPLE_CMD_RET_CONTINUE /**< Continue, looking for other commands with the same name to call. */
1.58 +} PurpleCmdRet;
1.59 +
1.60 +#define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
1.61 +
1.62 +/** A function implementing a command, as passed to purple_cmd_register().
1.63 + *
1.64 + * @todo document the arguments to these functions.
1.65 + * */
1.66 +typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
1.67 + gchar **args, gchar **error, void *data);
1.68 +/** A unique integer representing a command registered with
1.69 + * purple_cmd_register(), which can subsequently be passed to
1.70 + * purple_cmd_unregister() to unregister that command.
1.71 + */
1.72 +typedef guint PurpleCmdId;
1.73 +
1.74 +typedef enum _PurpleCmdPriority {
1.75 + PURPLE_CMD_P_VERY_LOW = -1000,
1.76 + PURPLE_CMD_P_LOW = 0,
1.77 + PURPLE_CMD_P_DEFAULT = 1000,
1.78 + PURPLE_CMD_P_PRPL = 2000,
1.79 + PURPLE_CMD_P_PLUGIN = 3000,
1.80 + PURPLE_CMD_P_ALIAS = 4000,
1.81 + PURPLE_CMD_P_HIGH = 5000,
1.82 + PURPLE_CMD_P_VERY_HIGH = 6000
1.83 +} PurpleCmdPriority;
1.84 +
1.85 +/** Flags used to set various properties of commands. Every command should
1.86 + * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
1.87 + * order to be even slighly useful.
1.88 + *
1.89 + * @see purple_cmd_register
1.90 + */
1.91 +typedef enum _PurpleCmdFlag {
1.92 + /** Command is usable in IMs. */
1.93 + PURPLE_CMD_FLAG_IM = 0x01,
1.94 + /** Command is usable in multi-user chats. */
1.95 + PURPLE_CMD_FLAG_CHAT = 0x02,
1.96 + /** Command is usable only for a particular prpl. */
1.97 + PURPLE_CMD_FLAG_PRPL_ONLY = 0x04,
1.98 + /** Incorrect arguments to this command should be accepted anyway. */
1.99 + PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08
1.100 +} PurpleCmdFlag;
1.101 +
1.102 +
1.103 +/*@}*/
1.104 +
1.105 +#ifdef __cplusplus
1.106 +extern "C" {
1.107 +#endif
1.108 +
1.109 +/**************************************************************************/
1.110 +/** @name Commands API */
1.111 +/**************************************************************************/
1.112 +/*@{*/
1.113 +
1.114 +/**
1.115 + * Register a new command with the core.
1.116 + *
1.117 + * The command will only happen if commands are enabled,
1.118 + * which is a UI pref. UIs don't have to support commands at all.
1.119 + *
1.120 + * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces
1.121 + * or other white space.
1.122 + * @param args A string of characters describing to libpurple how to parse this
1.123 + * command's arguments. If what the user types doesn't match this
1.124 + * pattern, libpurple will keep looking for another command, unless
1.125 + * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f.
1.126 + * This string should contain no whitespace, and use a single
1.127 + * character for each argument. The recognized characters are:
1.128 + * <ul>
1.129 + * <li><tt>'w'</tt>: Matches a single word.</li>
1.130 + * <li><tt>'W'</tt>: Matches a single word, with formatting.</li>
1.131 + * <li><tt>'s'</tt>: Matches the rest of the arguments after this
1.132 + * point, as a single string.</li>
1.133 + * <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li>
1.134 + * </ul>
1.135 + * If args is the empty string, then the command accepts no arguments.
1.136 + * The args passed to the callback @a func will be a @c NULL
1.137 + * terminated array of @c NULL terminated strings, and will always
1.138 + * match the number of arguments asked for, unless
1.139 + * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
1.140 + * @param p This is the priority. Higher priority commands will be run first,
1.141 + * and usually the first command will stop any others from being
1.142 + * called.
1.143 + * @param f Flags specifying various options about this command, combined with
1.144 + * <tt>|</tt> (bitwise OR). You need to at least pass one of
1.145 + * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
1.146 + * order for the command to ever actually be called.
1.147 + * @param prpl_id If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id
1.148 + * of the prpl to which the command applies (such as
1.149 + * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter
1.150 + * is ignored; pass @c NULL (or a humourous string of your
1.151 + * choice!).
1.152 + * @param func This is the function to call when someone enters this command.
1.153 + * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to
1.154 + * use the command. The preferred format of this string is the
1.155 + * command's name, followed by a space and any arguments it
1.156 + * accepts (if it takes any arguments, otherwise no space),
1.157 + * followed by a colon, two spaces, and a description of the
1.158 + * command in sentence form. Do not include a slash before the
1.159 + * command name.
1.160 + * @param data User defined data to pass to the #PurpleCmdFunc @a f.
1.161 + * @return A #PurpleCmdId, which is only used for calling
1.162 + * #purple_cmd_unregister, or @a 0 on failure.
1.163 + */
1.164 +PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
1.165 + const gchar *prpl_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
1.166 +
1.167 +/**
1.168 + * Unregister a command with the core.
1.169 + *
1.170 + * All registered commands must be unregistered, if they're registered by a plugin
1.171 + * or something else that might go away. Normally this is called when the plugin
1.172 + * unloads itself.
1.173 + *
1.174 + * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
1.175 + */
1.176 +void purple_cmd_unregister(PurpleCmdId id);
1.177 +
1.178 +/**
1.179 + * Do a command.
1.180 + *
1.181 + * Normally the UI calls this to perform a command. This might also be useful
1.182 + * if aliases are ever implemented.
1.183 + *
1.184 + * @param conv The conversation the command was typed in.
1.185 + * @param cmdline The command the user typed (including all arguments) as a single string.
1.186 + * The caller doesn't have to do any parsing, except removing the command
1.187 + * prefix, which the core has no knowledge of. cmd should not contain any
1.188 + * formatting, and should be in plain text (no html entities).
1.189 + * @param markup This is the same as cmd, but is the formatted version. It should be in
1.190 + * HTML, with < > and &, at least, escaped to html entities, and should
1.191 + * include both the default formatting and any extra manual formatting.
1.192 + * @param errormsg If the command failed errormsg is filled in with the appropriate error
1.193 + * message. It must be freed by the caller with g_free().
1.194 + * @return A #PurpleCmdStatus indicating if the command succeeded or failed.
1.195 + */
1.196 +PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
1.197 + const gchar *markup, gchar **errormsg);
1.198 +
1.199 +/**
1.200 + * List registered commands.
1.201 + *
1.202 + * Returns a <tt>GList</tt> (which must be freed by the caller) of all commands
1.203 + * that are valid in the context of @a conv, or all commands, if @a conv is @c
1.204 + * NULL. Don't keep this list around past the main loop, or anything else that
1.205 + * might unregister a command, as the <tt>const char *</tt>'s used get freed
1.206 + * then.
1.207 + *
1.208 + * @param conv The conversation, or @c NULL.
1.209 + * @return A @c GList of <tt>const char *</tt>, which must be freed with
1.210 + * <tt>g_list_free()</tt>.
1.211 + */
1.212 +GList *purple_cmd_list(PurpleConversation *conv);
1.213 +
1.214 +/**
1.215 + * Get the help string for a command.
1.216 + *
1.217 + * Returns the help strings for a given command in the form of a GList,
1.218 + * one node for each matching command.
1.219 + *
1.220 + * @param conv The conversation, or @c NULL for no context.
1.221 + * @param cmd The command. No wildcards accepted, but returns help for all
1.222 + * commands if @c NULL.
1.223 + * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string
1.224 + * for that command.
1.225 + */
1.226 +GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
1.227 +
1.228 +/**
1.229 + * Get the handle for the commands API
1.230 + * @return The handle
1.231 + * @since 2.5.0
1.232 + */
1.233 +gpointer purple_cmds_get_handle(void);
1.234 +
1.235 +/**
1.236 + * Initialize the commands subsystem.
1.237 + * @since 2.5.0
1.238 + */
1.239 +void purple_cmds_init(void);
1.240 +
1.241 +/**
1.242 + * Uninitialize the commands subsystem.
1.243 + * @since 2.5.0
1.244 + */
1.245 +void purple_cmds_uninit(void);
1.246 +
1.247 +/*@}*/
1.248 +
1.249 +#ifdef __cplusplus
1.250 +}
1.251 +#endif
1.252 +
1.253 +#endif /* _PURPLE_CMDS_H_ */