aniani/profanity
1
1
Fork 0
mirror of https://github.com/profanity-im/profanity.git synced 2025-01-03 14:57:42 -05:00
Code

Merge branch 'master' into osx-functional

Browse Source
This commit is contained in:
James Booth 2016-07-30 23:01:05 +01:00
commit 1f726b53ba
4 changed files with 325 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
apidocs/c/profapi.h
View File

@ -6,30 +6,26 @@ 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;
/** Type representing a function pointer to a command callback
@param args The arguments passed to the callback
*/
/** Type representing a function pointer to a command callback */
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);
/**
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);
@ -37,144 +33,251 @@ 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);
/**
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);
/**
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,
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);
/**
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 *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 *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 *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);
/**
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);
/**
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);
/**
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);
/**
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);
/**
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);
/**
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);
/**
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);
/**
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);
/**
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(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);
/**
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);
/**
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);
/**
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);
/**
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);

208
apidocs/c/profhooks.h
View File

@ -3,128 +3,216 @@ C Hooks.
*/
/**
Called when profanity loads the plugin
@param version The version of profanity as a string e.g. "0.5.0"
@param status The build status, either "development" or "release"
Called when a plugin is loaded, either when profanity is started, or when the /plugins load or /plugins install commands are called
@param version the version of Profanity
@param status the package status of Profanity, "development" or "release"
@param account_name account name of the currently logged in account, or NULL if not logged in
@param fulljid the users full Jabber ID (barejid and resource) if logged in, NULL otherwise
*/
void prof_init(const char * const version, const char * const status);
void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid);
/**
Called when profanity starts, after {@link prof_init}
Called when Profanity is started
*/
void prof_on_start(void);
/**
Called when profanity shuts down
Called when the user quits Profanity
*/
void prof_on_shutdown(void);
/**
Called when an account is connected
@param account_name The name of the account
@param fulljid The full JID of the account
Called when a plugin is unloaded with the /plugins unload command
*/
void prof_on_unload(void);
/**
Called when the user connects with an account
@param account_name account name of the account used for logging in
@param fulljid the full Jabber ID (barejid and resource) of the account
*/
void prof_on_connect(const char * const account_name, const char * const fulljid);
/**
Called when an account is disconnected
@param account_name The name of the account
@param fulljid The full JID of the account
Called when the user disconnects an account
@param account_name account name of the account being disconnected
@param fulljid the full Jabber ID (barejid and resource) of the account
*/
void prof_on_disconnect(const char * const account_name, const char * const fulljid);
/**
Called before a regular chat message is displayed
@param jid The JID of the sender
@param message The message received
@return The new message, or NULL if no change made to the message
Called before a chat message is displayed
@param barejid Jabber ID of the message sender
@param message the received message
@return the new message to display, or NULL to preserve the original message
*/
char* prof_pre_chat_message_display(const char * const jid, const char *message);
/**
Called after a regular chat message is displayed
@param jid The JID of the sender
@param message The message received
Called after a chat message is displayed
@param barejid Jabber ID of the message sender
@param message the received message
*/
void prof_post_chat_message_display(const char * const jid, const char *message);
/**
Called before a regular chat message is sent
@param jid The JID of the recipient
@param message The message to send
@return The new message, or NULL if no change made to the message
Called before a chat message is sent
@param barejid Jabber ID of the message recipient
@param message the message to be sent
@return the new message to send, or NULL to preserve the original message
*/
char* prof_pre_chat_message_send(const char * const jid, const char *message);
/**
Called after a regular chat message is sent
@param jid The JID of the recipient
@param message The message sent
Called after a chat message has been sent
@param barejid Jabber ID of the message recipient
@param message the sent message
*/
void prof_post_chat_message_send(const char * const jid, const char *message);
/**
Called before a MUC message is displayed
@param room The JID of the room
@param nick The nickname of the sender
@param message The message received
@return The new message, or NULL if no change made to the message
Called before a chat room message is displayed
@param room Jabber ID of the room
@param nick nickname of message sender
@param message the received message
@return the new message to display, or NULL to preserve the original message
*/
char* prof_pre_room_message_display(const char * const room, const char * const nick, const char *message);
/**
Called after a MUC message is displayed
@param room The JID of the room
@param nick The nickname of the sender
@param message The message received
Called after a chat room message is displayed
@param room Jabber ID of the room
@param nick nickname of the message sender
@param message the received message
*/
void prof_post_room_message_display(const char * const room, const char * const nick, const char *message);
/**
Called before a MUC message is sent
@param room The JID of the room
@param message The message to send
@return The new message, or NULL if no change made to the message
Called before a chat room message is sent
@param room Jabber ID of the room
@param message the message to be sent
@return the new message to send, or NULL to preserve the original message
*/
char* prof_pre_room_message_send(const char * const room, const char *message);
/**
Called after a MUC message is sent
@param room The JID of the room
@param message The message sent
Called after a chat room message has been sent
@param room Jabber ID of the room
@param message the sent message
*/
void prof_post_room_message_send(const char * const room, const char *message);
/**
Called before a MUC private message is displayed
@param room The JID of the room
@param nick The nickname of the sender
@param message The message received
@return The new message, or NULL if no change made to the message
Called when the server sends a chat room history message
@param room Jabber ID of the room
@param nick nickname of the message sender
@param message the message to be sent
@param timestamp time the message was originally sent to the room, in ISO8601 format
*/
void prof_on_room_history_message(const char * const room, const char *const nick, const char *const message, const char *const timestamp);
/**
Called before a private chat room message is displayed
@param room Jabber ID of the room
@param nick nickname of message sender
@param message the received message
@return the new message to display, or NULL to preserve the original message
*/
char* prof_pre_priv_message_display(const char * const room, const char * const nick, const char *message);
/**
Called after a MUC private message is displayed
@param room The JID of the room
@param nick The nickname of the sender
@param message The message received
Called after a private chat room message is displayed
@param room Jabber ID of the room
@param nick nickname of the message sender
@param message the received message
*/
void prof_post_priv_message_display(const char * const room, const char * const nick, const char *message);
/**
Called before a MUC private message is sent
@param room The JID of the room
@param nick The nickname of the recipient
@param message The message to send
@return The new message, or NULL if no change made to the message
Called before a private chat room message is sent
@param room Jabber ID of the room
@param nick nickname of message recipient
@param message the message to be sent
@return the new message to send, or NULL to preserve the original message
*/
char* prof_pre_priv_message_send(const char * const room, const char * const nick, const char *message);
/**
Called after a MUC private message is sent
@param room The JID of the room
@param nick The nickname of the recipient
@param message The message sent
Called after a private chat room message has been sent
@param room Jabber ID of the room
@param nick nickname of the message recipient
@param message the sent message
*/
void prof_post_priv_message_send(const char * const room, const char * const nick, const char *message);
/**
Called before an XMPP message stanza is sent
@param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza
*/
char* prof_on_message_stanza_send(const char *const stanza);
/**
Called when an XMPP message stanza is received
@param stanza The stanza received
@return 1 if Profanity should continue to process the message stanza, 0 otherwise
*/
int prof_on_message_stanza_receive(const char *const stanza);
/**
Called before an XMPP presence stanza is sent
@param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza
*/
char* prof_on_presence_stanza_send(const char *const stanza);
/**
Called when an XMPP presence stanza is received
@param stanza The stanza received
@return 1 if Profanity should continue to process the presence stanza, 0 otherwise
*/
int prof_on_presence_stanza_receive(const char *const stanza);
/**
Called before an XMPP iq stanza is sent
@param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza
*/
char* prof_on_iq_stanza_send(const char *const stanza);
/**
Called when an XMPP iq stanza is received
@param stanza The stanza received
@return 1 if Profanity should continue to process the iq stanza, 0 otherwise
*/
int prof_on_iq_stanza_receive(const char *const stanza);
/**
Called when a contact goes offline
@param barejid Jabber ID of the contact
@param resource the resource being disconnected
@param status the status message received with the offline presence, or NULL
*/
void prof_on_contact_offline(const char *const barejid, const char *const resource, const char *const status);
/**
Called when a presence notification is received from a contact
@param barejid Jabber ID of the contact
@param resource the resource being disconnected
@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd"
@param status the status message received with the presence, or NULL
@param priority the priority associated with the resource
*/
void prof_on_contact_presence(const char *const barejid, const char *const resource, const char *const presence, const char *const status, const int priority);
/**
Called when a chat window is focussed
@param barejid Jabber ID of the chat window recipient
*/
void prof_on_chat_win_focus(const char *const barejid);
/**
Called when a chat room window is focussed
@param room Jabber ID of the room
*/
void prof_on_room_win_focus(const char *const roomjid);

1
apidocs/python/src/plugin.py
View File

@ -236,6 +236,7 @@ def prof_post_priv_message_send(room, nick, message):
:param nick: nickname of the message recipient
:param message: the sent message
:type room: str or unicode
:type nick: str or unicode
:type message: str or unicode
"""
pass

14
apidocs/python/src/prof.py
View File

@ -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