This section describes the callbacks supported by the library.
Prototype:
Parameters:
session | The IRC session, which generated the event |
event | The text name of the event. Useful in case a single event handler is used to handle multiple events |
origin | The originator of the event. Depends on the event. |
params | Extra parameters, if any, for this event. The number of extra parameters depends on the event, and may be zero. Each parameter is a NULL-terminated text string. None of the params can be NULL, but the params pointer itself could be NULL for some events. |
count | The number of entries in the params argument supplied. |
Description:
Every IRC event generates a callback. This type of callback is universal and is used by almost all IRC events. Depending on the event nature, it can have zero or more parameters. For each type of event, the number of provided parameters is fixed, and their meaning is described in the irc_callbacks_t structure.
Every event has an origin (i.e. who originated the event). In some cases the origin variable may be NULL, which indicates that event origin is unknown. The origin usually looks like nick!host@ircserver, i.e. like tim!home@irc.server.net. Such origins can not be used in IRC commands, and need to be stripped (i.e. host and server part should be cut off) before using. This can be done either manually, by calling irc_target_get_nick(), or automatically for all the events - by setting the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().
Prototype:
Parameters:
session | IRC session, which generates an event (the one returned by irc_create_session) |
nick | User who requested the chat |
addr | IP address of the person such as 189.12.34.56 |
dccid | Identifier associated with this request which should be passed to the irc_dcc_accept() / irc_dcc_decline() functions |
Description:
This callback is called when someone requests DCC CHAT with you. DCC CHAT is the type of chat which goes directly between the clients, instead of going through the IRC server. Since the TCP connection must be established for it to happen, typically the initiator must either have the public IP or special software on the firewall which handles the necessary port forwarding.
You must respond to the chat request either by calling irc_dcc_accept() to accept it, or by calling irc_dcc_decline() to decline it.
Prototype:
Parameters:
session | The IRC session, which generates an event (the one returned by irc_create_session) |
nick | The user who requested the chat |
addr | The IP address of the person such as 189.12.34.56 |
filename | The name of the file the user is trying to send you |
size | The size of the file |
dccid | Identifier associated with this request which should be passed to the irc_dcc_accept() / irc_dcc_decline() functions |
Description:
This callback is called when someone wants to send you a file by using DCC SEND. DCC SEND goes directly between the clients, and requires the TCP connection to be established established for it to happen. Therefore the initiator must either have the public IP or special software on the firewall which handles the necessary port forwarding.
You must respond to the chat request either by calling irc_dcc_accept() to accept it, or by calling irc_dcc_decline() to decline it.
Prototype:
Parameters:
session | The IRC session, which generates an event (the one returned by irc_create_session) |
id | The DCC session id |
status | The DCC connection status. 0 means there is no error, otherwise contains an error code |
ctx | The user-provided context |
data | Data received (if available), otherwise NULL |
length | Size of the data received if any data |
Description:
This callback is called for all DCC functions when state change occurs.
Prototype:
Parameters:
session | The IRC session, which generates an event (the one returned by irc_create_session) |
event | The numeric code of the event. Useful in case a single event handler is used to handle multiple events |
origin | The originator of the event. Depends on the event. |
params | Extra parameters, if any, for this event. The number of extra parameters depends on the event, and may be zero. Each parameter is a NULL-terminated text string. None of the params can be NULL, but the params pointer itself could be NULL for some events. |
count | The number of entries in the params argument supplied. |
Description:
This is an advanced callback for those who want to handle events deeper. Most times the IRC server replies to your actions with numeric events. Most of those events are error codes, and some are list-start and list-stop markers. Every code has its own set of params; for details you can either experiment, or read RFC 1459 (don’t expect servers to follow it closely though).
Every event has an origin (i.e. who originated the event). In some cases the origin variable may be NULL, which indicates that event origin is unknown. The origin usually looks like nick!host@ircserver, i.e. like tim!home@irc.server.net. Such origins can not be used in IRC commands, and need to be stripped (i.e. host and server part should be cut off) before using. This can be done either manually, by calling irc_target_get_nick(), or automatically for all the events - by setting the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().