mirror of
https://github.com/profanity-im/profanity.git
synced 2025-01-03 14:57:42 -05:00
Update plugin API docs
This commit is contained in:
James Booth
parent
51a7588bc4
commit
9603e04e34
@ -6,7 +6,7 @@ C plugin API.
|
||||
List of all API function available to plugins: {@link profapi.h}
|
||||
|
||||
List of all hooks which plugins may implement: {@link profhooks.h}
|
||||
*/
|
||||
*/
|
||||
|
||||
/** Type representing a window, used for referencing windows created by the plugin */
|
||||
typedef char* PROF_WIN_TAG;
|
||||
@ -16,165 +16,271 @@ typedef char* PROF_WIN_TAG;
|
||||
*/
|
||||
typedef void(*CMD_CB)(char **args);
|
||||
|
||||
/** Type representing a function pointer to a timed callback
|
||||
*/
|
||||
/** Type representing a function pointer to a timed callback */
|
||||
typedef void(*TIMED_CB)(void);
|
||||
|
||||
/** Type representing a function pointer to a window callback
|
||||
*/
|
||||
/** Type representing a function pointer to a window callback */
|
||||
typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line);
|
||||
|
||||
|
||||
/** Highlights the console window in the status bar. */
|
||||
void prof_cons_alert(void);
|
||||
void prof_cons_alert)(void);
|
||||
|
||||
/**
|
||||
Show a message in the console.
|
||||
@param message the message to print
|
||||
Show a message in the console window.
|
||||
@param message the message to print
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_cons_show(const char * const message);
|
||||
int (*prof_cons_show)(const char * const message);
|
||||
|
||||
/**
|
||||
Show a message in the console, using the specified theme.
|
||||
Themes can be must be specified in ~/.local/share/profanity/plugin_themes
|
||||
@param group The group name in the themes file, or NULL
|
||||
@param item The item name within the group, or NULL
|
||||
@param def A default colour if the theme cannot be found, or NULL
|
||||
@param group the group name in the themes file
|
||||
@param item the item name within the group
|
||||
@param def default colour if the theme cannot be found
|
||||
@param message the message to print
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_cons_show_themed(const char *const group, const char *const item, const char *const def, const char *const message);
|
||||
int (*prof_cons_show_themed)(const char *const group, const char *const item, const char *const def, const char *const message);
|
||||
|
||||
/**
|
||||
Show a message in the console when invalid arguments have been passed to a command.
|
||||
@param cmd The name of the command, including the leading /
|
||||
Show a message indicating the command has been called incorrectly.
|
||||
@param cmd the command name with leading slash, e.g. "/say"
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_cons_bad_cmd_usage(const char *const cmd);
|
||||
int (*prof_cons_bad_cmd_usage)(const char *const cmd);
|
||||
|
||||
/**
|
||||
Register a plugin command.
|
||||
@param command_name The name of the command, including the leading /
|
||||
@param min_args Minimum arguments valid for the command
|
||||
@param max_args Maximum arguments valid for the command
|
||||
@param synopsis Overview of the command usage
|
||||
@param description A text description of the command
|
||||
@param arguments Description of all arguments
|
||||
@param examples Example command usages
|
||||
Register a new command, with help information, and callback for command execution.
|
||||
Profanity will do some basic validation when the command is called using the argument range.
|
||||
@param command_name the command name with leading slash, e.g. "/say"
|
||||
@param min_args minimum number or arguments that the command considers to be a valid call
|
||||
@param max_args maximum number or arguments that the command considers to be a valid call
|
||||
@param synopsis command usages
|
||||
@param description a short description of the command
|
||||
@param arguments argument descriptions
|
||||
@param examples example usages
|
||||
@param callback The {@link CMD_CB} function to execute when the command is invoked
|
||||
*/
|
||||
void prof_register_command(const char *command_name, int min_args, int max_args,
|
||||
const char **synopsis, const char *description, const char *arguments[][2], const char **examples,
|
||||
void (*_prof_register_command)(const char *filename, const char *command_name, int min_args, int max_args,
|
||||
char **synopsis, const char *description, char *arguments[][2], char **examples,
|
||||
CMD_CB callback);
|
||||
|
||||
/**
|
||||
Register a timed callback function
|
||||
Register a function that Profanity will call periodically.
|
||||
@param callback The {@link TIMED_CB} function to execute
|
||||
@param interval_seconds The interval for calling the function
|
||||
@param interval_seconds the time between each call to the function, in seconds
|
||||
*/
|
||||
void prof_register_timed(TIMED_CB callback, int interval_seconds);
|
||||
void (*_prof_register_timed)(const char *filename, TIMED_CB callback, int interval_seconds);
|
||||
|
||||
/**
|
||||
Register an autocompleter.
|
||||
Note that calling this function more than once will add the items to the autocompleter
|
||||
@param key The string used to initiate autocompletion
|
||||
@param items The to autocomplete with
|
||||
Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key.
|
||||
@param key the prefix to trigger autocompletion
|
||||
@param items the items to return on autocompletion
|
||||
*/
|
||||
void prof_register_ac(const char *key, char **items);
|
||||
void (*_prof_completer_add)(const char *filename, const char *key, char **items);
|
||||
|
||||
/**
|
||||
Remove values from autocompletion for a command, or command argument.
|
||||
|
||||
@param key the prefix from which to remove the autocompletion items
|
||||
@param items the items to remove
|
||||
*/
|
||||
void (*_prof_completer_remove)(const char *filename, const char *key, char **items);
|
||||
|
||||
/**
|
||||
Remove all values from autocompletion for a command, or command argument.
|
||||
|
||||
@param key the prefix from which to clear the autocompletion items
|
||||
@param items the items to remove
|
||||
*/
|
||||
void (*_prof_completer_clear)(const char *filename, const char *key);
|
||||
|
||||
/**
|
||||
Send a desktop notification.
|
||||
@param message The message to show in the notification
|
||||
@param timeout_ms Time in milliseconds until the notification disappears
|
||||
@param category Used as a notification category of the system supports it
|
||||
@param message the message to display in the notification
|
||||
@param timeout_ms the length of time before the notification disappears in milliseconds
|
||||
@param category the category of the notification, also displayed
|
||||
*/
|
||||
void prof_notify(const char *message, int timeout_ms, const char *category);
|
||||
void (*prof_notify)(const char *message, int timeout_ms, const char *category);
|
||||
|
||||
/**
|
||||
Send input to Profanity, equivalent to if the user had entered it.
|
||||
@param line The input to send.
|
||||
Send a line of input to Profanity to execute.
|
||||
@param line the line to send
|
||||
*/
|
||||
void prof_send_line(char *line);
|
||||
void (*prof_send_line)(char *line);
|
||||
|
||||
/**
|
||||
Get the current recipient if in a chat window.
|
||||
@return The JID of the recipient, or NULL if not in a chat window
|
||||
Retrieve the Jabber ID of the current chat recipient, when in a chat window.
|
||||
@return the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window.
|
||||
*/
|
||||
char* prof_get_current_recipient(void);
|
||||
char* (*prof_get_current_recipient)(void);
|
||||
|
||||
/**
|
||||
Get the current room if in a MUC window.
|
||||
@return The JID of the room, or NULL if not in a MUC window
|
||||
Retrieve the Jabber ID of the current room, when in a chat room window.
|
||||
@return the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window.
|
||||
*/
|
||||
char* prof_get_current_muc(void);
|
||||
char* (*prof_get_current_muc)(void);
|
||||
|
||||
/**
|
||||
Determines if the current window is the console.
|
||||
@return 1 if in the console, 0 otherwise
|
||||
Determine whether or not the Console window is currently focussed.
|
||||
@return 1 if the user is currently in the Console window, 0 otherwise.
|
||||
*/
|
||||
int prof_current_win_is_console(void);
|
||||
int (*prof_current_win_is_console)(void);
|
||||
|
||||
/**
|
||||
Log a DEBUG message to the profanity log
|
||||
Retrieve the users nickname in a chat room, when in a chat room window.
|
||||
@return the users nickname in the current chat room e.g. "eddie", or NULLL if not in a chat room window.
|
||||
*/
|
||||
char* (*prof_get_current_nick)(void);
|
||||
|
||||
/**
|
||||
Retrieve nicknames of all occupants in a chat room, when in a chat room window.
|
||||
@return nicknames of all occupants in the current room or an empty list if not in a chat room window.
|
||||
*/
|
||||
char** (*prof_get_current_occupants)(void);
|
||||
|
||||
/**
|
||||
Write to the Profanity log at level DEBUG.
|
||||
@param message The message to log
|
||||
*/
|
||||
void prof_log_debug(const char *message);
|
||||
void (*prof_log_debug)(const char *message);
|
||||
|
||||
/**
|
||||
Log a INFO message to the profanity log
|
||||
Write to the Profanity log at level INFO.
|
||||
@param message The message to log
|
||||
*/
|
||||
void prof_log_info(const char *message);
|
||||
void (*prof_log_info)(const char *message);
|
||||
|
||||
/**
|
||||
Log a WARNING message to the profanity log
|
||||
Write to the Profanity log at level WARNING.
|
||||
@param message The message to log
|
||||
*/
|
||||
void prof_log_warning(const char *message);
|
||||
void (*prof_log_warning)(const char *message);
|
||||
|
||||
/**
|
||||
Log a ERROR message to the profanity log
|
||||
Write to the Profanity log at level ERROR.
|
||||
@param message The message to log
|
||||
*/
|
||||
void prof_log_error(const char *message);
|
||||
void (*prof_log_error)(const char *message);
|
||||
|
||||
/**
|
||||
Determine if window exist with PROF_WIN_TAG
|
||||
@param win The {@link PROF_WIN_TAG} to check
|
||||
Create a plugin window.
|
||||
@param win The {@link PROF_WIN_TAG} used to refer to the window
|
||||
@param input_handler The WINDOW_CB function to call when the window receives input
|
||||
*/
|
||||
void (*_prof_win_create)(const char *filename, PROF_WIN_TAG win, WINDOW_CB input_handler);
|
||||
|
||||
/**
|
||||
Determine whether or not a plugin window currently exists for {@link PROF_WIN_TAG}.
|
||||
@param win the {@link PROF_WIN_TAG} used when creating the plugin window
|
||||
@return 1 if the window exists, 0 otherwise
|
||||
*/
|
||||
int prof_win_exists(PROF_WIN_TAG win);
|
||||
int (*prof_win_exists)(PROF_WIN_TAG win);
|
||||
|
||||
/**
|
||||
Create a new window
|
||||
@param win The {@link PROF_WIN_TAG} for the window
|
||||
@param input_handler The WINDOW_CB function to call when input is received for that window
|
||||
*/
|
||||
void prof_win_create(PROF_WIN_TAG win, WINDOW_CB input_handler);
|
||||
|
||||
/**
|
||||
Focus a window
|
||||
@param win The {@link PROF_WIN_TAG} of the window to focus
|
||||
Focus plugin window.
|
||||
@param win the {@link PROF_WIN_TAG} of the window to focus
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_win_focus(PROF_WIN_TAG win);
|
||||
int (*prof_win_focus)(PROF_WIN_TAG win);
|
||||
|
||||
/**
|
||||
Show a line in a window
|
||||
@param win The {@link PROF_WIN_TAG} of the window
|
||||
@param line The line to print
|
||||
Show a message in the plugin window.
|
||||
@param win the {@link PROF_WIN_TAG} of the window to display the message
|
||||
@param line The message to print
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_win_show(PROF_WIN_TAG win, char *line);
|
||||
int (*prof_win_show)(PROF_WIN_TAG win, char *line);
|
||||
|
||||
/**
|
||||
Show a message in a window, using the specified theme.
|
||||
Themes can be must be specified in ~/.local/share/profanity/plugin_themes
|
||||
@param win The {@link PROF_WIN_TAG} to print to
|
||||
@param group The group name in the themes file, or NULL
|
||||
@param item The item name within the group, or NULL
|
||||
@param def A default colour if the theme cannot be found, or NULL
|
||||
Show a message in the plugin window, using the specified theme.
|
||||
Themes must be specified in ~/.local/share/profanity/plugin_themes
|
||||
@param win The {@link PROF_WIN_TAG} of the window to display the message
|
||||
@param group the group name in the themes file
|
||||
@param key the item name within the group
|
||||
@param def default colour if the theme cannot be found or NULL
|
||||
@param message the message to print
|
||||
@return 1 on success, 0 on failure
|
||||
*/
|
||||
int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *line);
|
||||
int (*prof_win_show_themed)(PROF_WIN_TAG tag, char *group, char *key, char *def, char *line);
|
||||
|
||||
/**
|
||||
Send an XMPP stanza
|
||||
@param stanza an XMPP stanza
|
||||
@return 1 if the stanza was sent successfully, 0 otherwise
|
||||
*/
|
||||
int (*prof_send_stanza)(char *stanza);
|
||||
|
||||
/**
|
||||
Get a boolean setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param def default value if setting not found
|
||||
@return the setting, or default value
|
||||
*/
|
||||
int (*prof_settings_get_boolean)(char *group, char *key, int def);
|
||||
|
||||
/**
|
||||
Set a boolean setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param value value to set
|
||||
*/
|
||||
void (*prof_settings_set_boolean)(char *group, char *key, int value);
|
||||
|
||||
/**
|
||||
Get a string setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param def default value if setting not found
|
||||
@return the setting, or default value
|
||||
*/
|
||||
char* (*prof_settings_get_string)(char *group, char *key, char *def);
|
||||
|
||||
/**
|
||||
Set a string setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param value value to set
|
||||
*/
|
||||
void (*prof_settings_set_string)(char *group, char *key, char *value);
|
||||
|
||||
/**
|
||||
Get an integer setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param def default value if setting not found
|
||||
@return the setting, or default value
|
||||
*/
|
||||
int (*prof_settings_get_int)(char *group, char *key, int def);
|
||||
|
||||
/**
|
||||
Set an integer setting
|
||||
Settings must be specified in ~/.local/share/profanity/plugin_settings
|
||||
@param group the group name in the settings file
|
||||
@param key the item name within the group
|
||||
@param value value to set
|
||||
*/
|
||||
void (*prof_settings_set_int)(char *group, char *key, int value);
|
||||
|
||||
/**
|
||||
Trigger incoming message handling, this plugin will make profanity act as if the message has been received
|
||||
@param barejid Jabber ID of the sender of the message
|
||||
@param resource resource of the sender of the message
|
||||
@param message the message text
|
||||
*/
|
||||
void (*prof_incoming_message)(char *barejid, char *resource, char *message);
|
||||
|
||||
/**
|
||||
Add a service discovery feature the list supported by Profanity.
|
||||
If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity
|
||||
@param feature the service discovery feature to be added
|
||||
*/
|
||||
void (*prof_disco_add_feature)(char *feature);
|
||||
|
||||
@ -216,7 +216,7 @@ def notify(message, timeout, category):
|
||||
def get_current_recipient():
|
||||
"""Retrieve the Jabber ID of the current chat recipient, when in a chat window.
|
||||
|
||||
:return: The Jabber ID of the current chat recipient e.g. ``"buddy@chat.org"``, or ``None`` if not in a chat window.
|
||||
:return: the Jabber ID of the current chat recipient e.g. ``"buddy@chat.org"``, or ``None`` if not in a chat window.
|
||||
:rtype: str
|
||||
"""
|
||||
pass
|
||||
@ -225,7 +225,7 @@ def get_current_recipient():
|
||||
def get_current_muc():
|
||||
"""Retrieve the Jabber ID of the current room, when in a chat room window.
|
||||
|
||||
:return: The Jabber ID of the current chat room e.g. ``"metalchat@conference.chat.org"``, or ``None`` if not in a chat room window.
|
||||
:return: the Jabber ID of the current chat room e.g. ``"metalchat@conference.chat.org"``, or ``None`` if not in a chat room window.
|
||||
:rtype: str
|
||||
"""
|
||||
pass
|
||||
@ -234,7 +234,7 @@ def get_current_muc():
|
||||
def get_current_nick():
|
||||
"""Retrieve the users nickname in a chat room, when in a chat room window.
|
||||
|
||||
:return: The users nickname in the current chat room e.g. ``"eddie"``, or ``None`` if not in a chat room window.
|
||||
:return: the users nickname in the current chat room e.g. ``"eddie"``, or ``None`` if not in a chat room window.
|
||||
:rtype: str
|
||||
"""
|
||||
pass
|
||||
@ -243,7 +243,7 @@ def get_current_nick():
|
||||
def get_current_occupants():
|
||||
"""Retrieve nicknames of all occupants in a chat room, when in a chat room window.
|
||||
|
||||
:return: Nicknames of all occupants in the current room or an empty list if not in a chat room window.
|
||||
:return: nicknames of all occupants in the current room or an empty list if not in a chat room window.
|
||||
:rtype: list of str
|
||||
"""
|
||||
pass
|
||||
@ -340,7 +340,7 @@ def win_focus(tag):
|
||||
def win_show(tag, message):
|
||||
"""Show a message in the plugin window.
|
||||
|
||||
:param tag: The tag of the window to focus
|
||||
:param tag: The tag of the window to display the message
|
||||
:type tag: str or unicode
|
||||
:param message: the message to print
|
||||
:type message: str or unicode
|
||||
@ -354,9 +354,9 @@ def win_show(tag, message):
|
||||
|
||||
def win_show_themed(tag, group, key, default, message):
|
||||
"""Show a message in the plugin window, using the specified theme.\n
|
||||
Themes can be must be specified in ``~/.local/share/profanity/plugin_themes``
|
||||
Themes must be specified in ``~/.local/share/profanity/plugin_themes``
|
||||
|
||||
:param tag: The tag of the window to focus
|
||||
:param tag: The tag of the window to display the message
|
||||
:type tag: str or unicode
|
||||
:param group: the group name in the themes file
|
||||
:param key: the item name within the group
|
||||
|
||||
Loading…
Reference in New Issue
Block a user