366 lines
18 KiB
ReStructuredText
366 lines
18 KiB
ReStructuredText
|
|
Types
|
|
~~~~~
|
|
|
|
This section describes various types defined by the library.
|
|
|
|
irc_session_t
|
|
^^^^^^^^^^^^^
|
|
|
|
.. c:type:: typedef struct irc_session_s irc_session_t
|
|
|
|
The IRC session handle created by callind :c:func:`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 :c:func:`irc_destroy_session`.
|
|
|
|
|
|
irc_dcc_session_t
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
.. c:type:: 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
|
|
^^^^^^^^^
|
|
|
|
.. c:type:: 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
|
|
^^^^^^^^^^^^^^^
|
|
|
|
.. c:type:: 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.
|
|
|
|
.. c:member:: 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 :c:type:`irc_event_callback_t` callback with the following values:
|
|
|
|
+-------------+------------------------------------------------------------------+
|
|
| *origin* | Unused, set to NULL |
|
|
+-------------+------------------------------------------------------------------+
|
|
| *params* | Unused, set to NULL |
|
|
+-------------+------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`irc_event_callback_t` callback with the following values:
|
|
|
|
+-------------+------------------------------------------------------------------+
|
|
| *origin* | The original nick (may be yours!) |
|
|
+-------------+------------------------------------------------------------------+
|
|
| *params* | params[0] contains a new nick. |
|
|
+-------------+------------------------------------------------------------------+
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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) |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: event_umode
|
|
|
|
This event is triggered upon receipt of a user MODE message. It happens when your user mode is changed.
|
|
|
|
This event uses :c:type:`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" |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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: :c:func:`irc_cmd_invite`
|
|
|
|
|
|
.. c:member:: 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 :c:type:`irc_event_callback_t` callback with the following values:
|
|
|
|
+-------------+-------------------------------------------------------------------+
|
|
| *origin* | The user who generated the message |
|
|
+-------------+-------------------------------------------------------------------+
|
|
| *params* | params[0] contains the complete CTCP message |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`irc_event_callback_t` callback with the following values:
|
|
|
|
+-------------+-------------------------------------------------------------------+
|
|
| *origin* | The user who generated the message |
|
|
+-------------+-------------------------------------------------------------------+
|
|
| *params* | params[0] contains the complete CTCP message |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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 :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: event_unknown
|
|
|
|
This event is triggered upon receipt of an unknown message which is not handled by the library.
|
|
|
|
This event uses :c:type:`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 |
|
|
+-------------+-------------------------------------------------------------------+
|
|
|
|
|
|
.. c:member:: 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.
|
|
|
|
|
|
.. c:member:: event_dcc_chat_req
|
|
|
|
This event is triggered when someone attempts to establish the DCC CHAT with you.
|
|
|
|
This event uses the dedicated :c:type:`irc_event_dcc_chat_t` callback. See the callback documentation.
|
|
|
|
|
|
.. c:member:: event_dcc_send_req
|
|
|
|
This event is triggered when someone attempts to send you the file via DCC SEND.
|
|
|
|
This event uses the dedicated :c:type:`irc_event_dcc_send_t` callback. See the callback documentation.
|