aniani/profanity
1
0
Fork 0
mirror of https://github.com/profanity-im/profanity.git synced 2024-09-22 19:45:54 -04:00
Code

Update plugins API docs

Browse Source
This commit is contained in:
James Booth 2016-07-30 23:00:45 +01:00
parent 9603e04e34
commit 43b1d7f7cd
3 changed files with 184 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
apidocs/c/profapi.h
View File

@ -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 */ /** Type representing a window, used for referencing windows created by the plugin */
typedef char* PROF_WIN_TAG; typedef char* PROF_WIN_TAG;
/** Type representing a function pointer to a command callback /** Type representing a function pointer to a command callback */
@param args The arguments passed to the callback
*/
typedef void(*CMD_CB)(char **args); typedef void(*CMD_CB)(char **args);
/** Type representing a function pointer to a timed callback */ /** 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 */ /** Type representing a function pointer to a window callback */
typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line); typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line);
/** Highlights the console window in the status bar. */ /** Highlights the console window in the status bar. */
void prof_cons_alert)(void); void prof_cons_alert(void);
/** /**
Show a message in the console window. Show a message in the console window.
@param message the message to print @param message the message to print
@return 1 on success, 0 on failure @return 1 on success, 0 on failure
*/ */
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. 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 @param message the message to print
@return 1 on success, 0 on failure @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. Show a message indicating the command has been called incorrectly.
@param cmd the command name with leading slash, e.g. "/say" @param cmd the command name with leading slash, e.g. "/say"
@return 1 on success, 0 on failure @return 1 on success, 0 on failure
*/ */
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. 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 examples example usages
@param callback The {@link CMD_CB} function to execute when the command is invoked @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, char **synopsis, const char *description, char *arguments[][2], char **examples,
CMD_CB callback); 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 callback The {@link TIMED_CB} function to execute
@param interval_seconds the time between each call to the function, in seconds @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. 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 key the prefix to trigger autocompletion
@param items the items to return on 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. 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 key the prefix from which to remove the autocompletion items
@param items the items to remove @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. 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 key the prefix from which to clear the autocompletion items
@param items the items to remove @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. 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 timeout_ms the length of time before the notification disappears in milliseconds
@param category the category of the notification, also displayed @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. Send a line of input to Profanity to execute.
@param line the line to send @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. 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. @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. 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. @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. Determine whether or not the Console window is currently focussed.
@return 1 if the user is currently in the Console window, 0 otherwise. @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. 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. @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. 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. @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. Write to the Profanity log at level DEBUG.
@param message The message to log @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. Write to the Profanity log at level INFO.
@param message The message to log @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. Write to the Profanity log at level WARNING.
@param message The message to log @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. Write to the Profanity log at level ERROR.
@param message The message to log @param message The message to log
*/ */
void (*prof_log_error)(const char *message); void prof_log_error(const char *message);
/** /**
Create a plugin window. Create a plugin window.
@param win The {@link PROF_WIN_TAG} used to refer to the 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 @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}. 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 @param win the {@link PROF_WIN_TAG} used when creating the plugin window
@return 1 if the window exists, 0 otherwise @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. Focus plugin window.
@param win the {@link PROF_WIN_TAG} of the window to focus @param win the {@link PROF_WIN_TAG} of the window to focus
@return 1 on success, 0 on failure @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. Show a message in the plugin window.
@ -192,7 +189,7 @@ Show a message in the plugin window.
@param line The message to print @param line The message to print
@return 1 on success, 0 on failure @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. 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 @param message the message to print
@return 1 on success, 0 on failure @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 Send an XMPP stanza
@param stanza an XMPP stanza @param stanza an XMPP stanza
@return 1 if the stanza was sent successfully, 0 otherwise @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 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 @param def default value if setting not found
@return the setting, or default value @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 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 key the item name within the group
@param value value to set @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 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 @param def default value if setting not found
@return the setting, or default value @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 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 key the item name within the group
@param value value to set @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 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 @param def default value if setting not found
@return the setting, or default value @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 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 key the item name within the group
@param value value to set @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 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 resource resource of the sender of the message
@param message the message text @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. 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 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 @param feature the service discovery feature to be added
*/ */
void (*prof_disco_add_feature)(char *feature); void prof_disco_add_feature(char *feature);

208
apidocs/c/profhooks.h
View File

@ -3,128 +3,216 @@ C Hooks.
*/ */
/** /**
Called when profanity loads the plugin 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 as a string e.g. "0.5.0" @param version the version of Profanity
@param status The build status, either "development" or "release" @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); void prof_on_start(void);
/** /**
Called when profanity shuts down Called when the user quits Profanity
*/ */
void prof_on_shutdown(void); void prof_on_shutdown(void);
/** /**
Called when an account is connected Called when a plugin is unloaded with the /plugins unload command
@param account_name The name of the account */
@param fulljid The full JID of the account 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); void prof_on_connect(const char * const account_name, const char * const fulljid);
/** /**
Called when an account is disconnected Called when the user disconnects an account
@param account_name The name of the account @param account_name account name of the account being disconnected
@param fulljid The full JID of the account @param fulljid the full Jabber ID (barejid and resource) of the account
*/ */
void prof_on_disconnect(const char * const account_name, const char * const fulljid); void prof_on_disconnect(const char * const account_name, const char * const fulljid);
/** /**
Called before a regular chat message is displayed Called before a chat message is displayed
@param jid The JID of the sender @param barejid Jabber ID of the message sender
@param message The message received @param message the received message
@return The new message, or NULL if no change made to the 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); char* prof_pre_chat_message_display(const char * const jid, const char *message);
/** /**
Called after a regular chat message is displayed Called after a chat message is displayed
@param jid The JID of the sender @param barejid Jabber ID of the message sender
@param message The message received @param message the received message
*/ */
void prof_post_chat_message_display(const char * const jid, const char *message); void prof_post_chat_message_display(const char * const jid, const char *message);
/** /**
Called before a regular chat message is sent Called before a chat message is sent
@param jid The JID of the recipient @param barejid Jabber ID of the message recipient
@param message The message to send @param message the message to be sent
@return The new message, or NULL if no change made to the message @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); char* prof_pre_chat_message_send(const char * const jid, const char *message);
/** /**
Called after a regular chat message is sent Called after a chat message has been sent
@param jid The JID of the recipient @param barejid Jabber ID of the message recipient
@param message The message sent @param message the sent message
*/ */
void prof_post_chat_message_send(const char * const jid, const char *message); void prof_post_chat_message_send(const char * const jid, const char *message);
/** /**
Called before a MUC message is displayed Called before a chat room message is displayed
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the sender @param nick nickname of message sender
@param message The message received @param message the received message
@return The new message, or NULL if no change made to the 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); char* prof_pre_room_message_display(const char * const room, const char * const nick, const char *message);
/** /**
Called after a MUC message is displayed Called after a chat room message is displayed
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the sender @param nick nickname of the message sender
@param message The message received @param message the received message
*/ */
void prof_post_room_message_display(const char * const room, const char * const nick, const char *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 Called before a chat room message is sent
@param room The JID of the room @param room Jabber ID of the room
@param message The message to send @param message the message to be sent
@return The new message, or NULL if no change made to the message @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); char* prof_pre_room_message_send(const char * const room, const char *message);
/** /**
Called after a MUC message is sent Called after a chat room message has been sent
@param room The JID of the room @param room Jabber ID of the room
@param message The message sent @param message the sent message
*/ */
void prof_post_room_message_send(const char * const room, const char *message); void prof_post_room_message_send(const char * const room, const char *message);
/** /**
Called before a MUC private message is displayed Called when the server sends a chat room history message
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the sender @param nick nickname of the message sender
@param message The message received @param message the message to be sent
@return The new message, or NULL if no change made to the message @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); 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 Called after a private chat room message is displayed
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the sender @param nick nickname of the message sender
@param message The message received @param message the received message
*/ */
void prof_post_priv_message_display(const char * const room, const char * const nick, const char *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 Called before a private chat room message is sent
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the recipient @param nick nickname of message recipient
@param message The message to send @param message the message to be sent
@return The new message, or NULL if no change made to the message @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); 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 Called after a private chat room message has been sent
@param room The JID of the room @param room Jabber ID of the room
@param nick The nickname of the recipient @param nick nickname of the message recipient
@param message The message sent @param message the sent message
*/ */
void prof_post_priv_message_send(const char * const room, const char * const nick, const char *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);

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

@ -236,6 +236,7 @@ def prof_post_priv_message_send(room, nick, message):
:param nick: nickname of the message recipient :param nick: nickname of the message recipient
:param message: the sent message :param message: the sent message
:type room: str or unicode :type room: str or unicode
:type nick: str or unicode
:type message: str or unicode :type message: str or unicode
""" """
pass pass