Mercurial > pidgin.yaz
annotate libpurple/cmds.h @ 28269:df920ad8cf4f
merge of '21745356545795bcec9c44cff0e779429c5092c6'
and '39fc4acd81cf1796220d3ed4fff0b17bc5acf6de'
author | Elliott Sales de Andrade <qulogic@pidgin.im> |
---|---|
date | Sun, 16 Aug 2009 03:27:56 +0000 |
parents | d8452c0bec7b |
children | 5876584828e8 |
rev | line source |
---|---|
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
1 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
2 * @file cmds.h Commands API |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
3 * @ingroup core |
23414
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
4 * @see @ref cmd-signals |
20074
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19680
diff
changeset
|
5 */ |
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19680
diff
changeset
|
6 |
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19680
diff
changeset
|
7 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com> |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
8 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
9 * This program is free software; you can redistribute it and/or modify |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
10 * it under the terms of the GNU General Public License as published by |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
11 * the Free Software Foundation; either version 2 of the License, or |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
12 * (at your option) any later version. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
13 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
14 * This program is distributed in the hope that it will be useful, |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
17 * GNU General Public License for more details. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
18 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
19 * You should have received a copy of the GNU General Public License |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
20 * along with this program; if not, write to the Free Software |
19680
44b4e8bd759b
The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
15823
diff
changeset
|
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
22 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
23 */ |
15823 | 24 #ifndef _PURPLE_CMDS_H_ |
25 #define _PURPLE_CMDS_H_ | |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
26 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
27 #include "conversation.h" |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
28 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
29 /**************************************************************************/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
30 /** @name Structures */ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
31 /**************************************************************************/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
32 /*@{*/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
33 |
23370
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
34 /** The possible results of running a command with purple_cmd_do_command(). */ |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
35 typedef enum _PurpleCmdStatus { |
15823 | 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, | |
24635
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23414
diff
changeset
|
41 PURPLE_CMD_STATUS_WRONG_TYPE |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
42 } PurpleCmdStatus; |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
43 |
23370
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
44 /** Commands registered with the core return one of these values when run. |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
45 * Normally, a command will want to return one of the first two; in some |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
46 * unusual cases, you might want to have several functions called for a |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
47 * particular command; in this case, they should return |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
48 * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
49 * commands with the same name. |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
50 */ |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
51 typedef enum _PurpleCmdRet { |
23370
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
52 PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */ |
15823 | 53 PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/ |
24635
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23414
diff
changeset
|
54 PURPLE_CMD_RET_CONTINUE /**< Continue, looking for other commands with the same name to call. */ |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
55 } PurpleCmdRet; |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
56 |
15823 | 57 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func) |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
58 |
23370
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
59 /** A function implementing a command, as passed to purple_cmd_register(). |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
60 * |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
61 * @todo document the arguments to these functions. |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
62 * */ |
15823 | 63 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd, |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
64 gchar **args, gchar **error, void *data); |
23370
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
65 /** A unique integer representing a command registered with |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
66 * purple_cmd_register(), which can subsequently be passed to |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
67 * purple_cmd_unregister() to unregister that command. |
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23279
diff
changeset
|
68 */ |
15823 | 69 typedef guint PurpleCmdId; |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
70 |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
71 typedef enum _PurpleCmdPriority { |
15823 | 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, | |
24635
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23414
diff
changeset
|
79 PURPLE_CMD_P_VERY_HIGH = 6000 |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
80 } PurpleCmdPriority; |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
81 |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
82 /** Flags used to set various properties of commands. Every command should |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
83 * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
84 * order to be even slighly useful. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
85 * |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
86 * @see purple_cmd_register |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
87 */ |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
88 typedef enum _PurpleCmdFlag { |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
89 /** Command is usable in IMs. */ |
15823 | 90 PURPLE_CMD_FLAG_IM = 0x01, |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
91 /** Command is usable in multi-user chats. */ |
15823 | 92 PURPLE_CMD_FLAG_CHAT = 0x02, |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
93 /** Command is usable only for a particular prpl. */ |
15823 | 94 PURPLE_CMD_FLAG_PRPL_ONLY = 0x04, |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
95 /** Incorrect arguments to this command should be accepted anyway. */ |
24635
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23414
diff
changeset
|
96 PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08 |
21930
7d0ef1e3ac4f
C++ doesn't really allow forward declarations of enums, and we
Mark Doliner <mark@kingant.net>
parents:
20133
diff
changeset
|
97 } PurpleCmdFlag; |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
98 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
99 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
100 /*@}*/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
101 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
102 #ifdef __cplusplus |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
103 extern "C" { |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
104 #endif |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
105 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
106 /**************************************************************************/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
107 /** @name Commands API */ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
108 /**************************************************************************/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
109 /*@{*/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
110 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
111 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
112 * Register a new command with the core. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
113 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
114 * The command will only happen if commands are enabled, |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
115 * which is a UI pref. UIs don't have to support commands at all. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
116 * |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
117 * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
118 * or other white space. |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
119 * @param args A string of characters describing to libpurple how to parse this |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
120 * command's arguments. If what the user types doesn't match this |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
121 * pattern, libpurple will keep looking for another command, unless |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
122 * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
123 * This string should contain no whitespace, and use a single |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
124 * character for each argument. The recognized characters are: |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
125 * <ul> |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
126 * <li><tt>'w'</tt>: Matches a single word.</li> |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
127 * <li><tt>'W'</tt>: Matches a single word, with formatting.</li> |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
128 * <li><tt>'s'</tt>: Matches the rest of the arguments after this |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
129 * point, as a single string.</li> |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
130 * <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li> |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
131 * </ul> |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
132 * If args is the empty string, then the command accepts no arguments. |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
133 * The args passed to the callback @a func will be a @c NULL |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
134 * terminated array of @c NULL terminated strings, and will always |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
135 * match the number of arguments asked for, unless |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
136 * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
137 * @param p This is the priority. Higher priority commands will be run first, |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
138 * and usually the first command will stop any others from being |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
139 * called. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
140 * @param f Flags specifying various options about this command, combined with |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
141 * <tt>|</tt> (bitwise OR). You need to at least pass one of |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
142 * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
143 * order for the command to ever actually be called. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
144 * @param prpl_id If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
145 * of the prpl to which the command applies (such as |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
146 * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
147 * is ignored; pass @c NULL (or a humourous string of your |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
148 * choice!). |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
149 * @param func This is the function to call when someone enters this command. |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
150 * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
151 * use the command. The preferred format of this string is the |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
152 * command's name, followed by a space and any arguments it |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
153 * accepts (if it takes any arguments, otherwise no space), |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
154 * followed by a colon, two spaces, and a description of the |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
155 * command in sentence form. Do not include a slash before the |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
156 * command name. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
157 * @param data User defined data to pass to the #PurpleCmdFunc @a f. |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
158 * @return A #PurpleCmdId, which is only used for calling |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
159 * #purple_cmd_unregister, or @a 0 on failure. |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
160 */ |
15823 | 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); | |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
163 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
164 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
165 * Unregister a command with the core. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
166 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
167 * All registered commands must be unregistered, if they're registered by a plugin |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
168 * or something else that might go away. Normally this is called when the plugin |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
169 * unloads itself. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
170 * |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
171 * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register. |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
172 */ |
15823 | 173 void purple_cmd_unregister(PurpleCmdId id); |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
174 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
175 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
176 * Do a command. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
177 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
178 * Normally the UI calls this to perform a command. This might also be useful |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
179 * if aliases are ever implemented. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
180 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
181 * @param conv The conversation the command was typed in. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
182 * @param cmdline The command the user typed (including all arguments) as a single string. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
183 * The caller doesn't have to do any parsing, except removing the command |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
184 * prefix, which the core has no knowledge of. cmd should not contain any |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
185 * formatting, and should be in plain text (no html entities). |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
186 * @param markup This is the same as cmd, but is the formatted version. It should be in |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
187 * HTML, with < > and &, at least, escaped to html entities, and should |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
188 * include both the default formatting and any extra manual formatting. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
189 * @param errormsg If the command failed errormsg is filled in with the appropriate error |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
190 * message. It must be freed by the caller with g_free(). |
23279
14b9a5231f63
A few character comment change.
Mark Doliner <mark@kingant.net>
parents:
21930
diff
changeset
|
191 * @return A #PurpleCmdStatus indicating if the command succeeded or failed. |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
192 */ |
15823 | 193 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline, |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
194 const gchar *markup, gchar **errormsg); |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
195 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
196 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
197 * List registered commands. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
198 * |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
199 * Returns a <tt>GList</tt> (which must be freed by the caller) of all commands |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
200 * that are valid in the context of @a conv, or all commands, if @a conv is @c |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
201 * NULL. Don't keep this list around past the main loop, or anything else that |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
202 * might unregister a command, as the <tt>const char *</tt>'s used get freed |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
203 * then. |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
204 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
205 * @param conv The conversation, or @c NULL. |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
206 * @return A @c GList of <tt>const char *</tt>, which must be freed with |
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
207 * <tt>g_list_free()</tt>. |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
208 */ |
15823 | 209 GList *purple_cmd_list(PurpleConversation *conv); |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
210 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
211 /** |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
212 * Get the help string for a command. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
213 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
214 * Returns the help strings for a given command in the form of a GList, |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
215 * one node for each matching command. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
216 * |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
217 * @param conv The conversation, or @c NULL for no context. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
218 * @param cmd The command. No wildcards accepted, but returns help for all |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
219 * commands if @c NULL. |
20133
baf144ea4f9b
Let's document more of cmds.h!
Will Thompson <will.thompson@collabora.co.uk>
parents:
20074
diff
changeset
|
220 * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
221 * for that command. |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
222 */ |
15823 | 223 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd); |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
224 |
23414
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
225 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
226 * Get the handle for the commands API |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
227 * @return The handle |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
228 * @since 2.5.0 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
229 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
230 gpointer purple_cmds_get_handle(void); |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
231 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
232 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
233 * Initialize the commands subsystem. |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
234 * @since 2.5.0 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
235 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
236 void purple_cmds_init(void); |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
237 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
238 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
239 * Uninitialize the commands subsystem. |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
240 * @since 2.5.0 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
241 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
242 void purple_cmds_uninit(void); |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23370
diff
changeset
|
243 |
15374
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
244 /*@}*/ |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
245 |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
246 #ifdef __cplusplus |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
247 } |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
248 #endif |
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
249 |
15823 | 250 #endif /* _PURPLE_CMDS_H_ */ |