Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/cmds.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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_ */