RageIRCd v2.0 (bluemoon): Hooks
-------------------------------

$Id: hooks.txt,v 1.10.2.1 2005/02/21 02:32:45 amcwilliam Exp $
(C) 2000-2005 the RageIRCd Development Team, all rights reserved.

RageIRCd v2.0 incorporates a new hook subsystem, allowing external modules 
to plug into ircd in order to extend server functionality.

RageIRCd v2.0 contains a range of different hooks hard-coded into the 
standard distribution. These hooks allow dynamic modules to plug into 
ircd, providing a means for other developers to greatly extend the servers 
functionality.

Each time a hook is called upon, it will run each event associated with 
it. Hook Events are provided with a pointer to a HookData structure, for 
any additional parameters associated with the hook. The HookData structure 
is as follows.

typedef struct _hook_data {
	aClient *cptr;		/* Client pointer */
	aClient *sptr;		/* Client pointer */
	aClient *acptr;		/* Client pointer */
	aChannel *chptr;	/* Channel poiner */

	void *v;		/* void pointer */
	int i;			/* integer value */
	time_t t;		/* time_t value */
	char *c;		/* char* pointer */
} HookData;

The following hooks are hard-coded into RageIRCd v2.0.

------------------------|-------------------------------------------------------
Name                    | Description
------------------------|-------------------------------------------------------
h_post_accept           | Called after connection is accepted on listener, but
                        | before any client structures are allocated. Returning
                        | FLUSH_BUFFER will result in the socket being dropped.
                        |
                        | i - file descriptor
------------------------|-------------------------------------------------------
h_user_access           | Called during user authorisation, after an allow{}
                        | block has been successfully matched. Returning
                        | FLUSH_BUFFER will result in the client becoming
                        | unauthorised to connect, and subsequently exited.
                        |
                        | sptr - pointer to local aClient structure.
------------------------|-------------------------------------------------------
h_register_user_local   | Called during local user registration, before the
                        | client connection is announced. If an event results in
                        | calling exit_client() for the client, the hook MUST
                        | return FLUSH_BUFFER to halt further processing.
                        |
                        | sptr - pointer to local aClient in registration.
------------------------|-------------------------------------------------------
h_register_user_remote  | Called during remote user registration. This hook
                        | cannot abort clients, so the return value is ignored.
                        |
                        | cptr - pointer to uplink (always local)
                        | sptr - pointer to remote aClient in registration
------------------------|-------------------------------------------------------
h_post_register_user    | Called after local user registration is complete, and
                        | the client has been introduced to the network. This is
                        | for local clients only, and cannot abort. Return value
                        | is therefore ignored.
                        |
                        | sptr - pointer to fully-registered client.
------------------------|-------------------------------------------------------
h_conf_parse            | Called to parse unknown config entries. Valid returns:
                        | - CONF_SUCCESS: successfully parsed the entry.
                        | - CONF_FAILURE: failed to parse the entry.
                        | - CONF_NOMATCH: parser does not match entry.
                        |
                        | v - pointer to ConfigUnknown structure.
------------------------|-------------------------------------------------------
h_conf_test             | Called to test previously parsed unknown config
                        | entries. Valid returns:
                        | - CONF_SUCCESS: entry passed testing
                        | - CONF_FAILURE: entry failed testing (will be freed)
                        | - CONF_NOMATCH: test is not for the specified entry.
                        |
                        | v - pointer to ConfigUnknown structure.
------------------------|-------------------------------------------------------
h_conf_verify           | Called to verify all required config variables are
                        | present and correctly configured. Return value is
                        | ignored.
                        |
                        | No arguments - HookData pointer will be NULL!
------------------------|-------------------------------------------------------
h_conf_complete         | Called after config parse/testing is complete, to
                        | setup anything that depends on complete config. Return
                        | value is ignored.
                        |
                        | No arguments - HookData pointer will be NULL!
------------------------|-------------------------------------------------------
h_conf_rehash           | Called during rehash, after config has been erased but
                        | before ircd.conf has been re-loaded. Return value is
                        | ignored.
                        |
                        | No arguments - HookData pointer will be NULL!
------------------------|-------------------------------------------------------
h_pre_netio             | Called on each main loop iteration, before the main
                        | network I/O is performed. Return value is ignored.
                        |
                        | No arguments - HookData pointer will be NULL!
------------------------|-------------------------------------------------------
h_post_netio            | Called on each main loop iteration, after the main
                        | network I/O has been performed. Return value is
                        | ignored.
                        |
                        | No arguments - HookData pointer will be NULL!
------------------------|-------------------------------------------------------
h_exit_user_local       | Called when a local client is being exited. Return
                        | value is ignored.
                        |
                        | sptr - pointer to local client being exited
                        | c - pointer to comment string
------------------------|-------------------------------------------------------
h_exit_user_remote      | Called when a remote client is being exited. Return
                        | value is ignored.
                        |
                        | cptr - pointer to uplink (always local)
                        | sptr - pointer to remote client being exited
                        | c - pointer to comment string
------------------------|-------------------------------------------------------
h_exit_server           | Called when a server is being exited. Return value is
                        | ignored.
                        |
                        | sptr - pointer to server being exited
                        | c - pointer to comment string
------------------------|-------------------------------------------------------
h_exit_unknown          | Called when an unknown is being exited. Return value
                        | is ignored. Remember, an unknown connection can only
                        | ever be local!
                        |
                        | sptr - pointer to unknown aClient structure
                        | c - pointer to comment string
------------------------|-------------------------------------------------------
h_pre_connauth          | Called as soon as a new local client is passed to the
                        | ConnectAuth module, to check identd and DNS. Return
                        | value is ignored. (Performed before any identd/DNS
                        | checks are actually performed.)
                        |
                        | sptr - pointer to local (unknown) aClient structure
------------------------|-------------------------------------------------------

The following hooks are setup from modules.

------------------------|-------------------------------------------------------
Name                    | Description
------------------------|-------------------------------------------------------
h_post_oper             | Called after a local user has successfully opered up.
                        | Return value is ignored.
From m_oper             |
                        | sptr - pointer to local client structure
                        | v - pointer to ConfigItem_oper structure that was used
------------------------|-------------------------------------------------------
h_pre_join              | Called before a local user has been allowed to join
                        | the specified channel. Returning FLUSH_BUFFER will
From m_join             | result in the join for that channel being aborted.
                        |
                        | sptr - pointer to local client structure
                        | c - pointer to the name of the channel
                        | chptr - pointer to aChannel structure, or NULL if the
                        |         channel is being newly created
                        | i - value of user flags (0 [zero] or CMODE_CHANOP)
------------------------|-------------------------------------------------------
h_post_join             | Called after a local user has  successfully joined a
                        | channel, and it's been sent across the network via
From m_join             | Client SJOIN. Return value is ignored.
                        |
                        | sptr - pointer to local client structure
                        | c - pointer to the name of the channel
                        | chptr - pointer to the aChannel structure (never NULL)
                        | i - value of user flags (0 [zero] or CMODE_CHANOP)
------------------------|-------------------------------------------------------
h_chanmsg               | Called when parsing a message to a channel. Only
                        | called for local sources. Return value of FLUSH_BUFFER
From m_message          | will result in the message being ignored.
                        |
                        | sptr - pointer to local client (source of the msg)
                        | chptr - pointer to the aChannel structure
                        | i - notice flag (0 [zero] for privmsg, 1 for notice)
                        | c - pointer to the message text/string
------------------------|-------------------------------------------------------
h_usermsg               | Called when parsing a message directed to a user. Only
                        | called for local sources. Return value of FLUSH_BUFFER
From m_message          | will result in the message being ignored.
                        |
                        | sptr - pointer to local client (source of the msg)
                        | acptr - pointer to the target client (can be remote)
                        | i - notice flag (0 [zero] for privmsg, 1 for notice)
                        | c - pointer to the message text/string
------------------------|-------------------------------------------------------
h_dccsend               | Called when a DCC send is detected, when the target
                        | user is local. Return value of FLUSH_BUFFER will
From m_message          | result in the DCC send being blocked.
                        |
                        | cptr - pointer to uplink server (always local)
                        | sptr - pointer to source client of send (maybe remote)
                        | acptr - pointer to target user (always local)
                        | c - pointer to DCC send string
------------------------|-------------------------------------------------------
h_nick_change_local     | Called when a local client changes his/her nickname.
                        | Return value is ignored.
From m_nick             |
                        | sptr - pointer to local client doing nick change
------------------------|-------------------------------------------------------
h_nick_change_remote    | Called when a remote client changes his/her nickname.
                        | Return value is ignored.
From m_nick             |
                        | cptr - pointer to uplink server (always local)
                        | sptr - pointer to remote client doing nick change
------------------------|-------------------------------------------------------
h_stats                 | Called when processing a STATS request. Return value
                        | of FLUSH_BUFFER will result in the request being
From m_stats            | ignored.
                        |
                        | cptr - pointer to uplink server (always local)
                        | sptr - pointer to client doing stats (may be remote)
                        | v - pointer to associated StatsRequest structure
                        | c - pointer to optional parameter (usually NULL)
------------------------|-------------------------------------------------------
h_whois                 | Called when a whois is performed, before final idle-
                        | time numeric is sent. Return value is ignored.
From m_whois            |
                        | cptr - pointer to uplink server (always local)
                        | sptr - pointer to client doing whois (may be remote)
                        | acptr - pointer to target client of whois
------------------------|-------------------------------------------------------

The above hooks are standard in RageIRCd v2.0. Additional custom or third party
modules may create further hooks. However, please make sure you fully read and
understand any documentation provided with such modules before attempting to
register events in them.

End of document.
