From 6b558de902037dda96e6e55aa8085a3b146de5e0 Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Tue, 23 Sep 2025 14:04:56 +0200 Subject: [PATCH] docs(apidocs/c): improve profapi.h and profhooks.h comments - 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 --- apidocs/c/profapi.h | 834 +++++++++++++++++++++++++++--------------- apidocs/c/profhooks.h | 295 ++++++++------- 2 files changed, 706 insertions(+), 423 deletions(-) diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h index c6de34a8..5042c4ed 100644 --- a/apidocs/c/profapi.h +++ b/apidocs/c/profapi.h @@ -1,470 +1,726 @@ -/** @file -C plugin API. -*/ + /** @file profapi.h + * @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 -List of all API function available to plugins: {@link profapi.h} +/** @mainpage CProof Plugin API and Hooks + * API functions: @ref profapi.h + * Hooks: @ref profhooks.h + */ -List of all hooks which plugins may implement: {@link profhooks.h} -*/ - -/** Type representing a window, used for referencing windows created by the plugin */ +/** Window handle for referencing plugin-created windows. */ 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); -/** Type representing a function pointer to a timed callback */ +/** Function pointer for timed callbacks, accepting no arguments. */ 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); -/** Highlights the console window in the status bar. */ +/** Highlights the console window in the status bar. */ void prof_cons_alert(void); /** -Show a message in the console window. -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in the console window. + * @param message The message to print. + * @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); /** -Show a message in the console, using the specified theme. -Themes are specified in ~/.local/share/profanity/plugin_themes -@param group the group name in the themes file -@param item the item name within the group -@param def default colour if the theme cannot be found -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in the console with a specified theme. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param group The group name in the themes file. + * @param item The item name within the group. + * @param def Default color if theme is not found. + * @param message The message to print. + * @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); /** -Show a message indicating the command has been called incorrectly. -@param cmd the command name with leading slash, e.g. "/say" -@return 1 on success, 0 on failure -*/ + * Shows a message indicating a command was used incorrectly. + * @param cmd The command name with leading slash (e.g., "/say"). + * @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); /** -Register a new command, with help information, and callback for command execution. -Profanity will do some basic validation when the command is called using the argument range. -@param command_name the command name with leading slash, e.g. "/say" -@param min_args minimum number or arguments that the command considers to be a valid call -@param max_args maximum number or arguments that the command considers to be a valid call -@param synopsis command usages -@param description a short description of the command -@param arguments argument descriptions -@param examples example usages -@param callback The {@link CMD_CB} function to execute when the command is invoked -*/ + * Registers a new command with help information and callback. + * CProof validates arguments using the specified range. + * @param command_name The command name with leading slash (e.g., "/say"). + * @param min_args Minimum number of valid arguments. + * @param max_args Maximum number of valid arguments. + * @param synopsis Command usage strings. + * @param description Short command description. + * @param arguments Argument descriptions as [arg, desc] pairs. + * @param examples Example usage strings. + * @param callback The @ref CMD_CB function to invoke. + * + * Example: + * @code + * char *synopsis[] = { "/newcommand action1|action2", "/newcommand print " }; + * char *args[][2] = { { "action1|action2", "Perform action" }, { "print ", "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, char **synopsis, const char *description, char *arguments[][2], char **examples, CMD_CB callback); /** -Register a function that Profanity will call periodically. -@param callback The {@link TIMED_CB} function to execute -@param interval_seconds the time between each call to the function, in seconds -*/ + * Registers a function to be called periodically by CProof. + * @param callback The @ref TIMED_CB function to execute. + * @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); /** -Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key. -@param key the prefix to trigger autocompletion -@param items the items to return on autocompletion -*/ + * Adds autocomplete values for a command or argument. + * @param key The prefix to trigger 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); /** -Remove values from autocompletion for a command, or command argument. - -@param key the prefix from which to remove the autocompletion items -@param items the items to remove -*/ + * Removes autocomplete values for a command or argument. + * @param key The prefix to remove items from. + * @param items Items to remove. + * + * Example: + * @code + * char *items[] = { "action1", NULL }; + * prof_completer_remove("/mycommand", items); + * @endcode + */ void prof_completer_remove(const char *key, char **items); /** -Remove all values from autocompletion for a command, or command argument. - -@param key the prefix from which to clear the autocompletion items -*/ + * Clears all autocomplete values for a command or argument. + * @param key The prefix to clear. + * + * Example: + * @code + * prof_completer_clear("/mycommand"); + * @endcode + */ void prof_completer_clear(const char *key); /** -Add filepath autocompletion for a command, or command argument. - -@param prefix the prefix from which filepath autocompletion will be triggered -*/ + * Adds filepath autocompletion for a command or argument. + * @param prefix The prefix to trigger filepath autocompletion. + * + * Example: + * @code + * prof_filepath_completer_add("/filecmd"); + * @endcode + */ void prof_filepath_completer_add(const char *prefix); /** -Send a desktop notification. -@param message the message to display in the notification -@param timeout_ms the length of time before the notification disappears in milliseconds -@param category the category of the notification, also displayed -*/ + * Sends a desktop notification. + * @param message The message to display. + * @param timeout_ms Duration before the notification disappears (milliseconds). + * @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); /** -Send a line of input to Profanity to execute. -@param line the line to send -*/ + * Sends a line of input to CProof to execute. + * @param line The command line to send. + * + * Example: + * @code + * prof_send_line("/who online"); + * @endcode + */ void prof_send_line(char *line); /** -Retrieve the Jabber ID of the current chat recipient, when in a chat window. -@return the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window. -*/ + * Gets the Jabber ID of the current chat recipient. + * @return The Jabber ID (e.g., "buddy@example.com") or NULL if not in a chat window. + */ char* prof_get_current_recipient(void); /** -Retrieve the Jabber ID of the current room, when in a chat room window. -@return the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window. -*/ + * Gets the Jabber ID of the current chat room. + * @return The room Jabber ID (e.g., "metalchat@conference.example.com") or NULL if not in a room. + */ char* prof_get_current_muc(void); /** -Determine whether or not the Console window is currently focused. -@return 1 if the user is currently in the Console window, 0 otherwise. -*/ + * Checks if the console window is currently focused. + * @return 1 if in the console window, 0 otherwise. + */ int prof_current_win_is_console(void); /** -Retrieve the users nickname in a chat room, when in a chat room window. -@return the users nickname in the current chat room e.g. "eddie", or NULL if not in a chat room window. -*/ + * Gets the user’s nickname in the current chat room. + * @return The nickname (e.g., "eddie") or NULL if not in a room. + */ char* prof_get_current_nick(void); /** -Retrieve the nickname for a given barejid if it is in the roster. -@return the users nickname e.g. "eddie", or the input barejid if it is not in the roster. -*/ + * Gets the nickname for a barejid from 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); /** -Retrieve the barejid for a given nickname if it is in the roster. -@return the users barejid e.g. "eddie@server.tld", or NULL if the nickname is not in the roster. -*/ + * Gets the barejid for a nickname from 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); /** -Retrieve nicknames of all occupants in a chat room, when in a chat room window. -@return nicknames of all occupants in the current room or an empty list if not in a chat room window. -*/ + * Gets nicknames of all occupants in the current chat room. + * @return List of nicknames or an empty list if not in a room. + */ char** prof_get_current_occupants(void); /** -Retrieve current nickname used in chat room. -@param barejid The room's Jabber ID -@return Room nickname. -*/ + * Gets the current nickname in a chat room. + * @param barejid The room’s Jabber ID. + * @return The nickname. + */ char* prof_get_room_nick(const char *barejid); /** -Write to the Profanity log at level DEBUG. -@param message The message to log -*/ + * Logs a debug message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_debug("Debug message"); + * @endcode + */ void prof_log_debug(const char *message); /** -Write to the Profanity log at level INFO. -@param message The message to log -*/ + * Logs an info message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_info("Info message"); + * @endcode + */ void prof_log_info(const char *message); /** -Write to the Profanity log at level WARNING. -@param message The message to log -*/ + * Logs a warning message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_warning("Warning message"); + * @endcode + */ void prof_log_warning(const char *message); /** -Write to the Profanity log at level ERROR. -@param message The message to log -*/ + * Logs an error message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_error("Error message"); + * @endcode + */ void prof_log_error(const char *message); /** -Create a plugin window. -@param win The {@link PROF_WIN_TAG} used to refer to the window -@param input_handler The WINDOW_CB function to call when the window receives input -*/ + * Creates a plugin window. + * @param win The @ref PROF_WIN_TAG to refer to the window. + * @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); /** -Determine whether or not a plugin window currently exists for {@link PROF_WIN_TAG}. -@param win the {@link PROF_WIN_TAG} used when creating the plugin window -@return 1 if the window exists, 0 otherwise -*/ + * Checks if a plugin window exists. + * @param win The @ref PROF_WIN_TAG of the window. + * @return 1 if the window exists, 0 otherwise. + * + * Example: + * @code + * prof_win_exists("My Plugin"); + * @endcode + */ int prof_win_exists(PROF_WIN_TAG win); /** -Focus plugin window. -@param win the {@link PROF_WIN_TAG} of the window to focus -@return 1 on success, 0 on failure -*/ + * Focuses a plugin window. + * @param win The @ref PROF_WIN_TAG of the window. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_win_focus("My Plugin"); + * @endcode + */ int prof_win_focus(PROF_WIN_TAG win); /** -Show a message in the plugin window. -@param win the {@link PROF_WIN_TAG} of the window to display the message -@param message The message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a plugin window. + * @param win The @ref PROF_WIN_TAG of the window. + * @param message The message to print. + * @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); /** -Show a message in the plugin window, using the specified theme. -Themes are specified in ~/.local/share/profanity/plugin_themes -@param tag The {@link PROF_WIN_TAG} of the window to display the message -@param group the group name in the themes file -@param key the item name within the group -@param def default colour if the theme cannot be found or NULL -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a plugin window with a specified theme. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param tag The @ref PROF_WIN_TAG of the window. + * @param group The group name in the themes file. + * @param key The item name within the group. + * @param def Default color if theme is not found or NULL. + * @param message The message to print. + * @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); /** -Send an XMPP stanza -@param stanza an XMPP stanza -@return 1 if the stanza was sent successfully, 0 otherwise -*/ + * Sends an XMPP stanza. + * @param stanza The XMPP stanza to send. + * @return 1 if sent successfully, 0 otherwise. + * + * Example: + * @code + * prof_send_stanza(""); + * @endcode + */ int prof_send_stanza(char *stanza); /** -Get a boolean setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets a boolean setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @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); /** -Set a boolean setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets a boolean setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value 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); /** -Get a string setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets a string setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @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); /** -Set a string setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets a string setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value 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); /** -Get a string list setting -Settings must be specified 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 key the item name within the group -@return the list setting -*/ + * Gets a string list setting, separated by semicolons. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @return The list setting. + * + * Example: + * @code + * prof_settings_string_list_get("myplugin", "somelist"); + * @endcode + */ char** prof_settings_string_list_get(char *group, char *key); /** -Add an item to a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -If the list does not exist, a new one will be created with the element added -@param group the group name in the settings file -@param key the item name within the group -@param value item to add -*/ + * Adds an item to a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * Creates a new list if none exists. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @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); /** -Remove an item from a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value item to remove -@return 1 if the item was removed, or is not in the list, 0 if the list does not exist -*/ + * Removes an item from a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The item to remove. + * @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); /** -Remove all items from a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@return 1 if the list was cleared, 0 if the list does not exist -*/ + * Clears all items from a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @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); /** -Get an integer setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets an integer setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @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); /** -Set an integer setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets an integer setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value 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); /** -Trigger incoming message handling, this plugin will make profanity act as if the message has been received -@param barejid Jabber ID of the sender of the message -@param resource resource of the sender of the message -@param message the message text -*/ + * Triggers handling of an incoming message as if received by CProof. + * @param barejid Jabber ID of the sender. + * @param resource Resource of the sender. + * @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); /** -Add a service discovery feature the list supported by Profanity. -If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity -@param feature the service discovery feature to be added -*/ + * Adds a service discovery feature to CProof’s supported features. + * Sends a presence update if a session is connected. + * @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); /** -End any encrypted session with the specified user. -@param barejid Jabber ID of the recipient -*/ + * Ends an encrypted session with a user. + * @param barejid Jabber ID of the recipient. + * + * Example: + * @code + * prof_encryption_reset("alice@server.org"); + * @endcode + */ void prof_encryption_reset(char *barejid); /** -Set the text to display in the titlebar encryption indicator for recipient. -@param barejid Jabber ID of the recipient -@param enctext The text to display -@return 1 on success, 0 on failure -*/ + * Sets the titlebar encryption indicator text for a recipient. + * @param barejid Jabber ID of the recipient. + * @param enctext The text to display. + * @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); /** -Let profanity decide what to show in the titlebar encryption indicator for recipient. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the titlebar encryption indicator for a recipient to CProof’s default. + * @param barejid Jabber ID of the recipient. + * @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); /** -Set the incoming message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the incoming message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @param ch The character to display. + * @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); /** -Reset the incoming message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the incoming message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @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); /** -Set the outgoing message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the outgoing message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @param ch The character to display. + * @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); /** -Reset the outgoing message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the outgoing message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @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); /** -Set the text to display in the titlebar encryption indicator for room. -@param roomjid Jabber ID of the room -@param enctext The text to display -@return 1 on success, 0 on failure -*/ + * Sets the titlebar encryption indicator text for a room. + * @param roomjid Jabber ID of the room. + * @param enctext The text to display. + * @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); /** -Let profanity decide what to show in the titlebar encryption indicator for room. -@param roomjid Jabber ID of the room -@return 1 on success, 0 on failure -*/ + * Resets the titlebar encryption indicator for a room to CProof’s default. + * @param roomjid Jabber ID of the room. + * @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); /** -Set the message prefix character for specified room. -@param roomjid Jabber ID of the room -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the message prefix character for a room. + * @param roomjid Jabber ID of the room. + * @param ch The character to display. + * @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); /** -Reset the message prefix character for specified room. -@param roomjid Jabber ID of the room -@return 1 on success, 0 on failure -*/ + * Resets the message prefix character for a room. + * @param roomjid Jabber ID of the room. + * @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); /** -Show a message in a chat window. -@param barejid Jabber ID of the recipient -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat window. + * @param barejid Jabber ID of the recipient. + * @param message The message to print. + * @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); /** -Show a message in a chat window, using the specified theme, and prefix character -Themes are specified in ~/.local/share/profanity/plugin_themes -@param barejid Jabber ID of the recipient -@param group the group name in the themes file or NULL -@param item the item name within the group or NULL -@param def default colour if the theme cannot be found -@param ch The character to prefix the message, or NULL for default behaviour -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat window with a theme and prefix character. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param barejid Jabber ID of the recipient. + * @param group The group name in the themes file or NULL. + * @param item The item name within the group or NULL. + * @param def Default color if theme is not found. + * @param ch The prefix character or NULL for default. + * @param message The message to print. + * @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); /** -Show a message in a chat room window. -@param roomjid Jabber ID of the room -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat room window. + * @param roomjid Jabber ID of the room. + * @param message The message to print. + * @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); /** -Show a message in a chat room window, using the specified theme, and prefix character -Themes are specified in ~/.local/share/profanity/plugin_themes -@param roomjid Jabber ID of the room -@param group the group name in the themes file or NULL -@param item the item name within the group or NULL -@param def default colour if the theme cannot be found -@param ch The character to prefix the message, or NULL for default behaviour -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat room window with a theme and prefix character. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param roomjid Jabber ID of the room. + * @param group The group name in the themes file or NULL. + * @param item The item name within the group or NULL. + * @param def Default color if theme is not found. + * @param ch The prefix character or NULL for default. + * @param message The message to print. + * @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); diff --git a/apidocs/c/profhooks.h b/apidocs/c/profhooks.h index c789454d..29725ad7 100644 --- a/apidocs/c/profhooks.h +++ b/apidocs/c/profhooks.h @@ -1,220 +1,247 @@ -/** @file -C Hooks. -*/ +/** @file profhooks.h + * @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 -@param version the version of Profanity -@param status the package status of Profanity, "development" or "release" -@param account_name account name of the currently logged in account, or NULL if not logged in -@param fulljid the users full Jabber ID (barejid and resource) if logged in, NULL otherwise -*/ + * 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 CProof + * @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 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); /** -Called when Profanity is started -*/ + * Called when CProof is started + */ void prof_on_start(void); /** -Called when the user quits Profanity -*/ + * Called when the user quits CProof + */ 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); /** -Called when the user connects with an account -@param account_name account name of the account used for logging in -@param fulljid the full Jabber ID (barejid and resource) of the account -*/ + * Called when the user connects with an account + * @param account_name Account name of the account used for logging in + * @param fulljid The full Jabber ID (barejid and resource) of the account + */ void prof_on_connect(const char * const account_name, const char * const fulljid); /** -Called when the user disconnects an account -@param account_name account name of the account being disconnected -@param fulljid the full Jabber ID (barejid and resource) of the account -*/ + * Called when the user disconnects an account + * @param account_name Account name of the account being disconnected + * @param fulljid The full Jabber ID (barejid and resource) of the account + */ void prof_on_disconnect(const char * const account_name, const char * const fulljid); /** -Called before a chat message is displayed -@param barejid Jabber ID of the message sender -@param resource resource of the message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a chat message is displayed + * @param barejid Jabber ID of the message sender + * @param resource Resource of the message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_chat_message_display(const char * const barejid, const char *const resource, const char *message); /** -Called after a chat message is displayed -@param barejid Jabber ID of the message sender -@param resource resource of the message sender -@param message the received message -*/ + * Called after a chat message is displayed + * @param barejid Jabber ID of the message sender + * @param resource Resource of the message sender + * @param message The received 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 -@param barejid Jabber ID of the message recipient -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a chat message is sent + * @param barejid Jabber ID of the message recipient + * @param message The message to be sent + * @return The 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); /** -Called after a chat message has been sent -@param barejid Jabber ID of the message recipient -@param message the sent message -*/ + * Called after a chat message has been sent + * @param barejid Jabber ID of the message recipient + * @param message The sent message + */ void prof_post_chat_message_send(const char * const barejid, const char *message); /** -Called before a chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_room_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called after a chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the received message -*/ + * Called after a chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The received message + */ void prof_post_room_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called before a chat room message is sent -@param barejid Jabber ID of the room -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a chat room message is sent + * @param barejid Jabber ID of the room + * @param message The message to be sent + * @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); /** -Called after a chat room message has been sent -@param barejid Jabber ID of the room -@param message the sent message -*/ + * Called after a chat room message has been sent + * @param barejid Jabber ID of the room + * @param message The sent message + */ void prof_post_room_message_send(const char * const barejid, const char *message); /** -Called when the server sends a chat room history message -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the message to be sent -@param timestamp time the message was originally sent to the room, in ISO8601 format -*/ + * Called when the server sends a chat room history message + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The message to be sent + * @param timestamp Time the message was originally sent to the room, in ISO8601 format + */ void prof_on_room_history_message(const char * const barejid, const char *const nick, const char *const message, const char *const timestamp); /** -Called before a private chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a private chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_priv_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called after a private chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the received message -*/ + * Called after a private chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The received message + */ void prof_post_priv_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called before a private chat room message is sent -@param barejid Jabber ID of the room -@param nick nickname of message recipient -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a private chat room message is sent + * @param barejid Jabber ID of the room + * @param nick Nickname of message recipient + * @param message The message to be sent + * @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); /** -Called after a private chat room message has been sent -@param barejid Jabber ID of the room -@param nick nickname of the message recipient -@param message the sent message -*/ + * Called after a private chat room message has been sent + * @param barejid Jabber ID of the room + * @param nick Nickname of the message recipient + * @param message The sent message + */ void prof_post_priv_message_send(const char * const barejid, const char * const nick, const char *message); /** -Called before an XMPP message stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP message stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_message_stanza_send(const char *const stanza); /** -Called when an XMPP message stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the message stanza, 0 otherwise -*/ + * Called when an XMPP message stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the message stanza, 0 otherwise + */ int prof_on_message_stanza_receive(const char *const stanza); /** -Called before an XMPP presence stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP presence stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_presence_stanza_send(const char *const stanza); /** -Called when an XMPP presence stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the presence stanza, 0 otherwise -*/ + * Called when an XMPP presence stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the presence stanza, 0 otherwise + */ int prof_on_presence_stanza_receive(const char *const stanza); /** -Called before an XMPP iq stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP iq stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_iq_stanza_send(const char *const stanza); /** -Called when an XMPP iq stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the iq stanza, 0 otherwise -*/ + * Called when an XMPP iq stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the iq stanza, 0 otherwise + */ int prof_on_iq_stanza_receive(const char *const stanza); /** -Called when a contact goes offline -@param barejid Jabber ID of the contact -@param resource the resource being disconnected -@param status the status message received with the offline presence, or NULL -*/ + * Called when a contact goes offline + * @param barejid Jabber ID of the contact + * @param resource The resource being disconnected + * @param status The status message received with the offline presence, or NULL + */ void prof_on_contact_offline(const char *const barejid, const char *const resource, const char *const status); /** -Called when a presence notification is received from a contact -@param barejid Jabber ID of the contact -@param resource the resource being disconnected -@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd" -@param status the status message received with the presence, or NULL -@param priority the priority associated with the resource -*/ + * Called when a presence notification is received from a contact + * @param barejid Jabber ID of the contact + * @param resource The resource being disconnected + * @param presence Presence of the contact, one of "chat", "online", "away", "xa" or "dnd" + * @param status The status message received with the presence, or NULL + * @param priority The priority associated with the resource + */ void prof_on_contact_presence(const char *const barejid, const char *const resource, const char *const presence, const char *const status, const int priority); /** -Called when a chat window is focused -@param barejid Jabber ID of the chat window recipient -*/ + * Called when a chat window is focused + * @param barejid Jabber ID of the chat window recipient + */ void prof_on_chat_win_focus(const char *const barejid); /** -Called when a chat room window is focused -@param barejid Jabber ID of the room -*/ -void prof_on_room_win_focus(const char *const barejid); + * Called when a chat room window is focused + * @param barejid Jabber ID of the room + */ +void prof_on_room_win_focus(const char *const barejid); \ No newline at end of file