Types

This section describes various types defined by the library.

irc_session_t

typedef struct irc_session_s irc_session_t

The IRC session handle created by callind irc_create_session(). Most of the library function calls expect this handle as a parameter. You can create as many handles as you want. Each handle could be used to establish a single IRC connection to an IRC server as a single user.

Once the handle is not used anymore, it should be destroyed by calling irc_destroy_session().

irc_dcc_session_t

typedef struct irc_dcc_session_s irc_dcc_session_t

This structure describes a DCC session used by libircclient. Its members are internal to libircclient, and should not be used directly.

irc_dcc_t

typedef unsigned int irc_dcc_t

This type is a DCC session identifier, used to identify the DCC sessions in callbacks and various functions.

irc_callbacks_t

typedef struct irc_callbacks_t
typedef struct
{
  irc_event_callback_t         event_connect;
  irc_event_callback_t         event_nick;
  irc_event_callback_t         event_quit;
  irc_event_callback_t         event_join;
  irc_event_callback_t         event_part;
  irc_event_callback_t         event_mode;
  irc_event_callback_t         event_umode;
  irc_event_callback_t         event_topic;
  irc_event_callback_t         event_kick;
  irc_event_callback_t         event_channel;
  irc_event_callback_t         event_privmsg;
  irc_event_callback_t         event_notice;
  irc_event_callback_t         event_channel_notice;
  irc_event_callback_t         event_invite;
  irc_event_callback_t         event_ctcp_req;
  irc_event_callback_t         event_ctcp_rep;
  irc_event_callback_t         event_ctcp_action;
  irc_event_callback_t         event_unknown;
  irc_eventcode_callback_t     event_numeric;
  irc_event_dcc_chat_t         event_dcc_chat_req;
  irc_event_dcc_send_t         event_dcc_send_req;
}

Describes the event callbacks structure which is used in registering the callbacks.

All the communication with the IRC network is based on events. Generally speaking, event is anything generated by someone else in the network, or by the IRC server itself. “Someone sends you a message”, “Someone has joined the channel”, “Someone has quits IRC” - all these messages are events.

Every event has its own event handler, which is called when the appropriate event is received. You don’t have to define all the event handlers; define only the handlers for the events you need to intercept, and set the remaining handler pointers to NULL.

event_connect

This event is triggered when the connection to the IRC server is successfully established, and the MOTD is received. Depending on the server it may also be possible to send the commands before this event.

This event uses irc_event_callback_t callback with the following values:

origin Unused, set to NULL
params Unused, set to NULL
event_nick

This event is triggered when the NICK message is received. It happens when one of the users (including you) in one of the channels you are watching (have joined) changed their nick.

Changing your own nick will also generate this event. Note that the server may change your nick independently, so you must track this event.

This event uses irc_event_callback_t callback with the following values:

origin The original nick (may be yours!)
params params[0] contains a new nick.
event_quit

This event is triggered when the QUIT message is received. It happens when one of the users in one of the channels you are watching (have joined) disconnected from the IRC server.

This event uses irc_event_callback_t callback with the following values:

origin The user who disconnected
params params[0] is optional, contains the user-specified reason to quit
event_join

This event is triggered upon receipt of a JOIN message. It happens when a new user joins the channel you are watching (have joined). It also happens when you joined the new channel.

Note that you may be “forced” to join the channel (and therefore receive this event) without issuing the JOIN command. A typical case is when the NickServ bot on the server is configured to auto-join you to specific channels.

This event uses irc_event_callback_t callback with the following values:

origin The user who joined the channel (this may be you!)
params params[0] contains the channel name
event_part

This event is triggered upon receipt of a PART message. It happens when a user leaves the channel you are watching (have joined). It also happens when you leave a channel.

This event uses irc_event_callback_t callback with the following values:

origin The user who left the channel (this may be you!)
params params[0] contains the channel name params[1] is optional and contains the user-specified reason
event_mode

This event is triggered upon receipt of a channel MODE message. It happens when someone changed the mode(s) of the channel you are watching (have joined).

This event uses irc_event_callback_t callback with the following values:

origin The user who performed the change
params params[0] contains the channel name params[1] contains the channel mode changes, such as “+t”, “-i” params[2] optional, contains the argument for the channel mode (for example, a nick for the +o mode)
event_umode

This event is triggered upon receipt of a user MODE message. It happens when your user mode is changed.

This event uses irc_event_callback_t callback with the following values:

origin The user who performed the change
params params[0] contains the channel name params[1] contains the user mode changes, such as “+t”, “-i”
event_topic

This event is triggered upon receipt of a TOPIC message. It happens when someone changed the topic on the channel you are watching (have joined).

This event uses irc_event_callback_t callback with the following values:

origin The user who performed the change
params params[0] contains the channel name params[1] optional, contains the new topic
event_kick

This event is triggered upon receipt of a KICK message. It happens when someone (including you) kicked someone (including you) from the channel you are watching (have joined).

It is possible to kick yourself from the channel.

This event uses irc_event_callback_t callback with the following values:

origin The user who performed the action (may be you)
params params[0] contains the channel name params[1] optional, contains the nick of the kicked params[2] optional, contains the reason for the kick
event_channel

This event is triggered upon receipt of a PRIVMSG message sent to the channel. It happens when someone (but not you) sent a message to the channel you are watching (have joined).

Your own messages do not trigger this event. However the server can still “force” you to send a message to the channel by generating this event.

This event uses irc_event_callback_t callback with the following values:

origin The user who sent a message
params params[0] contains the channel name params[1] optional, contains the message text
event_privmsg

This event is triggered upon receipt of a PRIVMSG message sent privately to you. It happens when someone sent you a message.

This event uses irc_event_callback_t callback with the following values:

origin The user who sent a message
params params[0] contains your nick params[1] optional, contains the message text
event_notice

This event is triggered upon receipt of a NOTICE message. This message is similar to PRIVMSG and matches the event_privmsg. According to RFC 1459, the only difference between NOTICE and PRIVMSG is that you should NEVER automatically reply to NOTICE messages. Unfortunately, this rule is frequently violated by IRC servers itself - for example, NICKSERV messages require reply, and are sent as NOTICE.

This event uses irc_event_callback_t callback with the following values:

origin The user who sent a message
params params[0] contains the target nick name params[1] optional, contains the message text
event_channel_notice

This event is triggered upon receipt of a NOTICE message. This message is similar to PRIVMSG and matches the event_channel. According to RFC 1459, the only difference between NOTICE and PRIVMSG is that you should NEVER automatically reply to NOTICE messages. Unfortunately, this rule is frequently violated by IRC servers itself - for example, NICKSERV messages require reply, and are sent as NOTICE.

This event uses irc_event_callback_t callback with the following values:

origin The user who sent a message
params params[0] contains the channel name params[1] optional, contains the message text
event_invite

This event is triggered upon receipt of an INVITE message. It happens when someone invited you to a channel which has +i (invite-only) mode.

This event uses irc_event_callback_t callback with the following values:

origin The user who invited you
params params[0] contains your nick params[1] optional, contains the channel name

See also: irc_cmd_invite()

event_ctcp_req

This event is triggered upon receipt of an CTCP request. By default, the built-in CTCP request handler is used.

Mirc generates PING, FINGER, VERSION, TIME and ACTION messages which are automatically handled by the library if this event is not handled by your application. Those messages are replied automatically except the ACTION message which triggers event_ctcp_action event. If you need to handle more types of the message, define this event handler, and check the source code of libirc_event_ctcp_internal function to see how to write your own CTCP request handler. Note that you must support at least CTCP PING to pass the spoof check by some IRC servers.

Also you may find useful this question in FAQ: ref faq4

This event uses irc_event_callback_t callback with the following values:

origin The user who generated the message
params params[0] contains the complete CTCP message
event_ctcp_rep

This event is triggered upon receipt of an CTCP response. Thus if you generate the CTCP message and the remote user responded, this event handler will be called.

This event uses irc_event_callback_t callback with the following values:

origin The user who generated the message
params params[0] contains the complete CTCP message
event_ctcp_action

This event is triggered upon receipt of an CTCP ACTION message. It is only invoked if you did not define the event_ctcp_req event handler.

Such messages typically look like that in the IRC client:

::
[08:32:55] * Michael is having fun [08:32:55] * Bobby’s getting jealous

This event uses irc_event_callback_t callback with the following values:

origin The user who generated the message
params params[0] contains the content of ACTION message
event_unknown

This event is triggered upon receipt of an unknown message which is not handled by the library.

This event uses irc_event_callback_t callback with the following values:

origin The user who generated the event
params Zero or more parameters provided with the event
event_numeric

This event is triggered upon receipt of every numeric message from the server. The incomplete list of those responses could be found in RFC 1429. This event is necessary to handle for any meaningful client.

This event uses the dedicated irc_eventcode_callback_t_ callback. See the callback documentation.

event_dcc_chat_req

This event is triggered when someone attempts to establish the DCC CHAT with you.

This event uses the dedicated irc_event_dcc_chat_t callback. See the callback documentation.

event_dcc_send_req

This event is triggered when someone attempts to send you the file via DCC SEND.

This event uses the dedicated irc_event_dcc_send_t callback. See the callback documentation.

Table Of Contents

Previous topic

Functions

Next topic

Constants

This Page