devs/profanity
2
0
Fork 0
mirror of https://git.jabber.space/devs/cproof.git synced 2026-07-31 20:56:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(apidocs/c): improve profapi.h and profhooks.h comments

Browse Source 
- Enhanced file-level comments with concise descriptions
- Added usage examples and aligned with Python prof module style
- Updated function comments to remove tables, improve clarity
- Replaced Profanity with CProof, preserved paths and method names
This commit is contained in:
Jabber Developer
2025-09-23 14:04:56 +02:00
parent 8849d9b79e
commit 40dd773c6a
2 changed files with 702 additions and 424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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);