libpurple/cmds.h

   1 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
   2  *
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  16  *
  17  */
  18
  19 #ifndef _PURPLE_CMDS_H_
  20 #define _PURPLE_CMDS_H_
  21 /**
  22  * SECTION:cmds
  23  * @section_id: libpurple-cmds
  24  * @short_description: <filename>cmds.h</filename>
  25  * @title: Commands API
  26  * @see_also: <link linkend="chapter-signals-cmd">Command signals</link>
  27  */
  28
  29 #include "conversation.h"
  30
  31 /**************************************************************************/
  32 /* Structures                                                             */
  33 /**************************************************************************/
  34
  35 /**
  36  * PurpleCmdStatus:
  37  *
  38  * The possible results of running a command with purple_cmd_do_command().
  39  */
  40 typedef enum {
  41         PURPLE_CMD_STATUS_OK,
  42         PURPLE_CMD_STATUS_FAILED,
  43         PURPLE_CMD_STATUS_NOT_FOUND,
  44         PURPLE_CMD_STATUS_WRONG_ARGS,
  45         PURPLE_CMD_STATUS_WRONG_PROTOCOL,
  46         PURPLE_CMD_STATUS_WRONG_TYPE
  47 } PurpleCmdStatus;
  48
  49 /**
  50  * PurpleCmdRet:
  51  * @PURPLE_CMD_RET_OK:       Everything's okay; Don't look for another command
  52  *                           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
  55  *                           name to call.
  56  *
  57  * Commands registered with the core return one of these values when run.
  58  * Normally, a command will want to return one of the first two; in some
  59  * unusual cases, you might want to have several functions called for a
  60  * particular command; in this case, they should return
  61  * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
  62  * commands with the same name.
  63  */
  64 typedef enum {
  65         PURPLE_CMD_RET_OK,
  66         PURPLE_CMD_RET_FAILED,
  67         PURPLE_CMD_RET_CONTINUE
  68 } PurpleCmdRet;
  69
  70 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
  71
  72 /**
  73  * PurpleCmdFunc:
  74  *
  75  * A function implementing a command, as passed to purple_cmd_register().
  76  */
  77 /* TODO document the arguments to these functions. */
  78 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
  79                                   gchar **args, gchar **error, void *data);
  80 /**
  81  * PurpleCmdId:
  82  *
  83  * A unique integer representing a command registered with
  84  * purple_cmd_register(), which can subsequently be passed to
  85  * purple_cmd_unregister() to unregister that command.
  86  */
  87 typedef guint PurpleCmdId;
  88
  89 typedef enum {
  90         PURPLE_CMD_P_VERY_LOW  = -1000,
  91         PURPLE_CMD_P_LOW       =     0,
  92         PURPLE_CMD_P_DEFAULT   =  1000,
  93         PURPLE_CMD_P_PROTOCOL  =  2000,
  94         PURPLE_CMD_P_PLUGIN    =  3000,
  95         PURPLE_CMD_P_ALIAS     =  4000,
  96         PURPLE_CMD_P_HIGH      =  5000,
  97         PURPLE_CMD_P_VERY_HIGH =  6000
  98 } PurpleCmdPriority;
  99
 100 /**
 101  * PurpleCmdFlag:
 102  * @PURPLE_CMD_FLAG_IM: Command is usable in IMs.
 103  * @PURPLE_CMD_FLAG_CHAT: Command is usable in multi-user chats.
 104  * @PURPLE_CMD_FLAG_PROTOCOL_ONLY: Command is usable only for a particular
 105  *                                 protocol.
 106  * @PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS: Incorrect arguments to this command
 107  *                                    should be accepted anyway.
 108  *
 109  * Flags used to set various properties of commands.  Every command should
 110  * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
 111  * order to be even slighly useful.
 112  *
 113  * See purple_cmd_register().
 114  */
 115 typedef enum {
 116         PURPLE_CMD_FLAG_IM               = 0x01,
 117         PURPLE_CMD_FLAG_CHAT             = 0x02,
 118         PURPLE_CMD_FLAG_PROTOCOL_ONLY    = 0x04,
 119         PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08
 120 } PurpleCmdFlag;
 121
 122 /**
 123  * Command UI operations;  UIs should implement this if they want to handle
 124  * commands themselves, rather than relying on the core.
 125  *
 126  * @see @ref ui-ops
 127  */
 128 typedef struct
 129 {
 130         /** If implemented, the UI is responsible for handling commands. */
 131         /* @see purple_cmd_register for the argument values. */
 132         void (*register_command)(const gchar *name, PurpleCmdPriority priority,
 133                                  PurpleCmdFlag flags, const gchar *prpl_id,
 134                                  const gchar *help, PurpleCmdId id);
 135
 136         /** Should be implemented if register_command is implemented.
 137          *  name and prpl_id will have the same value that were used
 138          *  for the register_command call.
 139          */
 140         void (*unregister_command)(const gchar *name, const gchar *prpl_id);
 141
 142         void (*_purple_reserved1)(void);
 143         void (*_purple_reserved2)(void);
 144         void (*_purple_reserved3)(void);
 145         void (*_purple_reserved4)(void);
 146 } PurpleCommandsUiOps;
 147
 148 G_BEGIN_DECLS
 149
 150 /**************************************************************************/
 151 /* Commands API                                                           */
 152 /**************************************************************************/
 153
 154 /**
 155  * purple_cmd_register:
 156  * @cmd: The command. This should be a UTF-8 (or ASCII) string, with no spaces
 157  *            or other white space.
 158  * @args: A string of characters describing to libpurple how to parse this
 159  *        command's arguments.  If what the user types doesn't match this
 160  *        pattern, libpurple will keep looking for another command, unless
 161  *        the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @f.
 162  *        This string should contain no whitespace, and use a single
 163  *        character for each argument.  The recognized characters are:
 164  *        <itemizedlist>
 165  *          <listitem><literal>'w'</literal>: Matches a single word.</listitem>
 166  *          <listitem><literal>'W'</literal>: Matches a single word, with
 167  *                                            formatting.</listitem>
 168  *          <listitem><literal>'s'</literal>: Matches the rest of the
 169  *                                            arguments after this point,
 170  *                                            as a single string.</listitem>
 171  *          <listitem><literal>'S'</literal>: Same as <literal>'s'</literal>
 172  *                                            but with formatting.</listitem>
 173  *        </itemizedlist>
 174  *        If args is the empty string, then the command accepts no
 175  *        arguments. The args passed to the callback @func will be a %NULL
 176  *        terminated array of %NULL terminated strings, and will always
 177  *        match the number of arguments asked for, unless
 178  *        #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
 179  * @p: This is the priority. Higher priority commands will be run first,
 180  *     and usually the first command will stop any others from being
 181  *     called.
 182  * @f: Flags specifying various options about this command, combined with
 183  *     <literal>|</literal> (bitwise OR). You need to at least pass one of
 184  *     #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
 185  *     order for the command to ever actually be called.
 186  * @protocol_id: If the #PURPLE_CMD_FLAG_PROTOCOL_ONLY flag is set, this is the id
 187  *                of the protocol to which the command applies (such as
 188  *                <literal>"prpl-msn"</literal>). If the flag is not set, this
 189  *                parameter is ignored; pass %NULL (or a humourous string of
 190  *                your choice!).
 191  * @func: (scope call): This is the function to call when someone enters this
 192  *                      command.
 193  * @helpstr: a whitespace sensitive, UTF-8, HTML string describing how to
 194  *           use the command.  The preferred format of this string is the
 195  *           command's name, followed by a space and any arguments it
 196  *           accepts (if it takes any arguments, otherwise no space),
 197  *           followed by a colon, two spaces, and a description of the
 198  *           command in sentence form.  Do not include a slash before the
 199  *           command name.
 200  * @data: User defined data to pass to the #PurpleCmdFunc @f.
 201  *
 202  * Register a new command with the core.
 203  *
 204  * The command will only happen if commands are enabled,
 205  * which is a UI pref. UIs don't have to support commands at all.
 206  *
 207  * Returns: A #PurpleCmdId, which is only used for calling
 208  *         #purple_cmd_unregister, or 0 on failure.
 209  */
 210 PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
 211                              const gchar *protocol_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
 212
 213 /**
 214  * purple_cmd_unregister:
 215  * @id: The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
 216  *
 217  * Unregister a command with the core.
 218  *
 219  * All registered commands must be unregistered, if they're registered by a plugin
 220  * or something else that might go away. Normally this is called when the plugin
 221  * unloads itself.
 222  */
 223 void purple_cmd_unregister(PurpleCmdId id);
 224
 225 /**
 226  * purple_cmd_do_command:
 227  * @conv: The conversation the command was typed in.
 228  * @cmdline: The command the user typed (including all arguments) as a single string.
 229  *            The caller doesn't have to do any parsing, except removing the command
 230  *            prefix, which the core has no knowledge of. cmd should not contain any
 231  *            formatting, and should be in plain text (no html entities).
 232  * @markup: This is the same as cmd, but is the formatted version. It should be in
 233  *               HTML, with < > and &, at least, escaped to html entities, and should
 234  *               include both the default formatting and any extra manual formatting.
 235  * @errormsg: If the command failed errormsg is filled in with the appropriate error
 236  *                 message. It must be freed by the caller with g_free().
 237  *
 238  * Do a command.
 239  *
 240  * Normally the UI calls this to perform a command. This might also be useful
 241  * if aliases are ever implemented.
 242  *
 243  * Returns: A #PurpleCmdStatus indicating if the command succeeded or failed.
 244  */
 245 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline,
 246                                   const gchar *markup, gchar **errormsg);
 247
 248 /**
 249  * Execute a specific command.
 250  *
 251  * The UI calls this to execute a command, after parsing the
 252  * command name.
 253  *
 254  * @param c The command to execute.
 255  * @param conv The conversation the command was typed in.
 256  * @param cmdline The command the user typed (only the arguments).
 257  *            The caller should remove the prefix and the command name.
 258  *            It should not contain any formatting, and should be
 259  *            in plain text (no HTML entities).
 260  * @return TRUE if the command handled the @a cmdline, FALSE otherwise.
 261  */
 262 gboolean purple_cmd_execute(PurpleCmdId id, PurpleConversation *conv,
 263                             const gchar *cmdline);
 264
 265 /**
 266  * purple_cmd_list:
 267  * @conv: The conversation, or %NULL.
 268  *
 269  * List registered commands.
 270  *
 271  * Returns a #GList (which must be freed by the caller) of all commands
 272  * that are valid in the context of @conv, or all commands, if @conv is
 273  * %NULL.  Don't keep this list around past the main loop, or anything else that
 274  * might unregister a command, as the <type>const char *</type>'s used get freed
 275  * then.
 276  *
 277  * Returns: A #GList of <type>const char *</type>, which must be freed with
 278  *          g_list_free().
 279  */
 280 GList *purple_cmd_list(PurpleConversation *conv);
 281
 282 /**
 283  * purple_cmd_help:
 284  * @conv: The conversation, or %NULL for no context.
 285  * @cmd: The command. No wildcards accepted, but returns help for all
 286  *            commands if %NULL.
 287  *
 288  * Get the help string for a command.
 289  *
 290  * Returns the help strings for a given command in the form of a GList,
 291  * one node for each matching command.
 292  *
 293  * Returns: A #GList of <type>const char *</type>s, which is the help string
 294  *         for that command.
 295  */
 296 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd);
 297
 298 /**
 299  * purple_cmds_get_handle:
 300  *
 301  * Get the handle for the commands API
 302  *
 303  * Returns: The handle
 304  */
 305 gpointer purple_cmds_get_handle(void);
 306
 307 /**
 308  * Sets the UI operations structure to be used when registering and
 309  * unregistering commands.  The UI operations need only be set if the
 310  * UI wants to handle the commands itself; otherwise, leave it as NULL.
 311  *
 312  * @param ops The UI operations structure.
 313  */
 314 void purple_cmds_set_ui_ops(PurpleCommandsUiOps *ops);
 315
 316 /**
 317  * Returns the UI operations structure to be used when registering and
 318  * unregistering commands.
 319  *
 320  * @return The UI operations structure.
 321  */
 322 PurpleCommandsUiOps *purple_cmds_get_ui_ops(void);
 323
 324 /**
 325  * purple_cmds_init:
 326  *
 327  * Initialize the commands subsystem.
 328  */
 329 void purple_cmds_init(void);
 330
 331 /**
 332  * purple_cmds_uninit:
 333  *
 334  * Uninitialize the commands subsystem.
 335  */
 336 void purple_cmds_uninit(void);
 337
 338 G_END_DECLS
 339
 340 #endif /* _PURPLE_CMDS_H_ */