From 9603e04e346d2981a9c1e7ca9a17cf0cdb230954 Mon Sep 17 00:00:00 2001 From: James Booth Date: Sat, 30 Jul 2016 22:17:42 +0100 Subject: [PATCH 1/2] Update plugin API docs --- apidocs/c/profapi.h | 270 ++++++++++++++++++++++++++----------- apidocs/python/src/prof.py | 14 +- 2 files changed, 195 insertions(+), 89 deletions(-) diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h index 1ed05360..7047b2cd 100644 --- a/apidocs/c/profapi.h +++ b/apidocs/c/profapi.h @@ -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); diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index 297960e6..247fd587 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -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 From 43b1d7f7cd4e753effe3c15f0724798077638ff3 Mon Sep 17 00:00:00 2001 From: James Booth Date: Sat, 30 Jul 2016 23:00:45 +0100 Subject: [PATCH 2/2] Update plugins API docs --- apidocs/c/profapi.h | 73 ++++++------ apidocs/c/profhooks.h | 208 +++++++++++++++++++++++++---------- apidocs/python/src/plugin.py | 1 + 3 files changed, 184 insertions(+), 98 deletions(-) diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h index 7047b2cd..257c2799 100644 --- a/apidocs/c/profapi.h +++ b/apidocs/c/profapi.h @@ -11,9 +11,7 @@ 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 */ @@ -22,16 +20,15 @@ typedef void(*TIMED_CB)(void); /** 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 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. @@ -42,14 +39,14 @@ Themes can be must be specified in ~/.local/share/profanity/plugin_themes @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 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 new command, with help information, and callback for command execution. @@ -63,7 +60,7 @@ Profanity will do some basic validation when the command is called using the arg @param examples example usages @param callback The {@link CMD_CB} function to execute when the command is invoked */ -void (*_prof_register_command)(const char *filename, const char *command_name, int min_args, int max_args, +void prof_register_command(const char *command_name, int min_args, int max_args, char **synopsis, const char *description, char *arguments[][2], char **examples, CMD_CB callback); @@ -72,14 +69,14 @@ Register a function that Profanity will call periodically. @param callback The {@link TIMED_CB} function to execute @param interval_seconds the time between each call to the function, in seconds */ -void (*_prof_register_timed)(const char *filename, TIMED_CB callback, int interval_seconds); +void prof_register_timed(TIMED_CB callback, int interval_seconds); /** 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_completer_add)(const char *filename, const char *key, char **items); +void prof_completer_add(const char *key, char **items); /** Remove values from autocompletion for a command, or command argument. @@ -87,7 +84,7 @@ 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); +void prof_completer_remove(const char *key, char **items); /** Remove all values from autocompletion for a command, or command argument. @@ -95,7 +92,7 @@ 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); +void prof_completer_clear(const char *key); /** Send a desktop notification. @@ -103,88 +100,88 @@ Send a desktop 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 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); /** 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); /** 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); /** 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); /** 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); +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); +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); /** 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); /** 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); /** 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); /** 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); +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); +int prof_win_exists(PROF_WIN_TAG win); /** 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 message in the plugin window. @@ -192,7 +189,7 @@ Show a message in the plugin window. @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 the plugin window, using the specified theme. @@ -204,14 +201,14 @@ Themes must be specified in ~/.local/share/profanity/plugin_themes @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); +int prof_send_stanza(char *stanza); /** Get a boolean setting @@ -221,7 +218,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @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); +int prof_settings_get_boolean(char *group, char *key, int def); /** Set a boolean setting @@ -230,7 +227,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @param key the item name within the group @param value value to set */ -void (*prof_settings_set_boolean)(char *group, char *key, int value); +void prof_settings_set_boolean(char *group, char *key, int value); /** Get a string setting @@ -240,7 +237,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @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); +char* prof_settings_get_string(char *group, char *key, char *def); /** Set a string setting @@ -249,7 +246,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @param key the item name within the group @param value value to set */ -void (*prof_settings_set_string)(char *group, char *key, char *value); +void prof_settings_set_string(char *group, char *key, char *value); /** Get an integer setting @@ -259,7 +256,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @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); +int prof_settings_get_int(char *group, char *key, int def); /** Set an integer setting @@ -268,7 +265,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings @param key the item name within the group @param value value to set */ -void (*prof_settings_set_int)(char *group, char *key, int value); +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 @@ -276,11 +273,11 @@ Trigger incoming message handling, this plugin will make profanity act as if the @param resource resource of the sender of the message @param message the message text */ -void (*prof_incoming_message)(char *barejid, char *resource, char *message); +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); +void prof_disco_add_feature(char *feature); diff --git a/apidocs/c/profhooks.h b/apidocs/c/profhooks.h index 039abacc..78f77291 100644 --- a/apidocs/c/profhooks.h +++ b/apidocs/c/profhooks.h @@ -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); diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index f975a342..ff70b4a3 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -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