profanity/apidocs/c/profapi.h

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

/** Window handle for referencing plugin-created windows. */
typedef char* PROF_WIN_TAG;

/** Function pointer for command callbacks, accepting an array of arguments. */
typedef void (*CMD_CB)(char** args);

/** Function pointer for timed callbacks, accepting no arguments. */
typedef void (*TIMED_CB)(void);

/** 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. */
void prof_cons_alert(void);

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

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

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

/**
 * 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 <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,
                           char** synopsis, const char* description, char* arguments[][2], char** examples,
                           CMD_CB callback);

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

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

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

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

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

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

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

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

/**
 * Gets the title of the current window as shown in the titlebar.
 *
 * Special cases:
 * - MUC configuration window: Includes "config" and an asterisk if modified (e.g., "room@example.com config *").
 * - vCard window: Includes the bare JID and an asterisk if modified (e.g., "vCard user@example.com *").
 *
 * @return A null-terminated string containing the window title. The caller must free the returned string.
 */
char* prof_get_current_window(void);

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

/**
 * Checks if the console window is currently focused.
 * @return 1 if in the console window, 0 otherwise.
 */
int prof_current_win_is_console(void);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * Sends an XMPP stanza.
 * @param stanza The XMPP stanza to send.
 * @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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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