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