libpurple/cmds.h

   1 /**
   2  * @file cmds.h Commands API
   3  * @ingroup core
   4  * @see @ref cmd-signals
   5  */
   6
   7 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
   8  *
   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.
  13  *
  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.
  18  *
  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
  22  *
  23  */
  24 #ifndef _PURPLE_CMDS_H_
  25 #define _PURPLE_CMDS_H_
  26
  27 #include "conversation.h"
  28
  29 /**************************************************************************/
  30 /** @name Structures                                                      */
  31 /**************************************************************************/
  32 /*@{*/
  33
  34 /** The possible results of running a command with purple_cmd_do_command(). */
  35 typedef enum _PurpleCmdStatus {
  36         PURPLE_CMD_STATUS_OK,
  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
  42 } PurpleCmdStatus;
  43
  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.
  50  */
  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. */
  55 } PurpleCmdRet;
  56
  57 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
  58
  59 /** A function implementing a command, as passed to purple_cmd_register().
  60  *
  61  *  @todo document the arguments to these functions.
  62  * */
  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.
  68  */
  69 typedef guint PurpleCmdId;
  70
  71 typedef enum _PurpleCmdPriority {
  72         PURPLE_CMD_P_VERY_LOW  = -1000,
  73         PURPLE_CMD_P_LOW       =     0,
  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
  80 } PurpleCmdPriority;
  81
  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.
  85  *
  86  *  @see purple_cmd_register
  87  */
  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
  97 } PurpleCmdFlag;
  98
  99
 100 /*@}*/
 101
 102 #ifdef __cplusplus
 103 extern "C" {
 104 #endif
 105
 106 /**************************************************************************/
 107 /** @name Commands API                                                    */
 108 /**************************************************************************/
 109 /*@{*/
 110
 111 /**
 112  * Register a new command with the core.
 113  *
 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.
 116  *
 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:
 125  *             <ul>
 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>
 131  *             </ul>
 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
 139  *          called.
 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
 148  *                choice!).
 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
 156  *                command name.
 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.
 160  */
 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);
 163
 164 /**
 165  * Unregister a command with the core.
 166  *
 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
 169  * unloads itself.
 170  *
 171  * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
 172  */
 173 void purple_cmd_unregister(PurpleCmdId id);
 174
 175 /**
 176  * Do a command.
 177  *
 178  * Normally the UI calls this to perform a command. This might also be useful
 179  * if aliases are ever implemented.
 180  *
 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.
 192  */
 193 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
 194                                   const gchar *markup, gchar **errormsg);
 195
 196 /**
 197  * List registered commands.
 198  *
 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
 203  * then.
 204  *
 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>.
 208  */
 209 GList *purple_cmd_list(PurpleConversation *conv);
 210
 211 /**
 212  * Get the help string for a command.
 213  *
 214  * Returns the help strings for a given command in the form of a GList,
 215  * one node for each matching command.
 216  *
 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
 221  *         for that command.
 222  */
 223 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
 224
 225 /**
 226  * Get the handle for the commands API
 227  * @return The handle
 228  * @since 2.5.0
 229  */
 230 gpointer purple_cmds_get_handle(void);
 231
 232 /**
 233  * Initialize the commands subsystem.
 234  * @since 2.5.0
 235  */
 236 void purple_cmds_init(void);
 237
 238 /**
 239  * Uninitialize the commands subsystem.
 240  * @since 2.5.0
 241  */
 242 void purple_cmds_uninit(void);
 243
 244 /*@}*/
 245
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249
 250 #endif /* _PURPLE_CMDS_H_ */