pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Convert optional dependencies into Meson features.
2019-10-08, Elliott Sales de Andrade
e9eaaff671c9
Convert optional dependencies into Meson features.
/* Copyright (C) 2003 Timothy Ringenbach <omarvo@hotmail.com>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*
*/
#ifndef PURPLE_CMDS_H
#define PURPLE_CMDS_H
/**
* SECTION:cmds
* @section_id: libpurple-cmds
* @short_description: <filename>cmds.h</filename>
* @title: Commands API
* @see_also: <link linkend="chapter-signals-cmd">Command signals</link>
*/
#include
"conversation.h"
/******************************************************************************
* Structures
*****************************************************************************/
/**
* PurpleCmdStatus:
* @PURPLE_CMD_STATUS_OK: The command executed successfully.
* @PURPLE_CMD_STATUS_FAILED: The command failed to execute.
* @PURPLE_CMD_STATUS_NOT_FOUND: The command was not found.
* @PURPLE_CMD_STATUS_WRONG_ARGS: The wrong number of arguments were passed.
* @PURPLE_CMD_STATUS_WRONG_PROTOCOL: The command was run with the wrong
* protocol.
* @PURPLE_CMD_STATUS_WRONG_TYPE: The Command was ran against the wrong type of
* conversation.
*
* The possible results of running a command with purple_cmd_do_command().
*/
typedef
enum
{
PURPLE_CMD_STATUS_OK
,
PURPLE_CMD_STATUS_FAILED
,
PURPLE_CMD_STATUS_NOT_FOUND
,
PURPLE_CMD_STATUS_WRONG_ARGS
,
PURPLE_CMD_STATUS_WRONG_PROTOCOL
,
PURPLE_CMD_STATUS_WRONG_TYPE
}
PurpleCmdStatus
;
/**
* PurpleCmdRet:
* @PURPLE_CMD_RET_OK: Everything's okay; Don't look for another command to
* call.
* @PURPLE_CMD_RET_FAILED: The command failed, but stop looking.
* @PURPLE_CMD_RET_CONTINUE: Continue, looking for other commands with the same
* name to call.
*
* Commands registered with the core return one of these values when run.
* Normally, a command will want to return one of the first two; in some
* unusual cases, you might want to have several functions called for a
* particular command; in this case, they should return
* #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
* commands with the same name.
*/
typedef
enum
{
PURPLE_CMD_RET_OK
,
PURPLE_CMD_RET_FAILED
,
PURPLE_CMD_RET_CONTINUE
}
PurpleCmdRet
;
#define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
/**
* PurpleCmdFunc:
* @conversation: The #PurpleConversation where the command is being run.
* @cmd: The name of the command.
* @args: The arguments to the command.
* @error: (out): A return address for a #GError.
* @data: User data to pass to the function.
*
* A function implementing a command, as passed to purple_cmd_register().
*/
typedef
PurpleCmdRet
(
*
PurpleCmdFunc
)(
PurpleConversation
*
conversation
,
const
gchar
*
cmd
,
gchar
**
args
,
gchar
**
error
,
void
*
data
);
/**
* PurpleCmdId:
*
* A unique integer representing a command registered with
* purple_cmd_register(), which can subsequently be passed to
* purple_cmd_unregister() to unregister that command.
*/
typedef
guint
PurpleCmdId
;
/**
* PurpleCmdPriority:
* @PURPLE_CMD_P_VERY_LOW: Lowest priority.
* @PURPLE_CMD_P_LOW: Low priority.
* @PURPLE_CMD_P_DEFAULT: Default priority.
* @PURPLE_CMD_P_PROTOCOL: Priority for protocol plugins.
* @PURPLE_CMD_P_PLUGIN: Priority for plugins.
* @PURPLE_CMD_P_ALIAS: Priority for aliasing commands.
* @PURPLE_CMD_P_HIGH: High priority.
* @PURPLE_CMD_P_VERY_HIGH: Highest priority.
*
* Commands are registered from multiple locations which leads to name
* collisions. PurpleCmdPriority is used to determine which command will be
* run.
*/
typedef
enum
{
PURPLE_CMD_P_VERY_LOW
=
-1000
,
PURPLE_CMD_P_LOW
=
0
,
PURPLE_CMD_P_DEFAULT
=
1000
,
PURPLE_CMD_P_PROTOCOL
=
2000
,
PURPLE_CMD_P_PLUGIN
=
3000
,
PURPLE_CMD_P_ALIAS
=
4000
,
PURPLE_CMD_P_HIGH
=
5000
,
PURPLE_CMD_P_VERY_HIGH
=
6000
}
PurpleCmdPriority
;
/**
* PurpleCmdFlag:
* @PURPLE_CMD_FLAG_IM: Command is usable in IMs.
* @PURPLE_CMD_FLAG_CHAT: Command is usable in multi-user chats.
* @PURPLE_CMD_FLAG_PROTOCOL_ONLY: Command is usable only for a particular
* protocol.
* @PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS: Incorrect arguments to this command
* should be accepted anyway.
*
* Flags used to set various properties of commands. Every command should
* have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
* order to be even slighly useful.
*
* See purple_cmd_register().
*/
typedef
enum
{
PURPLE_CMD_FLAG_IM
=
0x01
,
PURPLE_CMD_FLAG_CHAT
=
0x02
,
PURPLE_CMD_FLAG_PROTOCOL_ONLY
=
0x04
,
PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS
=
0x08
}
PurpleCmdFlag
;
/**
* PurpleCommandsUiOps:
* @register_command: If implemented, the UI is responsible for handling
* commands. See @purple_cmd_register for the argument values.
* @unregister_command: Should be implemented if register_command is
* implemented. @name and @prpl_id will have the same value
* that were used for the register_command call.
*
* Command UI operations; UIs should implement this if they want to handle
* commands themselves, rather than relying on the core.
*
* See <link linkend="chapter-ui-ops">List of <literal>UiOps</literal>
* Structures</link>
*/
typedef
struct
{
void
(
*
register_command
)(
const
gchar
*
name
,
PurpleCmdPriority
priority
,
PurpleCmdFlag
flags
,
const
gchar
*
prpl_id
,
const
gchar
*
help
,
PurpleCmdId
id
);
void
(
*
unregister_command
)(
const
gchar
*
name
,
const
gchar
*
prpl_id
);
/*< private >*/
void
(
*
_purple_reserved1
)(
void
);
void
(
*
_purple_reserved2
)(
void
);
void
(
*
_purple_reserved3
)(
void
);
void
(
*
_purple_reserved4
)(
void
);
}
PurpleCommandsUiOps
;
G_BEGIN_DECLS
/**************************************************************************/
/* Commands API */
/**************************************************************************/
/**
* purple_cmd_register:
* @cmd: The command. This should be a UTF-8 (or ASCII) string, with no spaces
* or other white space.
* @args: A string of characters describing to libpurple how to parse this
* command's arguments. If what the user types doesn't match this
* pattern, libpurple will keep looking for another command, unless
* the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @f.
* This string should contain no whitespace, and use a single
* character for each argument. The recognized characters are:
* <itemizedlist>
* <listitem><literal>'w'</literal>: Matches a single word.</listitem>
* <listitem><literal>'W'</literal>: Matches a single word, with
* formatting.</listitem>
* <listitem><literal>'s'</literal>: Matches the rest of the
* arguments after this point,
* as a single string.</listitem>
* <listitem><literal>'S'</literal>: Same as <literal>'s'</literal>
* but with formatting.</listitem>
* </itemizedlist>
* If args is the empty string, then the command accepts no
* arguments. The args passed to the callback @func will be a %NULL
* terminated array of %NULL terminated strings, and will always
* match the number of arguments asked for, unless
* #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
* @p: This is the priority. Higher priority commands will be run first,
* and usually the first command will stop any others from being
* called.
* @f: Flags specifying various options about this command, combined with
* <literal>|</literal> (bitwise OR). You need to at least pass one of
* #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
* order for the command to ever actually be called.
* @protocol_id: If the #PURPLE_CMD_FLAG_PROTOCOL_ONLY flag is set, this is the id
* of the protocol to which the command applies (such as
* <literal>"prpl-msn"</literal>). If the flag is not set, this
* parameter is ignored; pass %NULL (or a humourous string of
* your choice!).
* @func: (scope call): This is the function to call when someone enters this
* command.
* @helpstr: a whitespace sensitive, UTF-8, HTML string describing how to
* use the command. The preferred format of this string is the
* command's name, followed by a space and any arguments it
* accepts (if it takes any arguments, otherwise no space),
* followed by a colon, two spaces, and a description of the
* command in sentence form. Do not include a slash before the
* command name.
* @data: User defined data to pass to the #PurpleCmdFunc @f.
*
* Register a new command with the core.
*
* The command will only happen if commands are enabled,
* which is a UI pref. UIs don't have to support commands at all.
*
* Returns: A #PurpleCmdId, which is only used for calling
* #purple_cmd_unregister, or 0 on failure.
*/
PurpleCmdId
purple_cmd_register
(
const
gchar
*
cmd
,
const
gchar
*
args
,
PurpleCmdPriority
p
,
PurpleCmdFlag
f
,
const
gchar
*
protocol_id
,
PurpleCmdFunc
func
,
const
gchar
*
helpstr
,
void
*
data
);
/**
* purple_cmd_unregister:
* @id: The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
*
* Unregister a command with the core.
*
* All registered commands must be unregistered, if they're registered by a plugin
* or something else that might go away. Normally this is called when the plugin
* unloads itself.
*/
void
purple_cmd_unregister
(
PurpleCmdId
id
);
/**
* purple_cmd_do_command:
* @conv: The conversation the command was typed in.
* @cmdline: The command the user typed (including all arguments) as a single string.
* The caller doesn't have to do any parsing, except removing the command
* prefix, which the core has no knowledge of. cmd should not contain any
* formatting, and should be in plain text (no html entities).
* @markup: This is the same as cmd, but is the formatted version. It should be in
* HTML, with < > and &, at least, escaped to html entities, and should
* include both the default formatting and any extra manual formatting.
* @errormsg: If the command failed errormsg is filled in with the appropriate error
* message. It must be freed by the caller with g_free().
*
* Do a command.
*
* Normally the UI calls this to perform a command. This might also be useful
* if aliases are ever implemented.
*
* Returns: A #PurpleCmdStatus indicating if the command succeeded or failed.
*/
PurpleCmdStatus
purple_cmd_do_command
(
PurpleConversation
*
conv
,
const
gchar
*
cmdline
,
const
gchar
*
markup
,
gchar
**
errormsg
);
/**
* purple_cmd_execute:
* @id: The command to execute.
* @conv: The conversation the command was typed in.
* @cmdline: The command the user typed (only the arguments).
* The caller should remove the prefix and the command name.
* It should not contain any formatting, and should be
* in plain text (no HTML entities).
*
* Execute a specific command.
*
* The UI calls this to execute a command, after parsing the
* command name.
*
* Returns: %TRUE if the command handled the @cmdline, %FALSE otherwise.
*/
gboolean
purple_cmd_execute
(
PurpleCmdId
id
,
PurpleConversation
*
conv
,
const
gchar
*
cmdline
);
/**
* purple_cmd_list:
* @conv: The conversation, or %NULL.
*
* List registered commands.
*
* Returns: (element-type utf8) (transfer container): All commands
* that are valid in the context of @conv, or all commands, if @conv is
* %NULL. Don't keep this list around past the main loop, or anything else that
* might unregister a command, as the <type>const char *</type>'s used get freed
* then.
*/
GList
*
purple_cmd_list
(
PurpleConversation
*
conv
);
/**
* purple_cmd_help:
* @conv: The conversation, or %NULL for no context.
* @cmd: The command. No wildcards accepted, but returns help for all
* commands if %NULL.
*
* Get the help string for a command.
*
* Returns: (element-type utf8) (transfer container): the help strings for a
* given command, one node for each matching command.
*/
GList
*
purple_cmd_help
(
PurpleConversation
*
conv
,
const
gchar
*
cmd
);
/**
* purple_cmds_get_handle:
*
* Get the handle for the commands API
*
* Returns: The handle
*/
gpointer
purple_cmds_get_handle
(
void
);
/**
* purple_cmds_set_ui_ops:
* @ops: The UI operations structure.
*
* Sets the UI operations structure to be used when registering and
* unregistering commands. The UI operations need only be set if the
* UI wants to handle the commands itself; otherwise, leave it as NULL.
*/
void
purple_cmds_set_ui_ops
(
PurpleCommandsUiOps
*
ops
);
/**
* purple_cmds_get_ui_ops:
*
* Returns the UI operations structure to be used when registering and
* unregistering commands.
*
* Returns: (transfer none): The UI operations structure.
*/
PurpleCommandsUiOps
*
purple_cmds_get_ui_ops
(
void
);
/**
* purple_cmds_init:
*
* Initialize the commands subsystem.
*/
void
purple_cmds_init
(
void
);
/**
* purple_cmds_uninit:
*
* Uninitialize the commands subsystem.
*/
void
purple_cmds_uninit
(
void
);
G_END_DECLS
#endif
/* PURPLE_CMDS_H */