Update plugins API docs

2 files changed, 183 insertions, 98 deletions

diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h
index 7047b2cd..257c2799 100644
--- a/apidocs/c/profapi.h
+++ b/apidocs/c/profapi.h
@@ -11,9 +11,7 @@ List of all hooks which plugins may implement: {@link profhooks.h}
 /** Type representing a window, used for referencing windows created by the plugin */
 typedef char* PROF_WIN_TAG;
 
-/** Type representing a function pointer to a command callback
-@param args The arguments passed to the callback
-*/
+/** Type representing a function pointer to a command callback */
 typedef void(*CMD_CB)(char **args);
 
 /** Type representing a function pointer to a timed callback */
@@ -22,16 +20,15 @@ typedef void(*TIMED_CB)(void);
 /** Type representing a function pointer to a window callback */
 typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line);
 
-
 /**	Highlights the console window in the status bar. */
-void prof_cons_alert)(void);
+void prof_cons_alert(void);
 
 /**	
 Show a message in the console window.
 @param message the message to print
 @return 1 on success, 0 on failure
 */
-int (*prof_cons_show)(const char * const message);
+int prof_cons_show(const char * const message);
 
 /**	
 Show a message in the console, using the specified theme.
@@ -42,14 +39,14 @@ Themes can be must be specified in ~/.local/share/profanity/plugin_themes
 @param message the message to print 
 @return 1 on success, 0 on failure
 */
-int (*prof_cons_show_themed)(const char *const group, const char *const item, const char *const def, const char *const message);
+int prof_cons_show_themed(const char *const group, const char *const item, const char *const def, const char *const message);
 
 /**	
 Show a message indicating the command has been called incorrectly.
 @param cmd the command name with leading slash, e.g. "/say" 
 @return 1 on success, 0 on failure
 */
-int (*prof_cons_bad_cmd_usage)(const char *const cmd);
+int prof_cons_bad_cmd_usage(const char *const cmd);
 
 /**
 Register a new command, with help information, and callback for command execution.
@@ -63,7 +60,7 @@ Profanity will do some basic validation when the command is called using the arg
 @param examples example usages
 @param callback The {@link CMD_CB} function to execute when the command is invoked
 */
-void (*_prof_register_command)(const char *filename, const char *command_name, int min_args, int max_args,
+void prof_register_command(const char *command_name, int min_args, int max_args,
     char **synopsis, const char *description, char *arguments[][2], char **examples,
     CMD_CB callback);
 
@@ -72,14 +69,14 @@ Register a function that Profanity will call periodically.
 @param callback The {@link TIMED_CB} function to execute
 @param interval_seconds the time between each call to the function, in seconds
 */
-void (*_prof_register_timed)(const char *filename, TIMED_CB callback, int interval_seconds);
+void prof_register_timed(TIMED_CB callback, int interval_seconds);
 
 /**
 Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key.
 @param key the prefix to trigger autocompletion
 @param items the items to return on autocompletion
 */
-void (*_prof_completer_add)(const char *filename, const char *key, char **items);
+void prof_completer_add(const char *key, char **items);
 
 /**
 Remove values from autocompletion for a command, or command argument.
@@ -87,7 +84,7 @@ Remove values from autocompletion for a command, or command argument.
 @param key the prefix from which to remove the autocompletion items
 @param items the items to remove
 */
-void (*_prof_completer_remove)(const char *filename, const char *key, char **items);
+void prof_completer_remove(const char *key, char **items);
 
 /**
 Remove all values from autocompletion for a command, or command argument.
@@ -95,7 +92,7 @@ Remove all values from autocompletion for a command, or command argument.
 @param key the prefix from which to clear the autocompletion items
 @param items the items to remove
 */
-void (*_prof_completer_clear)(const char *filename, const char *key);
+void prof_completer_clear(const char *key);
 
 /**
 Send a desktop notification.
@@ -103,88 +100,88 @@ Send a desktop notification.
 @param timeout_ms the length of time before the notification disappears in milliseconds
 @param category the category of the notification, also displayed
 */
-void (*prof_notify)(const char *message, int timeout_ms, const char *category);
+void prof_notify(const char *message, int timeout_ms, const char *category);
 
 /**
 Send a line of input to Profanity to execute.
 @param line the line to send
 */
-void (*prof_send_line)(char *line);
+void prof_send_line(char *line);
 
 /**
 Retrieve the Jabber ID of the current chat recipient, when in a chat window.
 @return the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window.
 */
-char* (*prof_get_current_recipient)(void);
+char* prof_get_current_recipient(void);
 
 /**
 Retrieve the Jabber ID of the current room, when in a chat room window.
 @return the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window.
 */
-char* (*prof_get_current_muc)(void);
+char* prof_get_current_muc(void);
 
 /**
 Determine whether or not the Console window is currently focussed.
 @return 1 if the user is currently in the Console window, 0 otherwise.
 */
-int (*prof_current_win_is_console)(void);
+int prof_current_win_is_console(void);
 
 /**
 Retrieve the users nickname in a chat room, when in a chat room window.
 @return the users nickname in the current chat room e.g. "eddie", or NULLL if not in a chat room window.
 */
-char* (*prof_get_current_nick)(void);
+char* prof_get_current_nick(void);
 
 /**
 Retrieve nicknames of all occupants in a chat room, when in a chat room window.
 @return nicknames of all occupants in the current room or an empty list if not in a chat room window.
 */
-char** (*prof_get_current_occupants)(void);
+char** prof_get_current_occupants(void);
 
 /**
 Write to the Profanity log at level DEBUG.
 @param message The message to log
 */
-void (*prof_log_debug)(const char *message);
+void prof_log_debug(const char *message);
 
 /**
 Write to the Profanity log at level INFO.
 @param message The message to log
 */
-void (*prof_log_info)(const char *message);
+void prof_log_info(const char *message);
 
 /**
 Write to the Profanity log at level WARNING.
 @param message The message to log
 */
-void (*prof_log_warning)(const char *message);
+void prof_log_warning(const char *message);
 
 /**
 Write to the Profanity log at level ERROR.
 @param message The message to log
 */
-void (*prof_log_error)(const char *message);
+void prof_log_error(const char *message);
 
 /**
 Create a plugin window.
 @param win The {@link PROF_WIN_TAG} used to refer to the window
 @param input_handler The WINDOW_CB function to call when the window receives input
 */
-void (*_prof_win_create)(const char *filename, PROF_WIN_TAG win, WINDOW_CB input_handler);
+void prof_win_create(PROF_WIN_TAG win, WINDOW_CB input_handler);
 
 /**
 Determine whether or not a plugin window currently exists for {@link PROF_WIN_TAG}.
 @param win the {@link PROF_WIN_TAG} used when creating the plugin window
 @return 1 if the window exists, 0 otherwise
 */
-int (*prof_win_exists)(PROF_WIN_TAG win);
+int prof_win_exists(PROF_WIN_TAG win);
 
 /**
 Focus plugin window.
 @param win the {@link PROF_WIN_TAG} of the window to focus
 @return 1 on success, 0 on failure
 */
-int (*prof_win_focus)(PROF_WIN_TAG win);
+int prof_win_focus(PROF_WIN_TAG win);
 
 /**
 Show a message in the plugin window.
@@ -192,7 +189,7 @@ Show a message in the plugin window.
 @param line The message to print
 @return 1 on success, 0 on failure
 */
-int (*prof_win_show)(PROF_WIN_TAG win, char *line);
+int prof_win_show(PROF_WIN_TAG win, char *line);
 
 /**	
 Show a message in the plugin window, using the specified theme.
@@ -204,14 +201,14 @@ Themes must be specified in ~/.local/share/profanity/plugin_themes
 @param message the message to print 
 @return 1 on success, 0 on failure
 */
-int (*prof_win_show_themed)(PROF_WIN_TAG tag, char *group, char *key, char *def, char *line);
+int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *line);
 
 /**
 Send an XMPP stanza
 @param stanza an XMPP stanza
 @return 1 if the stanza was sent successfully, 0 otherwise
 */
-int (*prof_send_stanza)(char *stanza);
+int prof_send_stanza(char *stanza);
 
 /**
 Get a boolean setting
@@ -221,7 +218,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param def default value if setting not found
 @return the setting, or default value
 */
-int (*prof_settings_get_boolean)(char *group, char *key, int def);
+int prof_settings_get_boolean(char *group, char *key, int def);
 
 /**
 Set a boolean setting
@@ -230,7 +227,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param key the item name within the group
 @param value value to set
 */
-void (*prof_settings_set_boolean)(char *group, char *key, int value);
+void prof_settings_set_boolean(char *group, char *key, int value);
 
 /**
 Get a string setting
@@ -240,7 +237,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param def default value if setting not found
 @return the setting, or default value
 */
-char* (*prof_settings_get_string)(char *group, char *key, char *def);
+char* prof_settings_get_string(char *group, char *key, char *def);
 
 /**
 Set a string setting
@@ -249,7 +246,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param key the item name within the group
 @param value value to set
 */
-void (*prof_settings_set_string)(char *group, char *key, char *value);
+void prof_settings_set_string(char *group, char *key, char *value);
 
 /**
 Get an integer setting
@@ -259,7 +256,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param def default value if setting not found
 @return the setting, or default value
 */
-int (*prof_settings_get_int)(char *group, char *key, int def);
+int prof_settings_get_int(char *group, char *key, int def);
 
 /**
 Set an integer setting
@@ -268,7 +265,7 @@ Settings must be specified in ~/.local/share/profanity/plugin_settings
 @param key the item name within the group
 @param value value to set
 */
-void (*prof_settings_set_int)(char *group, char *key, int value);
+void prof_settings_set_int(char *group, char *key, int value);
 
 /**
 Trigger incoming message handling, this plugin will make profanity act as if the message has been received
@@ -276,11 +273,11 @@ Trigger incoming message handling, this plugin will make profanity act as if the
 @param resource resource of the sender of the message
 @param message the message text
 */
-void (*prof_incoming_message)(char *barejid, char *resource, char *message);
+void prof_incoming_message(char *barejid, char *resource, char *message);
 
 /**
 Add a service discovery feature the list supported by Profanity.
 If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity
 @param feature the service discovery feature to be added
 */
-void (*prof_disco_add_feature)(char *feature);
+void prof_disco_add_feature(char *feature);
diff --git a/apidocs/c/profhooks.h b/apidocs/c/profhooks.h
index 039abacc..78f77291 100644
--- a/apidocs/c/profhooks.h
+++ b/apidocs/c/profhooks.h
@@ -3,128 +3,216 @@ C Hooks.
 */
 
 /**
-Called when profanity loads the plugin
-@param version The version of profanity as a string e.g. "0.5.0"
-@param status The build status, either "development" or "release"
+Called when a plugin is loaded, either when profanity is started, or when the /plugins load or /plugins install commands are called
+@param version the version of Profanity
+@param status the package status of Profanity, "development" or "release"
+@param account_name account name of the currently logged in account, or NULL if not logged in
+@param fulljid the users full Jabber ID (barejid and resource) if logged in, NULL otherwise
 */
-void prof_init(const char * const version, const char * const status);
+void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid);
 
 /**
-Called when profanity starts, after {@link prof_init}
+Called when Profanity is started
 */
 void prof_on_start(void);
 
 /**
-Called when profanity shuts down
+Called when the user quits Profanity
 */
 void prof_on_shutdown(void);
 
 /**
-Called when an account is connected
-@param account_name The name of the account
-@param fulljid The full JID of the account
+Called when a plugin is unloaded with the /plugins unload command
+*/
+void prof_on_unload(void);
+
+/**
+Called when the user connects with an account
+@param account_name account name of the account used for logging in
+@param fulljid the full Jabber ID (barejid and resource) of the account
 */
 void prof_on_connect(const char * const account_name, const char * const fulljid);
 
 /**
-Called when an account is disconnected
-@param account_name The name of the account
-@param fulljid The full JID of the account
+Called when the user disconnects an account
+@param account_name account name of the account being disconnected
+@param fulljid the full Jabber ID (barejid and resource) of the account
 */
 void prof_on_disconnect(const char * const account_name, const char * const fulljid);
 
 /**
-Called before a regular chat message is displayed
-@param jid The JID of the sender
-@param message The message received
-@return The new message, or NULL if no change made to the message
+Called before a chat message is displayed
+@param barejid Jabber ID of the message sender
+@param message the received message
+@return the new message to display, or NULL to preserve the original message 
 */
 char* prof_pre_chat_message_display(const char * const jid, const char *message);
 
 /**
-Called after a regular chat message is displayed
-@param jid The JID of the sender
-@param message The message received
+Called after a chat message is displayed
+@param barejid Jabber ID of the message sender
+@param message the received message
 */
 void prof_post_chat_message_display(const char * const jid, const char *message);
 
 /**
-Called before a regular chat message is sent
-@param jid The JID of the recipient
-@param message The message to send
-@return The new message, or NULL if no change made to the message
+Called before a chat message is sent
+@param barejid Jabber ID of the message recipient
+@param message the message to be sent
+@return the new message to send, or NULL to preserve the original message 
 */
 char* prof_pre_chat_message_send(const char * const jid, const char *message);
 
 /**
-Called after a regular chat message is sent
-@param jid The JID of the recipient
-@param message The message sent
+Called after a chat message has been sent
+@param barejid Jabber ID of the message recipient
+@param message the sent message
 */
 void prof_post_chat_message_send(const char * const jid, const char *message);
 
 /**
-Called before a MUC message is displayed
-@param room The JID of the room
-@param nick The nickname of the sender
-@param message The message received
-@return The new message, or NULL if no change made to the message
+Called before a chat room message is displayed
+@param room Jabber ID of the room
+@param nick nickname of message sender
+@param message the received message
+@return the new message to display, or NULL to preserve the original message 
 */
 char* prof_pre_room_message_display(const char * const room, const char * const nick, const char *message);
 
 /**
-Called after a MUC message is displayed
-@param room The JID of the room
-@param nick The nickname of the sender
-@param message The message received
+Called after a chat room message is displayed
+@param room Jabber ID of the room
+@param nick nickname of the message sender 
+@param message the received message
 */
 void prof_post_room_message_display(const char * const room, const char * const nick, const char *message);
 
 /**
-Called before a MUC message is sent
-@param room The JID of the room
-@param message The message to send
-@return The new message, or NULL if no change made to the message
+Called before a chat room message is sent
+@param room Jabber ID of the room
+@param message the message to be sent
+@return the new message to send, or NULL to preserve the original message 
 */
 char* prof_pre_room_message_send(const char * const room, const char *message);
 
 /**
-Called after a MUC message is sent
-@param room The JID of the room
-@param message The message sent
+Called after a chat room message has been sent
+@param room Jabber ID of the room
+@param message the sent message
 */
 void prof_post_room_message_send(const char * const room, const char *message);
 
 /**
-Called before a MUC private message is displayed
-@param room The JID of the room
-@param nick The nickname of the sender
-@param message The message received
-@return The new message, or NULL if no change made to the message
+Called when the server sends a chat room history message
+@param room Jabber ID of the room
+@param nick nickname of the message sender
+@param message the message to be sent
+@param timestamp time the message was originally sent to the room, in ISO8601 format
+*/
+void prof_on_room_history_message(const char * const room, const char *const nick, const char *const message, const char *const timestamp);
+
+/**
+Called before a private chat room message is displayed
+@param room Jabber ID of the room
+@param nick nickname of message sender
+@param message the received message
+@return the new message to display, or NULL to preserve the original message 
 */
 char* prof_pre_priv_message_display(const char * const room, const char * const nick, const char *message);
 
 /**
-Called after a MUC private message is displayed
-@param room The JID of the room
-@param nick The nickname of the sender
-@param message The message received
+Called after a private chat room message is displayed
+@param room Jabber ID of the room
+@param nick nickname of the message sender 
+@param message the received message
 */
 void prof_post_priv_message_display(const char * const room, const char * const nick, const char *message);
 
 /**
-Called before a MUC private message is sent
-@param room The JID of the room
-@param nick The nickname of the recipient
-@param message The message to send
-@return The new message, or NULL if no change made to the message
+Called before a private chat room message is sent
+@param room Jabber ID of the room
+@param nick nickname of message recipient
+@param message the message to be sent
+@return the new message to send, or NULL to preserve the original message 
 */
 char* prof_pre_priv_message_send(const char * const room, const char * const nick, const char *message);
 
 /**
-Called after a MUC private message is sent
-@param room The JID of the room
-@param nick The nickname of the recipient
-@param message The message sent
+Called after a private chat room message has been sent
+@param room Jabber ID of the room
+@param nick nickname of the message recipient
+@param message the sent message
 */
 void prof_post_priv_message_send(const char * const room, const char * const nick, const char *message);
+
+/**
+Called before an XMPP message stanza is sent
+@param stanza The stanza to send
+@return The new stanza to send, or NULL to preserve the original stanza
+*/
+char* prof_on_message_stanza_send(const char *const stanza);
+
+/**
+Called when an XMPP message stanza is received
+@param stanza The stanza received
+@return 1 if Profanity should continue to process the message stanza, 0 otherwise
+*/
+int prof_on_message_stanza_receive(const char *const stanza);
+
+/**
+Called before an XMPP presence stanza is sent
+@param stanza The stanza to send
+@return The new stanza to send, or NULL to preserve the original stanza
+*/
+char* prof_on_presence_stanza_send(const char *const stanza);
+
+/**
+Called when an XMPP presence stanza is received
+@param stanza The stanza received
+@return 1 if Profanity should continue to process the presence stanza, 0 otherwise
+*/
+int prof_on_presence_stanza_receive(const char *const stanza);
+
+/**
+Called before an XMPP iq stanza is sent
+@param stanza The stanza to send
+@return The new stanza to send, or NULL to preserve the original stanza
+*/
+char* prof_on_iq_stanza_send(const char *const stanza);
+
+/**
+Called when an XMPP iq stanza is received
+@param stanza The stanza received
+@return 1 if Profanity should continue to process the iq stanza, 0 otherwise
+*/
+int prof_on_iq_stanza_receive(const char *const stanza);
+
+/**
+Called when a contact goes offline
+@param barejid Jabber ID of the contact
+@param resource the resource being disconnected
+@param status the status message received with the offline presence, or NULL
+*/
+void prof_on_contact_offline(const char *const barejid, const char *const resource, const char *const status);
+
+/**
+Called when a presence notification is received from a contact
+@param barejid Jabber ID of the contact
+@param resource the resource being disconnected
+@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd"
+@param status the status message received with the presence, or NULL
+@param priority the priority associated with the resource
+*/
+void prof_on_contact_presence(const char *const barejid, const char *const resource, const char *const presence, const char *const status, const int priority);
+
+/**
+Called when a chat window is focussed
+@param barejid Jabber ID of the chat window recipient
+*/
+void prof_on_chat_win_focus(const char *const barejid);
+
+/**
+Called when a chat room window is focussed
+@param room Jabber ID of the room
+*/
+void prof_on_room_win_focus(const char *const roomjid);