Jabber Developer
40dd773c6a
All checks were successful
CI API Docs / Test C API Documentation Generation (pull_request) Successful in 23s
CI API Docs / Test Python API Documentation Generation (pull_request) Successful in 26s
CI Code / Check coding style (pull_request) Successful in 33s
CI Code / Check spelling (pull_request) Successful in 20s
CI Code / Linux (debian) (pull_request) Successful in 12m26s
CI Code / Linux (ubuntu) (pull_request) Successful in 12m46s
CI Code / Linux (arch) (pull_request) Successful in 15m17s
CI API Docs / Test C API Documentation Generation (push) Successful in 28s
CI API Docs / Test Python API Documentation Generation (push) Successful in 29s
- 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
247 lines
9.1 KiB
C
247 lines
9.1 KiB
C
/** @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 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 CProof is started
|
|
*/
|
|
void prof_on_start(void);
|
|
|
|
/**
|
|
* Called when the user quits CProof
|
|
*/
|
|
void prof_on_shutdown(void);
|
|
|
|
/**
|
|
* 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 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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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 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
|
|
*/
|
|
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 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
|
|
*/
|
|
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 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
|
|
*/
|
|
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 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); |