Function

Purplecmd_register

since: 2.0

Declaration [src] 

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
)

Description [src]

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.

Available since: 2.0

Parameters

cmd

Type: const gchar*

The command. This should be a UTF-8 (or ASCII) string, with no spaces or other white space.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
args

Type: const gchar*

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: ‘w’: Matches a single word. ‘W’: Matches a single word, with formatting. ‘s’: Matches the rest of the arguments after this point, as a single string. ‘S’: Same as ‘s’ but with formatting. 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.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
p

Type: PurpleCmdPriority

This is the priority. Higher priority commands will be run first, and usually the first command will stop any others from being called.

f

Type: PurpleCmdFlag

Flags specifying various options about this command, combined with | (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

Type: const gchar*

If the #PURPLE_CMD_FLAG_PROTOCOL_ONLY flag is set, this is the id of the protocol to which the command applies (such as “prpl-msn”). If the flag is not set, this parameter is ignored; pass NULL (or a humourous string of your choice!).

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
func

Type: PurpleCmdFunc

This is the function to call when someone enters this command.

helpstr

Type: const gchar*

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.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
data

Type: void*

User defined data to pass to the PurpleCmdFunc f.

The argument can be NULL.
The data is owned by the caller of the function.

Return value

Type: PurpleCmdId

A PurpleCmdId, which is only used for calling #purple_cmd_unregister, or 0 on failure.