devs/cproof
1
2
Fork 1
Code Issues 43 Pull Requests 8 Actions Packages Projects 1 Releases Wiki Activity

Fix documentation so it does not cause warnings by parsers #33

Manually merged
jabber.developer merged 5 commits from docs/minor-fixes into master 2025-09-30 08:59:20 +00:00
Conversation 0 Commits 5 Files Changed 6 +1238 -1295
6 changed files with 1238 additions and 1295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
.github/workflows/ci-api-docs.yml vendored Normal file
View File

@@ -0,0 +1,44 @@
name: CI API Docs
on:
push:
branches: [master]
paths:
- 'apidocs/**'
pull_request:
branches: [master]
paths:
- 'apidocs/**'
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
test-c-api-docs:
runs-on: ubuntu-latest
name: Test C API Documentation Generation
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends make doxygen
- name: Test C API docs generation
run: |
cd apidocs/c/
doxygen c-prof.conf
test-python-api-docs:
runs-on: ubuntu-latest
name: Test Python API Documentation Generation
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends make python3-sphinx
- name: Test Python API docs generation
run: |
cd apidocs/python/
sphinx-apidoc -f -o . src && make -j$(nproc) xml SPHINXOPTS="-W --keep-going -n"

40
.github/workflows/main.yml → .github/workflows/ci-code.yml vendored
View File

@@ -1,10 +1,18 @@
name: CI name: CI Code
on: on:
push: push:
branches: [master] branches: [master]
paths-ignore:
- 'docs/**'
- 'apidocs/**'
- 'README.md'
pull_request: pull_request:
branches: [master] branches: [master]
paths-ignore:
- 'docs/**'
- 'apidocs/**'
- 'README.md'
concurrency: concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -83,38 +91,10 @@ jobs:
continue-on-error: true continue-on-error: true
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: install dependencies - name: Install dependencies
run: | run: |
sudo apt update sudo apt update
sudo apt install -y --no-install-recommends codespell sudo apt install -y --no-install-recommends codespell
- name: Check spelling - name: Check spelling
run: | run: |
codespell codespell
test-c-api-docs:
runs-on: ubuntu-latest
name: Test C API Documentation Generation
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends make doxygen
- name: Test C API docs generation
run: |
cd apidocs/c/
doxygen c-prof.conf
test-python-api-docs:
runs-on: ubuntu-latest
name: Test Python API Documentation Generation
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends make python3-sphinx
- name: Test Python API docs generation
run: |
cd apidocs/python/
sphinx-apidoc -f -o . src && make -j$(nproc) xml SPHINXOPTS="-W --keep-going -n"

715
apidocs/c/profapi.h
View File

@@ -1,470 +1,721 @@
/** @file /** @file profapi.h
C plugin API. * @brief C Plugin API for CProof.
*
* This header defines functions for CProof plugins to interact with the console,
* windows, commands, autocompletion, notifications, and settings. All functions are
* optional and can be called by plugins to handle events like message display or
* command execution. Plugins should implement hooks in profhooks.h for event-driven
* behavior.
*
* Include this header in your plugin and call functions as needed. Example:
* @code
* #include "profapi.h"
* prof_cons_show("Hello from plugin!");
* @endcode
*
* @see profhooks.h
*/ */
/** \mainpage C Plugins API and Hooks /** Window handle for referencing plugin-created windows. */
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; typedef char* PROF_WIN_TAG;
/** Type representing a function pointer to a command callback */ /** Function pointer for command callbacks, accepting an array of arguments. */
typedef void(*CMD_CB)(char **args); typedef void(*CMD_CB)(char **args);
/** Type representing a function pointer to a timed callback */ /** Function pointer for timed callbacks, accepting no arguments. */
typedef void(*TIMED_CB)(void); typedef void(*TIMED_CB)(void);
/** Type representing a function pointer to a window callback */ /** Function pointer for window callbacks, accepting a window tag and input line. */
typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line); typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line);
/** Highlights the console window in the status bar. */ /** 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. * Shows a message in the console window.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_cons_show("This will appear in the console window");
* @endcode
*/ */
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. * Shows a message in the console with a specified theme.
Themes are specified in ~/.local/share/profanity/plugin_themes * Themes are in ~/.local/share/profanity/plugin_themes.
@param group the group name in the themes file * @param group The group name in the themes file.
@param item the item name within the group * @param item The item name within the group.
@param def default colour if the theme cannot be found * @param def Default color if theme is not found.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_cons_show_themed("myplugin", "text", NULL, "Plugin themed message");
* @endcode
*/ */
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. * Shows a message indicating a command was used incorrectly.
@param cmd the command name with leading slash, e.g. "/say" * @param cmd The command name with leading slash (e.g., "/say").
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_cons_bad_cmd_usage("/mycommand");
* @endcode
*/ */
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. * Registers a new command with help information and callback.
Profanity will do some basic validation when the command is called using the argument range. * CProof validates arguments using the specified range.
@param command_name the command name with leading slash, e.g. "/say" * @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 min_args Minimum number of valid arguments.
@param max_args maximum number or arguments that the command considers to be a valid call * @param max_args Maximum number of valid arguments.
@param synopsis command usages * @param synopsis Command usage strings.
@param description a short description of the command * @param description Short command description.
@param arguments argument descriptions * @param arguments Argument descriptions as [arg, desc] pairs.
@param examples example usages * @param examples Example usage strings.
@param callback The {@link CMD_CB} function to execute when the command is invoked * @param callback The @ref CMD_CB function to invoke.
*
* Example:
* @code
* char *synopsis[] = { "/newcommand action1|action2", "/newcommand print <arg>" };
* char *args[][2] = { { "action1|action2", "Perform action" }, { "print <arg>", "Print argument" } };
* char *examples[] = { "/newcommand action1", "/newcommand print \"Test\"" };
* prof_register_command("/newcommand", 1, 2, synopsis, "Example command", args, examples, my_function);
* @endcode
*/ */
void prof_register_command(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, char **synopsis, const char *description, char *arguments[][2], char **examples,
CMD_CB callback); CMD_CB callback);
/** /**
Register a function that Profanity will call periodically. * Registers a function to be called periodically by CProof.
@param callback The {@link TIMED_CB} function to execute * @param callback The @ref TIMED_CB function to execute.
@param interval_seconds the time between each call to the function, in seconds * @param interval_seconds Time between calls, in seconds.
*
* Example:
* @code
* prof_register_timed(my_function, 30);
* @endcode
*/ */
void prof_register_timed(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. * Adds autocomplete values for a command or argument.
@param key the prefix to trigger autocompletion * @param key The prefix to trigger autocompletion.
@param items the items to return on autocompletion * @param items Items to autocomplete.
*
* Example:
* @code
* char *items[] = { "action1", "action2", NULL };
* prof_completer_add("/mycommand", items);
* @endcode
*/ */
void prof_completer_add(const char *key, char **items); void prof_completer_add(const char *key, char **items);
/** /**
Remove values from autocompletion for a command, or command argument. * Removes autocomplete values for a command or argument.
* @param key The prefix to remove items from.
@param key the prefix from which to remove the autocompletion items * @param items Items to remove.
@param items the items to remove *
* Example:
* @code
* char *items[] = { "action1", NULL };
* prof_completer_remove("/mycommand", items);
* @endcode
*/ */
void prof_completer_remove(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. * Clears all autocomplete values for a command or argument.
* @param key The prefix to clear.
@param key the prefix from which to clear the autocompletion items *
* Example:
* @code
* prof_completer_clear("/mycommand");
* @endcode
*/ */
void prof_completer_clear(const char *key); void prof_completer_clear(const char *key);
/** /**
Add filepath autocompletion for a command, or command argument. * Adds filepath autocompletion for a command or argument.
* @param prefix The prefix to trigger filepath autocompletion.
@param prefix the prefix from which filepath autocompletion will be triggered *
* Example:
* @code
* prof_filepath_completer_add("/filecmd");
* @endcode
*/ */
void prof_filepath_completer_add(const char *prefix); void prof_filepath_completer_add(const char *prefix);
/** /**
Send a desktop notification. * Sends a desktop notification.
@param message the message to display in the notification * @param message The message to display.
@param timeout_ms the length of time before the notification disappears in milliseconds * @param timeout_ms Duration before the notification disappears (milliseconds).
@param category the category of the notification, also displayed * @param category The notification category.
*
* Example:
* @code
* prof_notify("Example notification", 5000, "Example plugin");
* @endcode
*/ */
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. * Sends a line of input to CProof to execute.
@param line the line to send * @param line The command line to send.
*
* Example:
* @code
* prof_send_line("/who online");
* @endcode
*/ */
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. * Gets the Jabber ID of the current chat recipient.
@return the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window. * @return The Jabber ID (e.g., "buddy@example.com") 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. * Gets the Jabber ID of the current chat room.
@return the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window. * @return The room Jabber ID (e.g., "metalchat@conference.example.com") or NULL if not in a room.
*/ */
char* prof_get_current_muc(void); char* prof_get_current_muc(void);
/** /**
Determine whether or not the Console window is currently focused. * Checks if the console window is currently focused.
@return 1 if the user is currently in the Console window, 0 otherwise. * @return 1 if 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. * Gets the user’s nickname in the current chat room.
@return the users nickname in the current chat room e.g. "eddie", or NULL if not in a chat room window. * @return The nickname (e.g., "eddie") or NULL if not in a room.
*/ */
char* prof_get_current_nick(void); char* prof_get_current_nick(void);
/** /**
Retrieve the nickname for a given barejid if it is in the roster. * Gets the nickname for a barejid from the roster.
@return the users nickname e.g. "eddie", or the input barejid if it is not in the roster. * @param barejid The Jabber ID.
* @return The nickname (e.g., "eddie") or the barejid if not in the roster.
*/ */
char* prof_get_name_from_roster(const char *barejid); char* prof_get_name_from_roster(const char *barejid);
/** /**
Retrieve the barejid for a given nickname if it is in the roster. * Gets the barejid for a nickname from the roster.
@return the users barejid e.g. "eddie@server.tld", or NULL if the nickname is not in the roster. * @param name The nickname.
* @return The barejid (e.g., "eddie@server.tld") or NULL if not in the roster.
*/ */
char* prof_get_barejid_from_roster(const char *name); char* prof_get_barejid_from_roster(const char *name);
/** /**
Retrieve nicknames of all occupants in a chat room, when in a chat room window. * Gets nicknames of all occupants in the current chat room.
@return nicknames of all occupants in the current room or an empty list if not in a chat room window. * @return List of nicknames or an empty list if not in a room.
*/ */
char** prof_get_current_occupants(void); char** prof_get_current_occupants(void);
/** /**
Retrieve current nickname used in chat room. * Gets the current nickname in a chat room.
@param barejid The room's Jabber ID * @param barejid The room’s Jabber ID.
@return Room nickname. * @return The nickname.
*/ */
char* prof_get_room_nick(const char *barejid); char* prof_get_room_nick(const char *barejid);
/** /**
Write to the Profanity log at level DEBUG. * Logs a debug message to the CProof log.
@param message The message to log * @param message The message to log.
*
* Example:
* @code
* prof_log_debug("Debug message");
* @endcode
*/ */
void prof_log_debug(const char *message); void prof_log_debug(const char *message);
/** /**
Write to the Profanity log at level INFO. * Logs an info message to the CProof log.
@param message The message to log * @param message The message to log.
*
* Example:
* @code
* prof_log_info("Info message");
* @endcode
*/ */
void prof_log_info(const char *message); void prof_log_info(const char *message);
/** /**
Write to the Profanity log at level WARNING. * Logs a warning message to the CProof log.
@param message The message to log * @param message The message to log.
*
* Example:
* @code
* prof_log_warning("Warning message");
* @endcode
*/ */
void prof_log_warning(const char *message); void prof_log_warning(const char *message);
/** /**
Write to the Profanity log at level ERROR. * Logs an error message to the CProof log.
@param message The message to log * @param message The message to log.
*
* Example:
* @code
* prof_log_error("Error message");
* @endcode
*/ */
void prof_log_error(const char *message); void prof_log_error(const char *message);
/** /**
Create a plugin window. * Creates a plugin window.
@param win The {@link PROF_WIN_TAG} used to refer to the window * @param win The @ref PROF_WIN_TAG to refer to the window.
@param input_handler The WINDOW_CB function to call when the window receives input * @param input_handler The @ref WINDOW_CB function for input handling.
*
* Example:
* @code
* prof_win_create("My Plugin", window_handler);
* @endcode
*/ */
void prof_win_create(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}. * Checks if a plugin window exists.
@param win the {@link PROF_WIN_TAG} used when creating the plugin window * @param win The @ref PROF_WIN_TAG of the window.
@return 1 if the window exists, 0 otherwise * @return 1 if the window exists, 0 otherwise.
*
* Example:
* @code
* prof_win_exists("My Plugin");
* @endcode
*/ */
int prof_win_exists(PROF_WIN_TAG win); int prof_win_exists(PROF_WIN_TAG win);
/** /**
Focus plugin window. * Focuses a plugin window.
@param win the {@link PROF_WIN_TAG} of the window to focus * @param win The @ref PROF_WIN_TAG of the window.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_win_focus("My Plugin");
* @endcode
*/ */
int prof_win_focus(PROF_WIN_TAG win); int prof_win_focus(PROF_WIN_TAG win);
/** /**
Show a message in the plugin window. * Shows a message in a plugin window.
@param win the {@link PROF_WIN_TAG} of the window to display the message * @param win The @ref PROF_WIN_TAG of the window.
@param message The message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_win_show("My Plugin", "Message in plugin window");
* @endcode
*/ */
int prof_win_show(PROF_WIN_TAG win, char *message); int prof_win_show(PROF_WIN_TAG win, char *message);
/** /**
Show a message in the plugin window, using the specified theme. * Shows a message in a plugin window with a specified theme.
Themes are specified in ~/.local/share/profanity/plugin_themes * Themes are in ~/.local/share/profanity/plugin_themes.
@param tag The {@link PROF_WIN_TAG} of the window to display the message * @param tag The @ref PROF_WIN_TAG of the window.
@param group the group name in the themes file * @param group The group name in the themes file.
@param key the item name within the group * @param key The item name within the group.
@param def default colour if the theme cannot be found or NULL * @param def Default color if theme is not found or NULL.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_win_show_themed("My Plugin", "myplugin", "text", NULL, "Themed message");
* @endcode
*/ */
int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *message); int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *message);
/** /**
Send an XMPP stanza * Sends an XMPP stanza.
@param stanza an XMPP stanza * @param stanza The XMPP stanza to send.
@return 1 if the stanza was sent successfully, 0 otherwise * @return 1 if sent successfully, 0 otherwise.
*
* Example:
* @code
* prof_send_stanza("<iq to='juliet@capulet.lit' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>");
* @endcode
*/ */
int prof_send_stanza(char *stanza); int prof_send_stanza(char *stanza);
/** /**
Get a boolean setting * Gets a boolean setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param def default value if setting not found * @param def Default value if not found.
@return the setting, or default value * @return The setting or default value.
*
* Example:
* @code
* prof_settings_boolean_get("myplugin", "notify", 0);
* @endcode
*/ */
int prof_settings_boolean_get(char *group, char *key, int def); int prof_settings_boolean_get(char *group, char *key, int def);
/** /**
Set a boolean setting * Sets a boolean setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param value value to set * @param value The value to set.
*
* Example:
* @code
* prof_settings_boolean_set("myplugin", "activate", 1);
* @endcode
*/ */
void prof_settings_boolean_set(char *group, char *key, int value); void prof_settings_boolean_set(char *group, char *key, int value);
/** /**
Get a string setting * Gets a string setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param def default value if setting not found * @param def Default value if not found.
@return the setting, or default value * @return The setting or default value.
*
* Example:
* @code
* prof_settings_string_get("myplugin", "prefix", "prefix-->");
* @endcode
*/ */
char* prof_settings_string_get(char *group, char *key, char *def); char* prof_settings_string_get(char *group, char *key, char *def);
/** /**
Set a string setting * Sets a string setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param value value to set * @param value The value to set.
*
* Example:
* @code
* prof_settings_string_set("myplugin", "prefix", "myplugin, ");
* @endcode
*/ */
void prof_settings_string_set(char *group, char *key, char *value); void prof_settings_string_set(char *group, char *key, char *value);
/** /**
Get a string list setting * Gets a string list setting, separated by semicolons.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
The string list setting items are separated by semicolons. * @param group The group name in the settings file.
@param group the group name in the settings file * @param key The item name within the group.
@param key the item name within the group * @return The list setting.
@return the list setting *
* Example:
* @code
* prof_settings_string_list_get("myplugin", "somelist");
* @endcode
*/ */
char** prof_settings_string_list_get(char *group, char *key); char** prof_settings_string_list_get(char *group, char *key);
/** /**
Add an item to a string list setting * Adds an item to a string list setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
If the list does not exist, a new one will be created with the element added * Creates a new list if none exists.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param value item to add * @param value The item to add.
*
* Example:
* @code
* prof_settings_string_list_add("myplugin", "somelist", "anelement");
* @endcode
*/ */
void prof_settings_string_list_add(char *group, char *key, char *value); void prof_settings_string_list_add(char *group, char *key, char *value);
/** /**
Remove an item from a string list setting * Removes an item from a string list setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param value item to remove * @param value The item to remove.
@return 1 if the item was removed, or is not in the list, 0 if the list does not exist * @return 1 if removed or not in the list, 0 if the list does not exist.
*
* Example:
* @code
* prof_settings_string_list_remove("myplugin", "somelist", "anelement");
* @endcode
*/ */
int prof_settings_string_list_remove(char *group, char *key, char *value); int prof_settings_string_list_remove(char *group, char *key, char *value);
/** /**
Remove all items from a string list setting * Clears all items from a string list setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@return 1 if the list was cleared, 0 if the list does not exist * @return 1 if cleared, 0 if the list does not exist.
*
* Example:
* @code
* prof_settings_string_list_clear("myplugin", "somelist");
* @endcode
*/ */
int prof_settings_string_list_clear(char *group, char *key); int prof_settings_string_list_clear(char *group, char *key);
/** /**
Get an integer setting * Gets an integer setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param def default value if setting not found * @param def Default value if not found.
@return the setting, or default value * @return The setting or default value.
*
* Example:
* @code
* prof_settings_int_get("myplugin", "timeout", 10);
* @endcode
*/ */
int prof_settings_int_get(char *group, char *key, int def); int prof_settings_int_get(char *group, char *key, int def);
/** /**
Set an integer setting * Sets an integer setting.
Settings must be specified in ~/.local/share/profanity/plugin_settings * Settings are in ~/.local/share/profanity/plugin_settings.
@param group the group name in the settings file * @param group The group name in the settings file.
@param key the item name within the group * @param key The item name within the group.
@param value value to set * @param value The value to set.
*
* Example:
* @code
* prof_settings_int_set("myplugin", "timeout", 100);
* @endcode
*/ */
void prof_settings_int_set(char *group, char *key, int value); void prof_settings_int_set(char *group, char *key, int value);
/** /**
Trigger incoming message handling, this plugin will make profanity act as if the message has been received * Triggers handling of an incoming message as if received by CProof.
@param barejid Jabber ID of the sender of the message * @param barejid Jabber ID of the sender.
@param resource resource of the sender of the message * @param resource Resource of the sender.
@param message the message text * @param message The message text.
*
* Example:
* @code
* prof_incoming_message("bob@server.org", "laptop", "Hello there");
* @endcode
*/ */
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. * Adds a service discovery feature to CProof’s supported features.
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 * Sends a presence update if a session is connected.
@param feature the service discovery feature to be added * @param feature The feature to add.
*
* Example:
* @code
* prof_disco_add_feature("urn:xmpp:omemo:0:devicelist+notify");
* @endcode
*/ */
void prof_disco_add_feature(char *feature); void prof_disco_add_feature(char *feature);
/** /**
End any encrypted session with the specified user. * Ends an encrypted session with a user.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
*
* Example:
* @code
* prof_encryption_reset("alice@server.org");
* @endcode
*/ */
void prof_encryption_reset(char *barejid); void prof_encryption_reset(char *barejid);
/** /**
Set the text to display in the titlebar encryption indicator for recipient. * Sets the titlebar encryption indicator text for a recipient.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@param enctext The text to display * @param enctext The text to display.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_set_titlebar_enctext("bob@example.com", "safe");
* @endcode
*/ */
int prof_chat_set_titlebar_enctext(char *barejid, char *enctext); int prof_chat_set_titlebar_enctext(char *barejid, char *enctext);
/** /**
Let profanity decide what to show in the titlebar encryption indicator for recipient. * Resets the titlebar encryption indicator for a recipient to CProof’s default.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_unset_titlebar_enctext("bob@example.com");
* @endcode
*/ */
int prof_chat_unset_titlebar_enctext(char *barejid); int prof_chat_unset_titlebar_enctext(char *barejid);
/** /**
Set the incoming message prefix character for specified contact. * Sets the incoming message prefix character for a contact.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@param ch The character to display * @param ch The character to display.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_set_incoming_char("kristine@example.com", "*");
* @endcode
*/ */
int prof_chat_set_incoming_char(char *barejid, char *ch); int prof_chat_set_incoming_char(char *barejid, char *ch);
/** /**
Reset the incoming message prefix character for specified contact. * Resets the incoming message prefix character for a contact.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_unset_incoming_char("kristine@example.com");
* @endcode
*/ */
int prof_chat_unset_incoming_char(char *barejid); int prof_chat_unset_incoming_char(char *barejid);
/** /**
Set the outgoing message prefix character for specified contact. * Sets the outgoing message prefix character for a contact.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@param ch The character to display * @param ch The character to display.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_set_outgoing_char("david@example.com", "+");
* @endcode
*/ */
int prof_chat_set_outgoing_char(char *barejid, char *ch); int prof_chat_set_outgoing_char(char *barejid, char *ch);
/** /**
Reset the outgoing message prefix character for specified contact. * Resets the outgoing message prefix character for a contact.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_unset_outgoing_char("david@example.com");
* @endcode
*/ */
int prof_chat_unset_outgoing_char(char *barejid); int prof_chat_unset_outgoing_char(char *barejid);
/** /**
Set the text to display in the titlebar encryption indicator for room. * Sets the titlebar encryption indicator text for a room.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@param enctext The text to display * @param enctext The text to display.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_set_titlebar_enctext("generalchat@conference.service.com", "secret");
* @endcode
*/ */
int prof_room_set_titlebar_enctext(char *roomjid, char *enctext); int prof_room_set_titlebar_enctext(char *roomjid, char *enctext);
/** /**
Let profanity decide what to show in the titlebar encryption indicator for room. * Resets the titlebar encryption indicator for a room to CProof’s default.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_unset_titlebar_enctext("generalchat@conference.service.com");
* @endcode
*/ */
int prof_room_unset_titlebar_enctext(char *roomjid); int prof_room_unset_titlebar_enctext(char *roomjid);
/** /**
Set the message prefix character for specified room. * Sets the message prefix character for a room.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@param ch The character to display * @param ch The character to display.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_set_message_char("ohnoes@conference.example.com", "^");
* @endcode
*/ */
int prof_room_set_message_char(char *roomjid, char *ch); int prof_room_set_message_char(char *roomjid, char *ch);
/** /**
Reset the message prefix character for specified room. * Resets the message prefix character for a room.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_unset_message_char("ohnoes@conference.example.com");
* @endcode
*/ */
int prof_room_unset_message_char(char *roomjid); int prof_room_unset_message_char(char *roomjid);
/** /**
Show a message in a chat window. * Shows a message in a chat window.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_show("bob@server.org", "From a plugin in the chat window");
* @endcode
*/ */
int prof_chat_show(char *barejid, char *message); int prof_chat_show(char *barejid, char *message);
/** /**
Show a message in a chat window, using the specified theme, and prefix character * Shows a message in a chat window with a theme and prefix character.
Themes are specified in ~/.local/share/profanity/plugin_themes * Themes are in ~/.local/share/profanity/plugin_themes.
@param barejid Jabber ID of the recipient * @param barejid Jabber ID of the recipient.
@param group the group name in the themes file or NULL * @param group The group name in the themes file or NULL.
@param item the item name within the group or NULL * @param item The item name within the group or NULL.
@param def default colour if the theme cannot be found * @param def Default color if theme is not found.
@param ch The character to prefix the message, or NULL for default behaviour * @param ch The prefix character or NULL for default.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_chat_show_themed("bob@server.org", "myplugin", "text", NULL, "!", "Themed message");
* @endcode
*/ */
int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, char *ch, char *message); int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, char *ch, char *message);
/** /**
Show a message in a chat room window. * Shows a message in a chat room window.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_show("chat@conference.example.com", "From a plugin in the chat room");
* @endcode
*/ */
int prof_room_show(char *roomjid, char *message); int prof_room_show(char *roomjid, char *message);
/** /**
Show a message in a chat room window, using the specified theme, and prefix character * Shows a message in a chat room window with a theme and prefix character.
Themes are specified in ~/.local/share/profanity/plugin_themes * Themes are in ~/.local/share/profanity/plugin_themes.
@param roomjid Jabber ID of the room * @param roomjid Jabber ID of the room.
@param group the group name in the themes file or NULL * @param group The group name in the themes file or NULL.
@param item the item name within the group or NULL * @param item The item name within the group or NULL.
@param def default colour if the theme cannot be found * @param def Default color if theme is not found.
@param ch The character to prefix the message, or NULL for default behaviour * @param ch The prefix character or NULL for default.
@param message the message to print * @param message The message to print.
@return 1 on success, 0 on failure * @return 1 on success, 0 on failure.
*
* Example:
* @code
* prof_room_show_themed("chat@conference.example.com", "myplugin", "text", NULL, "!", "Themed message");
* @endcode
*/ */
int prof_room_show_themed(char *roomjid, char *group, char *item, char *def, char *ch, char *message); int prof_room_show_themed(char *roomjid, char *group, char *item, char *def, char *ch, char *message);

233
apidocs/c/profhooks.h
View File

@@ -1,220 +1,247 @@
/** @file /** @file profhooks.h
C Hooks. * @brief C Plugin Hooks for CProof.
*
* This header defines optional callback hooks that CProof plugins can implement to
* handle events such as startup, shutdown, message processing, and presence updates in
* CProof, a console-based XMPP client. These hooks are called by CProof when the
* corresponding events occur, allowing plugins to customize behavior. All hooks are
* optional; plugins can define only the hooks they need, and CProof will automatically
* invoke them when appropriate.
*
* To use these hooks, define the functions in your plugin with the signatures provided
* in this header. For example, to handle the startup event:
*
* @code
* #include "profhooks.h"
* void prof_on_start(void) {
* // Handle CProof startup
* }
* @endcode
*
* For additional plugin functionality, such as displaying messages or registering
* commands, see the CProof API functions in profapi.h.
*
* @see profapi.h
*/
/** @mainpage CProof Plugins API and Hooks
* List of all API functions available to plugins: @ref profapi.h
* List of all hooks which plugins may implement: @ref profhooks.h
*/ */
/** /**
Called when a plugin is loaded, either when profanity is started, or when the /plugins load or /plugins install commands are called * Called when a plugin is loaded, either when CProof is started, or when the /plugins load or /plugins install commands are called
@param version the version of Profanity * @param version The version of CProof
@param status the package status of Profanity, "development" or "release" * @param status The package status of CProof, "development" or "release"
@param account_name account name of the currently logged in account, or NULL if not logged in * @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 * @param fulljid The user's full Jabber ID (barejid and resource) if logged in, NULL otherwise
*/ */
void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid); void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid);
/** /**
Called when Profanity is started * Called when CProof is started
*/ */
void prof_on_start(void); void prof_on_start(void);
/** /**
Called when the user quits Profanity * Called when the user quits CProof
*/ */
void prof_on_shutdown(void); void prof_on_shutdown(void);
/** /**
Called when a plugin is unloaded with the /plugins unload command * Called when a plugin is unloaded with the /plugins unload command
*/ */
void prof_on_unload(void); void prof_on_unload(void);
/** /**
Called when the user connects with an account * Called when the user connects with an account
@param account_name account name of the account used for logging in * @param account_name Account name of the account used for logging in
@param fulljid the full Jabber ID (barejid and resource) of the account * @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); void prof_on_connect(const char * const account_name, const char * const fulljid);
/** /**
Called when the user disconnects an account * Called when the user disconnects an account
@param account_name account name of the account being disconnected * @param account_name Account name of the account being disconnected
@param fulljid the full Jabber ID (barejid and resource) of the account * @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); void prof_on_disconnect(const char * const account_name, const char * const fulljid);
/** /**
Called before a chat message is displayed * Called before a chat message is displayed
@param barejid Jabber ID of the message sender * @param barejid Jabber ID of the message sender
@param resource resource of the message sender * @param resource Resource of the message sender
@param message the received message * @param message The received message
@return the new message to display, or NULL to preserve the original message * @return The new message to display, or NULL to preserve the original message
*/ */
char* prof_pre_chat_message_display(const char * const barejid, const char *const resource, const char *message); char* prof_pre_chat_message_display(const char * const barejid, const char *const resource, const char *message);
/** /**
Called after a chat message is displayed * Called after a chat message is displayed
@param barejid Jabber ID of the message sender * @param barejid Jabber ID of the message sender
@param resource resource of the message sender * @param resource Resource of the message sender
@param message the received message * @param message The received message
*/ */
void prof_post_chat_message_display(const char * const barejid, const char *const resource, const char *message); void prof_post_chat_message_display(const char * const barejid, const char *const resource, const char *message);
/** /**
Called before a chat message is sent * Called before a chat message is sent
@param barejid Jabber ID of the message recipient * @param barejid Jabber ID of the message recipient
@param message the message to be sent * @param message The message to be sent
@return the modified or original message to send, or NULL to cancel sending of the message * @return The modified or original message to send, or NULL to cancel sending of the message
*/ */
char* prof_pre_chat_message_send(const char * const barejid, const char *message); char* prof_pre_chat_message_send(const char * const barejid, const char *message);
/** /**
Called after a chat message has been sent * Called after a chat message has been sent
@param barejid Jabber ID of the message recipient * @param barejid Jabber ID of the message recipient
@param message the sent message * @param message The sent message
*/ */
void prof_post_chat_message_send(const char * const barejid, const char *message); void prof_post_chat_message_send(const char * const barejid, const char *message);
/** /**
Called before a chat room message is displayed * Called before a chat room message is displayed
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of message sender * @param nick Nickname of message sender
@param message the received message * @param message The received message
@return the new message to display, or NULL to preserve the original message * @return The new message to display, or NULL to preserve the original message
*/ */
char* prof_pre_room_message_display(const char * const barejid, const char * const nick, const char *message); char* prof_pre_room_message_display(const char * const barejid, const char * const nick, const char *message);
/** /**
Called after a chat room message is displayed * Called after a chat room message is displayed
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of the message sender * @param nick Nickname of the message sender
@param message the received message * @param message The received message
*/ */
void prof_post_room_message_display(const char * const barejid, const char * const nick, const char *message); void prof_post_room_message_display(const char * const barejid, const char * const nick, const char *message);
/** /**
Called before a chat room message is sent * Called before a chat room message is sent
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param message the message to be sent * @param message The message to be sent
@return the modified or original message to send, or NULL to cancel sending of the message * @return The modified or original message to send, or NULL to cancel sending of the message
*/ */
char* prof_pre_room_message_send(const char * const barejid, const char *message); char* prof_pre_room_message_send(const char * const barejid, const char *message);
/** /**
Called after a chat room message has been sent * Called after a chat room message has been sent
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param message the sent message * @param message The sent message
*/ */
void prof_post_room_message_send(const char * const barejid, const char *message); void prof_post_room_message_send(const char * const barejid, const char *message);
/** /**
Called when the server sends a chat room history message * Called when the server sends a chat room history message
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of the message sender * @param nick Nickname of the message sender
@param message the message to be sent * @param message The message to be sent
@param timestamp time the message was originally sent to the room, in ISO8601 format * @param timestamp Time the message was originally sent to the room, in ISO8601 format
*/ */
void prof_on_room_history_message(const char * const barejid, const char *const nick, const char *const message, const char *const timestamp); void prof_on_room_history_message(const char * const barejid, const char *const nick, const char *const message, const char *const timestamp);
/** /**
Called before a private chat room message is displayed * Called before a private chat room message is displayed
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of message sender * @param nick Nickname of message sender
@param message the received message * @param message The received message
@return the new message to display, or NULL to preserve the original message * @return The new message to display, or NULL to preserve the original message
*/ */
char* prof_pre_priv_message_display(const char * const barejid, const char * const nick, const char *message); char* prof_pre_priv_message_display(const char * const barejid, const char * const nick, const char *message);
/** /**
Called after a private chat room message is displayed * Called after a private chat room message is displayed
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of the message sender * @param nick Nickname of the message sender
@param message the received message * @param message The received message
*/ */
void prof_post_priv_message_display(const char * const barejid, const char * const nick, const char *message); void prof_post_priv_message_display(const char * const barejid, const char * const nick, const char *message);
/** /**
Called before a private chat room message is sent * Called before a private chat room message is sent
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of message recipient * @param nick Nickname of message recipient
@param message the message to be sent * @param message The message to be sent
@return the modified or original message to send, or NULL to cancel sending of the message * @return The modified or original message to send, or NULL to cancel sending of the message
*/ */
char* prof_pre_priv_message_send(const char * const barejid, const char * const nick, const char *message); char* prof_pre_priv_message_send(const char * const barejid, const char * const nick, const char *message);
/** /**
Called after a private chat room message has been sent * Called after a private chat room message has been sent
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
@param nick nickname of the message recipient * @param nick Nickname of the message recipient
@param message the sent message * @param message The sent message
*/ */
void prof_post_priv_message_send(const char * const barejid, const char * const nick, const char *message); void prof_post_priv_message_send(const char * const barejid, const char * const nick, const char *message);
/** /**
Called before an XMPP message stanza is sent * Called before an XMPP message stanza is sent
@param stanza The stanza to send * @param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza * @return The new stanza to send, or NULL to preserve the original stanza
*/ */
char* prof_on_message_stanza_send(const char *const stanza); char* prof_on_message_stanza_send(const char *const stanza);
/** /**
Called when an XMPP message stanza is received * Called when an XMPP message stanza is received
@param stanza The stanza received * @param stanza The stanza received
@return 1 if Profanity should continue to process the message stanza, 0 otherwise * @return 1 if CProof should continue to process the message stanza, 0 otherwise
*/ */
int prof_on_message_stanza_receive(const char *const stanza); int prof_on_message_stanza_receive(const char *const stanza);
/** /**
Called before an XMPP presence stanza is sent * Called before an XMPP presence stanza is sent
@param stanza The stanza to send * @param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza * @return The new stanza to send, or NULL to preserve the original stanza
*/ */
char* prof_on_presence_stanza_send(const char *const stanza); char* prof_on_presence_stanza_send(const char *const stanza);
/** /**
Called when an XMPP presence stanza is received * Called when an XMPP presence stanza is received
@param stanza The stanza received * @param stanza The stanza received
@return 1 if Profanity should continue to process the presence stanza, 0 otherwise * @return 1 if CProof should continue to process the presence stanza, 0 otherwise
*/ */
int prof_on_presence_stanza_receive(const char *const stanza); int prof_on_presence_stanza_receive(const char *const stanza);
/** /**
Called before an XMPP iq stanza is sent * Called before an XMPP iq stanza is sent
@param stanza The stanza to send * @param stanza The stanza to send
@return The new stanza to send, or NULL to preserve the original stanza * @return The new stanza to send, or NULL to preserve the original stanza
*/ */
char* prof_on_iq_stanza_send(const char *const stanza); char* prof_on_iq_stanza_send(const char *const stanza);
/** /**
Called when an XMPP iq stanza is received * Called when an XMPP iq stanza is received
@param stanza The stanza received * @param stanza The stanza received
@return 1 if Profanity should continue to process the iq stanza, 0 otherwise * @return 1 if CProof should continue to process the iq stanza, 0 otherwise
*/ */
int prof_on_iq_stanza_receive(const char *const stanza); int prof_on_iq_stanza_receive(const char *const stanza);
/** /**
Called when a contact goes offline * Called when a contact goes offline
@param barejid Jabber ID of the contact * @param barejid Jabber ID of the contact
@param resource the resource being disconnected * @param resource The resource being disconnected
@param status the status message received with the offline presence, or NULL * @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); 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 * Called when a presence notification is received from a contact
@param barejid Jabber ID of the contact * @param barejid Jabber ID of the contact
@param resource the resource being disconnected * @param resource The resource being disconnected
@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd" * @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 status The status message received with the presence, or NULL
@param priority the priority associated with the resource * @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); 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 focused * Called when a chat window is focused
@param barejid Jabber ID of the chat window recipient * @param barejid Jabber ID of the chat window recipient
*/ */
void prof_on_chat_win_focus(const char *const barejid); void prof_on_chat_win_focus(const char *const barejid);
/** /**
Called when a chat room window is focused * Called when a chat room window is focused
@param barejid Jabber ID of the room * @param barejid Jabber ID of the room
*/ */
void prof_on_room_win_focus(const char *const barejid); void prof_on_room_win_focus(const char *const barejid);

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

@@ -3,12 +3,14 @@ The plugin module defines optional callback functions that CProof plugins can
implement to handle events such as startup, shutdown, message processing, and implement to handle events such as startup, shutdown, message processing, and
presence updates. presence updates.
:: All functions are optional and are called by CProof when the corresponding event
occurs. You need to define them in your module and they will automatically be used
for callback events.
To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof``
documentation and use::
import prof import prof
All functions are optional and are called by CProof when the corresponding event
occurs. String parameters and return values are Python 3 str types.
""" """
# Initialization and Lifecycle # Initialization and Lifecycle
@@ -20,18 +22,13 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str
Called when CProof starts or when the plugin is loaded via the ``/plugins load`` Called when CProof starts or when the plugin is loaded via the ``/plugins load``
or ``/plugins install`` commands. or ``/plugins install`` commands.
Args: :param version: The version of CProof (e.g., ``"1.0.0"``).
version: The version of CProof (e.g., ``"1.0.0"``). :param status: The package status of CProof (``"development"`` or ``"release"``).
status: The package status of CProof (``"development"`` or ``"release"``). :param account_name: The account name of the logged-in user, or None if not logged in.
account_name: The account name of the logged-in user, or None if not logged in. :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in. :return: None
Returns: Example::
None
Example:
::
def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None: def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}") prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}")
@@ -43,15 +40,9 @@ def prof_on_start() -> None:
Use this to perform setup tasks that should occur at application startup. Use this to perform setup tasks that should occur at application startup.
Args: :return: None
None
Returns: Example::
None
Example:
::
def prof_on_start() -> None: def prof_on_start() -> None:
prof.cons_show("CProof has started...") prof.cons_show("CProof has started...")
@@ -63,15 +54,9 @@ def prof_on_shutdown() -> None:
Use this to perform cleanup tasks before the application exits. Use this to perform cleanup tasks before the application exits.
Args: :return: None
None
Returns: Example::
None
Example:
::
def prof_on_shutdown() -> None: def prof_on_shutdown() -> None:
prof.cons_show("CProof is shutting down...") prof.cons_show("CProof is shutting down...")
@@ -83,15 +68,9 @@ def prof_on_unload() -> None:
Use this to clean up plugin-specific resources. Use this to clean up plugin-specific resources.
Args: :return: None
None
Returns: Example::
None
Example:
::
def prof_on_unload() -> None: def prof_on_unload() -> None:
prof.cons_show("Plugin unloaded") prof.cons_show("Plugin unloaded")
@@ -101,16 +80,11 @@ def prof_on_unload() -> None:
def prof_on_connect(account_name: str, fulljid: str) -> None: def prof_on_connect(account_name: str, fulljid: str) -> None:
"""Called when a user connects to CProof with an account. """Called when a user connects to CProof with an account.
Args: :param account_name: The account name used for login.
account_name: The account name used for login. :param fulljid: The full Jabber ID (barejid/resource) of the connected account.
fulljid: The full Jabber ID (barejid/resource) of the connected account. :return: None
Returns: Example::
None
Example:
::
def prof_on_connect(account_name: str, fulljid: str) -> None: def prof_on_connect(account_name: str, fulljid: str) -> None:
prof.cons_show(f"Connected as {account_name} ({fulljid})") prof.cons_show(f"Connected as {account_name} ({fulljid})")
@@ -120,16 +94,11 @@ def prof_on_connect(account_name: str, fulljid: str) -> None:
def prof_on_disconnect(account_name: str, fulljid: str) -> None: def prof_on_disconnect(account_name: str, fulljid: str) -> None:
"""Called when a user disconnects an account from CProof. """Called when a user disconnects an account from CProof.
Args: :param account_name: The account name being disconnected.
account_name: The account name being disconnected. :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
fulljid: The full Jabber ID (barejid/resource) of the disconnected account. :return: None
Returns: Example::
None
Example:
::
def prof_on_disconnect(account_name: str, fulljid: str) -> None: def prof_on_disconnect(account_name: str, fulljid: str) -> None:
prof.cons_show(f"Disconnected {account_name} ({fulljid})") prof.cons_show(f"Disconnected {account_name} ({fulljid})")
@@ -144,17 +113,12 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) ->
Allows the plugin to modify or cancel the message display. Allows the plugin to modify or cancel the message display.
Args: :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). :param resource: The sender's resource (e.g., ``laptop``).
resource: The sender's resource (e.g., ``laptop``). :param message: The received message.
message: The received message. :return: The modified message to display, or None to preserve the original.
Returns: Example::
str | None: The modified message to display, or None to preserve the original.
Example:
::
def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
new_message = f"{message} (from {barejid})" new_message = f"{message} (from {barejid})"
@@ -167,17 +131,12 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) ->
Use this to perform actions after the message is shown. Use this to perform actions after the message is shown.
Args: :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). :param resource: The sender's resource (e.g., ``laptop``).
resource: The sender's resource (e.g., ``laptop``). :param message: The displayed message.
message: The displayed message. :return: None
Returns: Example::
None
Example:
::
def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}") prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}")
@@ -189,16 +148,11 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
Allows the plugin to modify or cancel the message. Allows the plugin to modify or cancel the message.
Args: :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). :param message: The message to be sent.
message: The message to be sent. :return: The modified message to send, or None to cancel sending.
Returns: Example::
str | None: The modified message to send, or None to cancel sending.
Example:
::
def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
return f"{message} (sent by plugin)" return f"{message} (sent by plugin)"
@@ -210,16 +164,11 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None:
Use this to log or react to sent messages. Use this to log or react to sent messages.
Args: :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). :param message: The sent message.
message: The sent message. :return: None
Returns: Example::
None
Example:
::
def prof_post_chat_message_send(barejid: str, message: str) -> None: def prof_post_chat_message_send(barejid: str, message: str) -> None:
prof.cons_show(f"Sent to {barejid}: {message}") prof.cons_show(f"Sent to {barejid}: {message}")
@@ -234,17 +183,12 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str
Allows the plugin to modify or cancel the message display. Allows the plugin to modify or cancel the message display.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message sender.
nick: The nickname of the message sender. :param message: The received message.
message: The received message. :return: The modified message to display, or None to preserve the original.
Returns: Example::
str | None: The modified message to display, or None to preserve the original.
Example:
::
def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (from {nick})" return f"{message} (from {nick})"
@@ -256,17 +200,12 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non
Use this to perform actions after the message is shown. Use this to perform actions after the message is shown.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message sender.
nick: The nickname of the message sender. :param message: The displayed message.
message: The displayed message. :return: None
Returns: Example::
None
Example:
::
def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Displayed in {barejid} from {nick}: {message}") prof.cons_show(f"Displayed in {barejid} from {nick}: {message}")
@@ -278,16 +217,11 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
Allows the plugin to modify or cancel the message. Allows the plugin to modify or cancel the message.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param message: The message to be sent.
message: The message to be sent. :return: The modified message to send, or None to cancel sending.
Returns: Example::
str | None: The modified message to send, or None to cancel sending.
Example:
::
def prof_pre_room_message_send(barejid: str, message: str) -> str | None: def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
return f"{message} (sent by plugin)" return f"{message} (sent by plugin)"
@@ -299,16 +233,11 @@ def prof_post_room_message_send(barejid: str, message: str) -> None:
Use this to log or react to sent messages. Use this to log or react to sent messages.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param message: The sent message.
message: The sent message. :return: None
Returns: Example::
None
Example:
::
def prof_post_room_message_send(barejid: str, message: str) -> None: def prof_post_room_message_send(barejid: str, message: str) -> None:
prof.cons_show(f"Sent to {barejid}: {message}") prof.cons_show(f"Sent to {barejid}: {message}")
@@ -318,18 +247,13 @@ def prof_post_room_message_send(barejid: str, message: str) -> None:
def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None: def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
"""Called when a chat room history message is received from the server. """Called when a chat room history message is received from the server.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message sender.
nick: The nickname of the message sender. :param message: The received message.
message: The received message. :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). :return: None
Returns: Example::
None
Example:
::
def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None: def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}") prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}")
@@ -344,17 +268,12 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str
Allows the plugin to modify or cancel the message display. Allows the plugin to modify or cancel the message display.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message sender.
nick: The nickname of the message sender. :param message: The received message.
message: The received message. :return: The modified message to display, or None to preserve the original.
Returns: Example::
str | None: The modified message to display, or None to preserve the original.
Example:
::
def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (private from {nick})" return f"{message} (private from {nick})"
@@ -366,17 +285,12 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non
Use this to perform actions after the message is shown. Use this to perform actions after the message is shown.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message sender.
nick: The nickname of the message sender. :param message: The displayed message.
message: The displayed message. :return: None
Returns: Example::
None
Example:
::
def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None: def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}") prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}")
@@ -388,17 +302,12 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N
Allows the plugin to modify or cancel the message. Allows the plugin to modify or cancel the message.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message recipient.
nick: The nickname of the message recipient. :param message: The message to be sent.
message: The message to be sent. :return: The modified message to send, or None to cancel sending.
Returns: Example::
str | None: The modified message to send, or None to cancel sending.
Example:
::
def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (private to {nick})" return f"{message} (private to {nick})"
@@ -410,17 +319,12 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
Use this to log or react to sent messages. Use this to log or react to sent messages.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param nick: The nickname of the message recipient.
nick: The nickname of the message recipient. :param message: The sent message.
message: The sent message. :return: None
Returns: Example::
None
Example:
::
def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Sent private to {nick} in {barejid}: {message}") prof.cons_show(f"Sent private to {nick} in {barejid}: {message}")
@@ -435,15 +339,10 @@ def prof_on_message_stanza_send(stanza: str) -> str | None:
Allows the plugin to modify or cancel the stanza. Allows the plugin to modify or cancel the stanza.
Args: :param stanza: The XMPP message stanza to send.
stanza: The XMPP message stanza to send. :return: The modified stanza to send, or None to preserve the original.
Returns: Example::
str | None: The modified stanza to send, or None to preserve the original.
Example:
::
def prof_on_message_stanza_send(stanza: str) -> str | None: def prof_on_message_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending message stanza: {stanza}") prof.cons_show(f"Sending message stanza: {stanza}")
@@ -456,15 +355,10 @@ def prof_on_message_stanza_receive(stanza: str) -> bool:
Allows the plugin to control whether CProof processes the stanza. Allows the plugin to control whether CProof processes the stanza.
Args: :param stanza: The received XMPP message stanza.
stanza: The received XMPP message stanza. :return: True to allow CProof to process the stanza, False to block processing.
Returns: Example::
bool: True to allow CProof to process the stanza, False to block processing.
Example:
::
def prof_on_message_stanza_receive(stanza: str) -> bool: def prof_on_message_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received message stanza: {stanza}") prof.cons_show(f"Received message stanza: {stanza}")
@@ -477,15 +371,10 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None:
Allows the plugin to modify or cancel the stanza. Allows the plugin to modify or cancel the stanza.
Args: :param stanza: The XMPP presence stanza to send.
stanza: The XMPP presence stanza to send. :return: The modified stanza to send, or None to preserve the original.
Returns: Example::
str | None: The modified stanza to send, or None to preserve the original.
Example:
::
def prof_on_presence_stanza_send(stanza: str) -> str | None: def prof_on_presence_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending presence stanza: {stanza}") prof.cons_show(f"Sending presence stanza: {stanza}")
@@ -498,15 +387,10 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool:
Allows the plugin to control whether CProof processes the stanza. Allows the plugin to control whether CProof processes the stanza.
Args: :param stanza: The received XMPP presence stanza.
stanza: The received XMPP presence stanza. :return: True to allow CProof to process the stanza, False to block processing.
Returns: Example::
bool: True to allow CProof to process the stanza, False to block processing.
Example:
::
def prof_on_presence_stanza_receive(stanza: str) -> bool: def prof_on_presence_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received presence stanza: {stanza}") prof.cons_show(f"Received presence stanza: {stanza}")
@@ -519,15 +403,10 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None:
Allows the plugin to modify or cancel the stanza. Allows the plugin to modify or cancel the stanza.
Args: :param stanza: The XMPP IQ stanza to send.
stanza: The XMPP IQ stanza to send. :return: The modified stanza to send, or None to preserve the original.
Returns: Example::
str | None: The modified stanza to send, or None to preserve the original.
Example:
::
def prof_on_iq_stanza_send(stanza: str) -> str | None: def prof_on_iq_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending IQ stanza: {stanza}") prof.cons_show(f"Sending IQ stanza: {stanza}")
@@ -540,15 +419,10 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool:
Allows the plugin to control whether CProof processes the stanza. Allows the plugin to control whether CProof processes the stanza.
Args: :param stanza: The received XMPP IQ stanza.
stanza: The received XMPP IQ stanza. :return: True to allow CProof to process the stanza, False to block processing.
Returns: Example::
bool: True to allow CProof to process the stanza, False to block processing.
Example:
::
def prof_on_iq_stanza_receive(stanza: str) -> bool: def prof_on_iq_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received IQ stanza: {stanza}") prof.cons_show(f"Received IQ stanza: {stanza}")
@@ -562,17 +436,12 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool:
def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
"""Called when a contact goes offline. """Called when a contact goes offline.
Args: :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :param resource: The resource being disconnected (e.g., ``laptop``).
resource: The resource being disconnected (e.g., ``laptop``). :param status: The status message received with the offline presence, or None.
status: The status message received with the offline presence, or None. :return: None
Returns: Example::
None
Example:
::
def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}") prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}")
@@ -582,19 +451,14 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) ->
def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
"""Called when a presence notification is received from a contact. """Called when a presence notification is received from a contact.
Args: :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :param resource: The resource of the contact (e.g., ``laptop``).
resource: The resource of the contact (e.g., ``laptop``). :param presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``).
presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``). :param status: The status message received with the presence, or None.
status: The status message received with the presence, or None. :param priority: The priority associated with the resource.
priority: The priority associated with the resource. :return: None
Returns: Example::
None
Example:
::
def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
prof.notify(f"{barejid} is {presence}", 5000, "Presence") prof.notify(f"{barejid} is {presence}", 5000, "Presence")
@@ -607,15 +471,10 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status:
def prof_on_chat_win_focus(barejid: str) -> None: def prof_on_chat_win_focus(barejid: str) -> None:
"""Called when a chat window is focused. """Called when a chat window is focused.
Args: :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). :return: None
Returns: Example::
None
Example:
::
def prof_on_chat_win_focus(barejid: str) -> None: def prof_on_chat_win_focus(barejid: str) -> None:
prof.cons_show(f"Focused chat window for {barejid}") prof.cons_show(f"Focused chat window for {barejid}")
@@ -625,15 +484,10 @@ def prof_on_chat_win_focus(barejid: str) -> None:
def prof_on_room_win_focus(barejid: str) -> None: def prof_on_room_win_focus(barejid: str) -> None:
"""Called when a chat room window is focused. """Called when a chat room window is focused.
Args: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :return: None
Returns: Example::
None
Example:
::
def prof_on_room_win_focus(barejid: str) -> None: def prof_on_room_win_focus(barejid: str) -> None:
prof.cons_show(f"Focused room window for {barejid}") prof.cons_show(f"Focused room window for {barejid}")

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

File diff suppressed because it is too large Load Diff