Mercurial > pidgin
annotate libpurple/cmds.h @ 31537:6ec53e134447
bonjour: Recurse through user IP addresses instead of using the first one only
This, among other things, makes interactivity with iChat more reliable because
iChat apparently advertises an IPv6 address, but doesn't listen on it.
Fixes #13773
committer: Daniel Atallah <daniel.atallah@gmail.com>
author | Simon van der Linden <simon@vanderlinden.eu.org> |
---|---|
date | Tue, 03 May 2011 16:12:36 +0000 |
parents | d8452c0bec7b |
children | 5876584828e8 |
rev | line source |
---|---|
15373
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 |
23412
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
diff
changeset
|
4 * @see @ref cmd-signals |
20074
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19681
diff
changeset
|
5 */ |
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19681
diff
changeset
|
6 |
6bf32c9e15a7
remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents:
19681
diff
changeset
|
7 /* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com> |
15373
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 |
19681
44b4e8bd759b
The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
15822
diff
changeset
|
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA |
15373
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 */ |
15822 | 24 #ifndef _PURPLE_CMDS_H_ |
25 #define _PURPLE_CMDS_H_ | |
15373
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 |
23368
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23277
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 { |
15822 | 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, | |
24687
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23412
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; |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
43 |
23368
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23277
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:
23277
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:
23277
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:
23277
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:
23277
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:
23277
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:
23277
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 { |
23368
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23277
diff
changeset
|
52 PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */ |
15822 | 53 PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/ |
24687
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23412
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; |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
56 |
15822 | 57 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func) |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
58 |
23368
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23277
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:
23277
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:
23277
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:
23277
diff
changeset
|
62 * */ |
15822 | 63 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd, |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
64 gchar **args, gchar **error, void *data); |
23368
23498a6244f3
Document a few types in cmds, partly to make doxygen links to those types work.
Will Thompson <will.thompson@collabora.co.uk>
parents:
23277
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:
23277
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:
23277
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:
23277
diff
changeset
|
68 */ |
15822 | 69 typedef guint PurpleCmdId; |
15373
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 { |
15822 | 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, | |
24687
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23412
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; |
15373
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. */ |
15822 | 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. */ |
15822 | 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. */ |
15822 | 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. */ |
24687
d8452c0bec7b
Remove the commas at the end of enumerator lists. This resolves warnings
Florian Quèze <florian@instantbird.org>
parents:
23412
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; |
15373
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 |
15373
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> |
15373
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!). |
15373
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. |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
160 */ |
15822 | 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); | |
15373
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. |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
172 */ |
15822 | 173 void purple_cmd_unregister(PurpleCmdId id); |
15373
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(). |
23277
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. |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
192 */ |
15822 | 193 PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline, |
15373
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. |
15373
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>. |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
208 */ |
15822 | 209 GList *purple_cmd_list(PurpleConversation *conv); |
15373
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 |
15373
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 */ |
15822 | 223 GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd); |
15373
5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff
changeset
|
224 |
23412
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
diff
changeset
|
225 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
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:
23368
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:
23368
diff
changeset
|
229 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
diff
changeset
|
231 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
diff
changeset
|
232 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
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:
23368
diff
changeset
|
235 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
diff
changeset
|
237 |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
diff
changeset
|
238 /** |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
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:
23368
diff
changeset
|
241 */ |
b5f679e95666
cmd-added and cmd-removed signals to emit when commands are registered/unregistered.
Sadrul Habib Chowdhury <imadil@gmail.com>
parents:
23368
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:
23368
diff
changeset
|
243 |
15373
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 |
15822 | 250 #endif /* _PURPLE_CMDS_H_ */ |