1LIBIRCCLIENT(1)                  Libircclient                  LIBIRCCLIENT(1)
2
3
4

NAME

6       libircclient - Libircclient Documentation
7

INTRODUCTION

9   Introduction
10   Overview
11       Libircclient is a small but extremely powerful library which implements
12       the client IRC protocol. It is designed to be small, fast, portable and
13       compatible  with  the RFC standards as well as non-standard but popular
14       features. It is perfect for building the IRC clients and bots.
15
16   Features
17          · Comprehensive C API;
18
19          · Full coverage of the IRC protocol using providing functions;
20
21          · Supports multiple simultaneous connection to different IRC servers
22            or even to the same server;
23
24          · Supports  both  plain  and SSL connections to the IRC servers with
25            the optional certificate check;
26
27          · Full multi-threading support, the library is thread-safe;
28
29          · All the processing could be handled by a  single  thread  even  if
30            multiple connections are used;
31
32          · Non-blocking,  asynchronous event-based interface implemented with
33            callbacks;
34
35          · Extra  support  for  the  socket-based  applications,  which   use
36            select();
37
38          · CTCP support with optional build-in reply code;
39
40          · Supports CTCP PING necessary to pass the “spoof check” implemented
41            by most IRC servers;
42
43          · Flexible DCC support, including both DCC chat, and DCC file trans‐
44            fer;
45
46          · Can both initiate and react to initiated DCC;
47
48          · Can accept or decline DCC sessions asynchronously;
49
50          · Written  in  plain C, very small binary size (around 30K depending
51            on platform);
52
53          · Compatible all tested IRC clients;
54
55          · Free software licensed under the LGPLv3 license;
56
57          · Supports Linux as well as any POSIX-compliant Unix, Mac OS  X  and
58            Microsoft Windows;
59
60          · Supports 32/64bit architectures as well as non-x86 architectures;
61
62          · IPv6 support (optional, must be compiled in);
63
64          · OpenSSL support (optional, must be compiled in);
65
66          · Cocoa interface by Nathan Ollerenshaw;
67
68          · Comprehensive documentation, examples and the FAQ;
69
70   Known issues
71       Even  though  possible  by  using multiple sessions, the library is not
72       suitable to connect to a large number of IRC servers simultaneously. If
73       you still want to use it, you'd have to overcome the following:
74
75          · You cannot use the main loop in irc_run() because it only supports
76            one session. You would have to use irc_add_select_descriptors()
77
78          · You'd have to handle reconnections separately  by  processing  the
79            relevant irc_process_select_descriptors() return values
80
81          · If  you wish to use poll/epoll() instead of select() you'd have to
82            write more logic as it is not directly supported. See the FAQ.
83
84          · The library is not optimized to have a low  per-connection  memory
85            footprint,  each  non-SSL connection uses at least 4K, with around
86            32K per connection for SSL.
87
88   Author
89       This library is created by George Yunaev, copyright 2004-2013.
90
91   License
92       Libircclient is licensed under Lesser General Public License version  3
93       or higher. The complete license text is provided in the Appendix.
94

INTEGRATION

96   Integration
97   Requirements
98   Supported operating systems and compilers
99       The library has been extensively tested on Linux x86 and x86_64. It has
100       also been tested on Solaris x86, Linux on ARM and Linux on  MIPS  plat‐
101       forms, on Mac OS X on x86 and on various versions of Microsoft Windows.
102
103   Compilation
104       On  Linux,  FreeBSD  and  Mac  OS  X the library has to be compiled and
105       installed before use unless you use a precompiled package  provided  by
106       your  operating  system distribution. If it is provided, you are recom‐
107       mended to use it as it would be updated  from  the  central  repository
108       when the bugs are fixed.
109
110       On Microsoft Windows the official library binaries are provided, so you
111       do not have to build it. Unless you have experience building with  Cyg‐
112       win,  you're  advised  not  to  build  from source and use the official
113       binary.
114
115   Required libraries
116       The library depends only  on  libc  (glibc-devel  on  Linux)  and  gcc,
117       although the examples require also libstdc++ (libstdc++-devel) and g++.
118       Minimum supported version is glibc 2.2, although if IPv6 is  requested,
119       at least glibc 2.4 is required.
120
121       If the library is built with SSL support, the openssl development pack‐
122       age (openssl-devel) needs to be installed.
123
124       On Microsoft Windows the Cygwin  with  necessary  development  packages
125       must be installed (and openssl-devel as well).
126
127   Compiling
128       The library is configured and built the standard Unix way:
129
130          ./configure [--enable-openssl] [--enable-ipv6]
131          make
132
133   Installing
134       Although no install is necessary to use the libraries, the install tar‐
135       get is provided for convenience and could  be  invoked  via  sudo  make
136       install
137
138   Linking
139       Link  your  application  with  either libircclient.a or libircclient.so
140       depending on your needs. If you use the system-provided library, please
141       link with libircclient.so.
142
143       If  you  have built the library with SSL support, you will need to link
144       with OpenSSL libraries; add -lcrypto -lssl to your LDFLAGS
145
146       On Microsoft Windows please link with libircclient.lib which implicitly
147       links with libircclient.dll
148
149   Coding
150   Initialization
151   Include the headers
152       Before using the library you need to include the library header libirc‐
153       client.h. You may also want to include libirc_rfcnumeric.h  which  pro‐
154       vides the RFC codes:
155
156          #include "libircclient.h"
157          #include "libirc_rfcnumeric.h"
158
159   Create event handlers
160       Unlike most network protocols such as HTTP or SMTP, the IRC protocol is
161       event-based. The events come from server  asynchronously.  Some  events
162       are  triggered  by your action (such as joining the channel or changing
163       your nick), some are triggered by other IRC users (such as sending  you
164       a  message),  and  some are triggered by the IRC server itself (such as
165       sending operation notes or invoking NickServ services).
166
167       Libircclient helps handling those events by providing  the  event  han‐
168       dling structure. It declares the events you can define in your applica‐
169       tion, and when such event is received from the server, the  appropriate
170       callback  will  be  called.  The  number  of  events you need to handle
171       depending on the complexity of your client  and  the  functionality  it
172       supports.
173
174       Generally  there  are only two events you must handle to provide a bare
175       minimum functionality: event_connect and event_numeric. However  it  is
176       recommended  to create an event dump function and use it for all unused
177       events to make sure you do not miss  an  important  event  because  you
178       expected  a  wrong  one.  See  function  dump_event  in  the file exam‐
179       ples/irctest.c
180
181   Windows-specific initialization
182       If you link with the static library on Microsoft Windows, you  need  to
183       initialize  the  Winsock2 library before calling the library functions.
184       It could be done by following:
185
186          WSADATA wsaData;
187
188          if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
189              // report an error
190
191       However if you link with the dynamic library  (libircclient.dll)  which
192       is  default  if  you use the official build, this is not needed because
193       the DLL initializes it automatically on load.
194
195   Create an IRC session
196       To use the library at least one IRC session needs to  be  created.  One
197       session  could  be  used  to  establish  a single connection to one IRC
198       server for one nick.  However more than one session could be created if
199       needed.
200
201       To create a session, call the irc_create_session() function:
202
203          // The IRC callbacks structure
204          irc_callbacks_t callbacks;
205
206          // Init it
207          memset ( &callbacks, 0, sizeof(callbacks) );
208
209          // Set up the mandatory events
210          callbacks.event_connect = event_connect;
211          callbacks.event_numeric = event_numeric;
212
213          // Set up the rest of events
214
215          // Now create the session
216          irc_session_t * session = irc_create_session( &callbacks );
217
218          if ( !session )
219              // Handle the error
220
221       This  code could be repeated as many times as needed to create multiple
222       sessions. The same callback structure could be reused for multiple ses‐
223       sions.
224
225   Set options
226       Besides  debugging  there  are  two  options  you  may need to use. The
227       LIBIRC_OPTION_STRIPNICKS enables automatic parsing  of  nicknames,  and
228       since  it is hard to imagine the case when it should not be enabled, we
229       enable it:
230
231          irc_option_set( session, LIBIRC_OPTION_STRIPNICKS );
232
233       The second option you may need if you use SSL connections and  plan  to
234       connect to the servers which use self-signed certificates. See the doc‐
235       umentation for LIBIRC_OPTION_SSL_NO_VERIFY
236
237   Connect to the server
238       To initiate the connection to the IRC server,  call  the  irc_connect()
239       function:
240
241          // Connect to a regular IRC server
242          if ( irc_connect (session, "irc.example.com", 6667, 0, "mynick", "myusername", "myrealname" ) )
243            // Handle the error: irc_strerror() and irc_errno()
244
245       To  initiate  the  connection  to  the  IRC  server  over SSL, call the
246       irc_connect() function and prefix the host name or IP  address  with  a
247       hash symbol:
248
249          // Connect to the SSL server; #192.168.1.1 is also possible
250          if ( irc_connect (session, "#irc.example.com", 6669, 0, "mynick", "myusername", "myrealname" ) )
251            // Handle the error: irc_strerror() and irc_errno()
252
253       This  function  only  initiates the connection, so when it successfully
254       returns the connection is only initiated, but not established yet. Then
255       one of the following happens after you invoke the networking handler:
256
257          · If  the connection is established, you will receive the event_con‐
258            nect - this is why it is important to handle it
259
260          · If the connection failed, the  networking  handler  function  will
261            return failure
262
263   Connect to the IPv6 server
264       To  initiate the connection to the IPv6 server, call the irc_connect6()
265       function:
266
267          if ( irc_connect6 (session, "2001:0db8:85a3:0042:1000:8a2e:0370:7334", 6669, 0, "mynick", "myusername", "myrealname" ) )
268            // Handle the error: irc_strerror() and irc_errno()
269
270       The rest of the details, including the return value and the SSL are the
271       same as with regular connect.
272
273   Start the networking loop
274       To  let the library handle the events, there are two scenarios. You can
275       either invoke the built-in networking loop which will handle  the  net‐
276       working and call your events, or you can write your own loop.
277
278       Invoking  the build-in networking loop is simpler but limited. Since it
279       loops until the connection terminates, it is not an option  for  a  GUI
280       application  (unless  you start the loop in a separate thread which you
281       can do). And since this loop only can handle one session, it is  impos‐
282       sible  to  use it if you want to handle multiple IRC sessions. In those
283       cases the custom networking loop, described below, should be used.
284
285       To start the event loop call the irc_run() function:
286
287          if ( irc_run (s) )
288            // Either the connection to the server could not be established or terminated. See irc_errno()
289
290       Remember that irc_run() call will not return until the  server  connec‐
291       tion is not active anymore.
292
293   Use the custom networking loop
294       If  you  use multiple sessions or have your own socket handler, you can
295       use the custom networking loop. In this case your application  must  be
296       select()-based  (see the FAQ if you want to use other polling methods).
297       And you need to run the following loop:
298
299          // Make sure that all the IRC sessions are connected
300          if ( !irc_is_connected(session) )
301            // reconnect it, or abort
302
303          // Create the structures for select()
304          struct timeval tv;
305          fd_set in_set, out_set;
306          int maxfd = 0;
307
308          // Wait 0.25 sec for the events - you can wait longer if you want to, but the library has internal timeouts
309          // so it needs to be called periodically even if there are no network events
310          tv.tv_usec = 250000;
311          tv.tv_sec = 0;
312
313          // Initialize the sets
314          FD_ZERO (&in_set);
315          FD_ZERO (&out_set);
316
317          // Add your own descriptors you need to wait for, if any
318          ...
319
320          // Add the IRC session descriptors - call irc_add_select_descriptors() for each active session
321          irc_add_select_descriptors( session, &in_set, &out_set, &maxfd );
322
323          // Call select()
324          if ( select (maxfd + 1, &in_set, &out_set, 0, &tv) < 0 )
325             // Error
326
327          // You may also check if any descriptor is active, but again the library needs to handle internal timeouts,
328          // so you need to call irc_process_select_descriptors() for each session at least once in a few seconds
329          ...
330
331          // Call irc_process_select_descriptors() for each session with the descriptor set
332          if ( irc_process_select_descriptors (session, &in_set, &out_set) )
333              // The connection failed, or the server disconnected. Handle it.
334
335          // Do it again
336
337   Channels and users
338       Before calling any of those functions make sure you have  connected  to
339       the server.
340
341   Join and leave a channel
342       To  join  the channel call the irc_cmd_join() function with the channel
343       name:
344
345          // Join the channel #linux
346          if ( irc_cmd_join( session, "#linux", 0 ) )
347            // most likely connection error
348
349          // Join the channel $science protected by the secret key *superpassword*
350          if ( irc_cmd_join( session, "$science", "superpassword" ) )
351            // most likely connection error
352
353       You can join as many channels as  you  want,  although  the  serer  may
354       restrict the number of channels you can join simultaneously.
355
356       If  the  join was successful you will receive the event_join event. You
357       need to wait for this event before you can perform any  channel  opera‐
358       tions  (such  as sending the messages). However you do NOT have to wait
359       for this event to issue a second JOIN command as shown in  the  example
360       above.
361
362       If  the  join  was  not  successful,  you  will  receive  the error via
363       event_numeric.
364
365       To leave the channel call the irc_cmd_part() function with the  channel
366       name:
367
368          // Leave the channel #linux
369          if ( irc_cmd_part( session, "#linux" ) )
370            // most likely connection error
371
372          // Leave the channel $science
373          if ( irc_cmd_part( session, "$science" ) )
374            // most likely connection error
375
376   Send a message to a channel or to a user
377       After  you have joined the channel, you can send a message to the chan‐
378       nel by using the irc_cmd_msg() function with the channel name:
379
380          // Say "Hi!" to everyone in the channel #linux
381          if ( irc_cmd_msg( session, "#linux", "Hi!" ) )
382            // most likely connection error
383
384       Technically the protocol does not require one to join  the  channel  to
385       send the messages into the channel. However most servers by default set
386       the channel mode which prevents the users who did not join the  channel
387       from sending the message into the channel.
388
389       Same  function is used to send a "private" message to another user. The
390       "private" messages do not go through the channels, but  they  still  go
391       through  the  IRC server (sometime multiple servers) and can be seen or
392       even logged by the IRC network operators.
393
394          // Say "Hi!" to IRC user john
395          if ( irc_cmd_msg( session, "john", "Hi!" ) )
396            // most likely connection error
397
398       If the message was sent successfully you will not receive any confirma‐
399       tion or event. You will only receive the error via event_numeric if the
400       message was not sent.
401
402   Receive messages from a channel or from a user
403       You receive the channel messages by handling  the  event_channel.  Each
404       time someone says something in the channel this event is called.
405
406       You  receive  the  "private"  messages from other users by handling the
407       event_privmsg.
408
409       Those event handlers should be created in your application  and  passed
410       to the library when you create an IRC session
411
412   Send an action message
413       "Action"  messages,  also  called /me messages, are specially formatted
414       CTCP messages. However the library contains a special function to  send
415       them,  irc_cmd_me().  Actions  sent  by other people are handled by the
416       event_ctcp_action event.
417
418       Same as with sending messages no confirmation is received on success.
419
420   Send a CTCP request
421       Other CTCP requests such as PING, VERSION etc should be sent by calling
422       irc_cmd_ctcp_request(). If the CTCP response is received, it is handled
423       by the event_ctcp_rep event.
424
425   Handling DCC chat
426   Implementing the DCC callback
427       No matter whether you plan to initiate DCC chats or respond to them you
428       must implement the DCC callback:
429
430          void dcc_callback (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
431          {
432             if ( status )
433             {
434                 // If status is LIBIRC_ERR_CLOSED, the chat has been closed by the remote party.
435                 // Otherwise it is an error; the CHAT either terminated or could not be established. status is the error code; see irc_strerror(status)
436             }
437             else if ( length == 0 )
438             {
439                 // The remote side has accepted the chat request, send "hello" something to them
440                 irc_dcc_text( session, id, "Hello!" );
441             }
442             else
443             {
444                 // We have received the chat message from the remote party
445                 printf ("Remote party said: %s\n", data );
446             }
447          }
448
449       This  callback should be passed to either irc_dcc_chat() function which
450       initiates the request, or to irc_dcc_accept()  function  which  accepts
451       the DCC CHAT request initiated by another user.
452
453   Initiating the DCC CHAT
454       You   can   initiate   the  DCC  chat  with  another  user  by  calling
455       irc_dcc_chat():
456
457          // The DCC chat session id will be returned in this variable
458          irc_dcc_t dccid;
459
460          // Initiate the DCC chat with the IRC user "john"
461          if ( irc_dcc_chat( session, 0, "john", dcc_callback, &dccid ) )
462            // report error
463
464       Now you can proceed with other tasks. When John accepts or declines the
465       chat, the dcc_callback() will be called, and it will be possible to use
466       the irc_dcc_text() function to send the  chat  messages.  The  callback
467       will  also  be called each time a new chat message is received, or when
468       the chat is finished or terminated because of network error.
469
470   Responding to DCC CHAT requests
471       To respond to the DCC CHAT equests your  application  should  implement
472       for the event_dcc_chat_req event.  The callback could be implemented as
473       following:
474
475          void callback_event_dcc_chat( irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid )
476          {
477              // User 'nick' from the IP address 'addr' tries to initiate the DCC chat with us.
478              // Store this information in the application internal queue together with the dccid so the callback can return
479              dcc_queue.store( dccid, "CHAT from " + nick + " IP address: " + addr  );
480          }
481
482       and registered when the IRC session is created.   If  your  application
483       does  not  handle  DCC  at  all you can just call the irc_dcc_decline()
484       function inside the callback.
485
486       If it does, we only store this information in the callback, and return.
487       This  is  because  the  event  processing  will stop until the callback
488       returns, so popping up the dialog  asking  for  the  user  confirmation
489       would  stop  further  events  such  as channel messages from being pro‐
490       cessed. Even if your  application  is  automatic  and  doesn't  pop  up
491       dialogs it is still better to separate the chat logic from the callback
492       logic.
493
494       Somewhere later the application  would  check  the  queue  in  the  GUI
495       thread,  get  this  information,  and pop up the dialog asking the user
496       feedback. Then if the chat request was accepted, the application  would
497       call  the irc_dcc_accept() function, and if it was declined, the appli‐
498       cation would call the irc_dcc_decline() function. Both  functions  will
499       accept the dccid which identifies this specific request:
500
501          // Somewhere in the GUI thread
502          if ( !dcc_queue.empty() )
503          {
504              // Get the DCC information and show the dialog to the user
505              irc_dcc_t dccid = dcc_chat_queue.top().dccid;
506
507              ...
508
509              // React to the user entry
510              if ( dialog.isAccepted() )
511                  irc_dcc_accept( session, dccid, 0, dcc_callback );
512              else
513                  irc_dcc_decline( session, dccid );
514          }
515
516   Send CHAT messages
517       Once  the  chat  session is established, you can send the chat messages
518       using irc_dcc_text() function. Note that you need to pass the dcc  ses‐
519       sion id instead of nick:
520
521          irc_dcc_text( session, dccid, "Hello there!" );
522
523   Handling DCC file transfer
524       This section covers handling sending and receiving files via DCC.
525
526   Implementing the callback
527       No  matter  whether  you plan to send or receive files via dcc you must
528       implement the DCC callback.  While the same callback may be  used  both
529       for  sending  and receiving, this is not recommended since the logic is
530       different. Therefore the suggested implementation would be to use  dif‐
531       ferent callbacks as suggested:
532
533          // This callback is used when we send a file to the remote party
534          void callback_dcc_send_file (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
535          {
536             if ( status )
537             {
538                 // It is an error; the send operation was either terminated or the connection could not be established. status is the error code; see irc_strerror(status)
539             }
540             else
541             {
542                 // We have sent some data to the remote party, 'length' indicates how much data was sent
543                 printf ("Sent bytes: %d\n", length );
544             }
545          }
546
547          // This callback is used when we receive a file from the remote party
548          void callback_dcc_recv_file (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
549          {
550             if ( status )
551             {
552                 // It is an error; the send operation was either terminated or the connection could not be established. status is the error code; see irc_strerror(status)
553             }
554             else if ( data == 0 )
555             {
556                 // File transfer has been finished
557                 printf ("File has been received successfully\n" );
558             }
559             else
560             {
561                 // More file content has been received. Store it in memory, write to disk or something
562                 printf ("Received %d bytes of data\n", length );
563             }
564          }
565
566       This  callback  should  be passed to either irc_dcc_sendfile() function
567       which initiates the request,  or  to  irc_dcc_accept()  function  which
568       accepts the DCC RECVFILE request initiated by another user.
569
570   Sending the file via DCC
571       You  can  initiate  sending the file via DCC to another user by calling
572       irc_dcc_sendfile():
573
574          // The DCC session id will be returned in this variable
575          irc_dcc_t dccid;
576
577          // Initiate sending of file "/etc/passwd" via DCC chat to the IRC user "john"
578          if ( irc_dcc_sendfile( session, 0, "john", "/etc/passwd", callback_dcc_send_file, &dccid ) )
579            // report error
580
581       Now you can proceed with other tasks. When John  accepts  the  request,
582       the  file will be sent and callback_dcc_send_file() will be called each
583       time a piece of file is sent. The callback will also be called when the
584       file  has  been sent, or when sending was terminated because of network
585       error.
586
587   Receive a file via DCC
588       To receive the file via DCC a remote user must initiate the DCC request
589       to  send  you  a  file. To receive this request your application should
590       implement the event_dcc_send_req event. The callback  could  be  imple‐
591       mented as following:
592
593          void callback_event_dcc_file( irc_session_t * session, const char * nick, const char * addr, const char * filename, unsigned long size, irc_dcc_t dccid )
594          {
595              // User 'nick' from the IP address 'addr' tries to initiate the DCC chat with us.
596              // Store this information in the application internal queue together with the dccid so the callback can return
597              dcc_queue.store( dccid, "CHAT from " + nick + " IP address: " + addr + ", filename " + filename  );
598          }
599
600       If  your  application  does not handle DCC at all you can just call the
601       irc_dcc_decline() function inside the callback.
602
603       If it does, we only store this information in the callback, and return.
604       This  is  because  the  event  processing  will stop until the callback
605       returns, so popping up the dialog  asking  for  the  user  confirmation
606       would  stop  further  events  such  as channel messages from being pro‐
607       cessed. Even if your  application  is  automatic  and  doesn't  pop  up
608       dialogs it is still better to separate the chat logic from the callback
609       logic.
610
611       Somewhere later the application  would  check  the  queue  in  the  GUI
612       thread,  get  this  information,  and pop up the dialog asking the user
613       feedback. Then if the chat request was accepted, the application  would
614       call  the irc_dcc_accept() function, and if it was declined, the appli‐
615       cation would call the irc_dcc_decline() function. Both  functions  will
616       accept the dccid which identifies this specific request:
617
618          // Somewhere in the GUI thread
619          if ( !dcc_queue.empty() )
620          {
621              // Get the DCC information and show the dialog to the user
622              irc_dcc_t dccid = dcc_chat_queue.top().dccid;
623
624              ...
625
626              // React to the user entry
627              if ( dialog.isAccepted() )
628                  irc_dcc_accept( session, dccid, 0, dcc_callback );
629              else
630                  irc_dcc_decline( session, dccid );
631          }
632
633       Note  that  it  is  not possible to request a remote user to send you a
634       file.
635
636   Handling colors
637   Stripping colors from the message
638       If your bot reacts on the text messages, you need  to  strip  down  the
639       colors  from  the  text  messages before processing them. Otherwise the
640       user sending the colored message won't get the  same  reaction  as  the
641       user who doesn't use colors, and some users use colors by default.
642
643       Use  the  irc_color_strip_from_mirc() function to strip the ANSI colors
644       from the text message. It does not modify the message which doesn't use
645       colors.
646
647   Color conversion
648       The  library supports color translation, and can convert colors between
649       the ANSI colors used by the IRC clients and their  textual  representa‐
650       tion.  Colors usage is typically limited to the messages and user spec‐
651       ified reasons. You cannot use colors as part of your  nick  or  channel
652       name.
653
654       Use  the  irc_color_convert_from_mirc() function to convert colors from
655       ANSI  to  the  library  textual  representation,   and   irc_color_con‐
656       vert_to_mirc()  to convert the library textual representation of colors
657       into ANSI.
658
659       Do not forget to free() the returned pointer once it is not  used  any‐
660       more.
661
662   Miscellaneous
663   Tracking user nicks
664       If  your  application maintains some user-specific quotas, it is impor‐
665       tant to track the nick changes. Since the nick is the  only  identifier
666       available  to  you,  each  time  the  user changes the nick you need to
667       update your quota  database.  To  do  so  you  need  to  intercept  the
668       event_nick event. See the examples/censor.c for details.
669

API REFERENCE

671   Callbacks
672       This section describes the callbacks supported by the library.
673
674   irc_event_callback_t
675       Prototype:
676
677       typedef  void  (*irc_event_callback_t)(irc_session_t  * session,  const
678       char * event, const  char  * origin,  const  char  ** params,  unsigned
679       int count)
680
681       Parameters:
682
683                       ┌────────┬────────────────────────────┐
684session │ The   IRC  session,  which │
685                       │        │ generated the event        │
686                       ├────────┼────────────────────────────┤
687event   │ The  text  name   of   the │
688                       │        │ event.  Useful  in  case a │
689                       │        │ single  event  handler  is │
690                       │        │ used  to  handle  multiple │
691                       │        │ events                     │
692                       ├────────┼────────────────────────────┤
693origin  │ The  originator   of   the │
694                       │        │ event.   Depends   on  the │
695                       │        │ event.                     │
696                       ├────────┼────────────────────────────┤
697params  │ Extra parameters, if  any, │
698                       │        │ for this event. The number │
699                       │        │ of    extra     parameters │
700                       │        │ depends  on the event, and │
701                       │        │ may be zero.  Each parame‐ │
702                       │        │ ter  is  a NULL-terminated │
703                       │        │ text string. None  of  the │
704                       │        │ params  can  be  NULL, but │
705                       │        │ the params pointer  itself │
706                       │        │ could  be  NULL  for  some │
707                       │        │ events.                    │
708                       ├────────┼────────────────────────────┤
709count   │ The number of  entries  in │
710                       │        │ the  params  argument sup‐ │
711                       │        │ plied.                     │
712                       └────────┴────────────────────────────┘
713
714       Description:
715
716       Every IRC event generates a callback. This type of callback is  univer‐
717       sal  and  is  used  by  almost  all  IRC events. Depending on the event
718       nature, it can have zero or more parameters.  For each type  of  event,
719       the  number  of  provided  parameters  is  fixed,  and their meaning is
720       described in the irc_callbacks_t structure.
721
722       Every event has an origin (i.e. who  originated  the  event).  In  some
723       cases  the origin variable may be NULL, which indicates that event ori‐
724       gin is unknown. The origin usually looks like nick!host@ircserver, i.e.
725       like  tim!home@irc.server.net. Such origins can not be used in IRC com‐
726       mands, and need to be stripped (i.e. host and server part should be cut
727       off)  before  using.  This  can  be  done  either  manually, by calling
728       irc_target_get_nick(), or automatically for all the events - by setting
729       the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().
730
731   irc_event_dcc_chat_t
732       Prototype:
733
734       typedef  void  (*irc_event_dcc_chat_t)(irc_session_t  * session,  const
735       char * nick, const char * addr, irc_dcc_t dccid)
736
737       Parameters:
738
739                       ┌────────┬────────────────────────────┐
740session │ IRC session, which  gener‐ │
741                       │        │ ates  an  event  (the  one │
742                       │        │ returned    by    irc_cre‐ │
743                       │        │ ate_session)               │
744                       └────────┴────────────────────────────┘
745
746
747
748nick    │ User   who  requested  the │
749                       │        │ chat                       │
750                       ├────────┼────────────────────────────┤
751addr    │ IP address of  the  person │
752                       │        │ such as 189.12.34.56       │
753                       ├────────┼────────────────────────────┤
754dccid   │ Identifier associated with │
755                       │        │ this request which  should │
756                       │        │ be     passed    to    the │
757                       │        │ irc_dcc_accept()         / │
758                       │        │ irc_dcc_decline()    func‐ │
759                       │        │ tions                      │
760                       └────────┴────────────────────────────┘
761
762       Description:
763
764       This callback is called when someone requests DCC CHAT  with  you.  DCC
765       CHAT  is  the  type  of  chat  which goes directly between the clients,
766       instead of going through the IRC server. Since the TCP connection  must
767       be  established  for  it to happen, typically the initiator must either
768       have the public IP or special software on the  firewall  which  handles
769       the necessary port forwarding.
770
771       You must respond to the chat request either by calling irc_dcc_accept()
772       to accept it, or by calling irc_dcc_decline() to decline it.
773
774   irc_event_dcc_send_t
775       Prototype:
776
777       typedef  void  (*irc_event_dcc_send_t)(irc_session_t  * session,  const
778       char  * nick,  const  char  * addr,  const  char  * filename,  unsigned
779       long size, irc_dcc_t dccid)
780
781       Parameters:
782
783                       ┌─────────┬────────────────────────────┐
784session  │ The  IRC  session,   which │
785                       │         │ generates  an  event  (the │
786                       │         │ one returned  by  irc_cre‐ │
787                       │         │ ate_session)               │
788                       ├─────────┼────────────────────────────┤
789nick     │ The user who requested the │
790                       │         │ chat                       │
791                       ├─────────┼────────────────────────────┤
792addr     │ The IP address of the per‐ │
793                       │         │ son such as 189.12.34.56   │
794                       ├─────────┼────────────────────────────┤
795filename │ The  name  of the file the │
796                       │         │ user is trying to send you │
797                       ├─────────┼────────────────────────────┤
798size     │ The size of the file       │
799                       ├─────────┼────────────────────────────┤
800dccid    │ Identifier associated with │
801                       │         │ this  request which should │
802                       │         │ be    passed    to     the │
803                       │         │ irc_dcc_accept()         / │
804                       │         │ irc_dcc_decline()    func‐ │
805                       │         │ tions                      │
806                       └─────────┴────────────────────────────┘
807
808       Description:
809
810       This  callback is called when someone wants to send you a file by using
811       DCC SEND. DCC SEND goes directly between the clients, and requires  the
812       TCP  connection  to be established established for it to happen. There‐
813       fore the initiator must either have the public IP or  special  software
814       on the firewall which handles the necessary port forwarding.
815
816       You must respond to the chat request either by calling irc_dcc_accept()
817       to accept it, or by calling irc_dcc_decline() to decline it.
818
819   irc_dcc_callback_t
820       Prototype:
821
822       typedef     void     (*irc_dcc_callback_t)(irc_session_t     * session,
823       irc_dcc_t id,  int status,  void  * ctx,  const  char  * data, unsigned
824       int length)
825
826       Parameters:
827
828                       ┌────────┬────────────────────────────┐
829session │ The  IRC  session,   which │
830                       │        │ generates  an  event  (the │
831                       │        │ one returned  by  irc_cre‐ │
832                       │        │ ate_session)               │
833                       ├────────┼────────────────────────────┤
834id      │ The DCC session id         │
835                       ├────────┼────────────────────────────┤
836status  │ The DCC connection status. │
837                       │        │ 0 means there is no error, │
838                       │        │ otherwise    contains   an │
839                       │        │ error code                 │
840                       ├────────┼────────────────────────────┤
841ctx     │ The user-provided context  │
842                       ├────────┼────────────────────────────┤
843data    │ Data received  (if  avail‐ │
844                       │        │ able), otherwise NULL      │
845                       ├────────┼────────────────────────────┤
846length  │ Size  of the data received │
847                       │        │ if any data                │
848                       └────────┴────────────────────────────┘
849
850       Description:
851
852       This callback is called for all DCC functions when state change occurs.
853
854       For DCC CHAT, the callback is called as following:
855
856              · status is LIBIRC_ERR_CLOSED: connection is  closed  by  remote
857                peer.  After  returning  from the callback, the DCC session is
858                automatically destroyed
859
860              · status is nonzero but not LIBIRC_ERR_CLOSED: socket I/O  error
861                (connect  error,  accept error, recv error, send error). After
862                returning from the callback, the DCC session is  automatically
863                destroyed
864
865              · status  is  zero  and length is zero: the remote side accepted
866                the chat request
867
868              · status is  zero  and  length  is  nonzero:  new  chat  message
869                received,   data   contains  the  message  (a  null-terminated
870                string), length contains the string length without null termi‐
871                nator
872
873       For  DCC SEND, while file is being sent, the callback is called as fol‐
874       lowing:
875
876              · status is nonzero: socket I/O  error  (connect  error,  accept
877                error, recv error, send error). After returning from the call‐
878                back, the DCC session is automatically destroyed
879
880              · status is zero: another data packet has been sent, length con‐
881                tains the total amount of data sent so far, data is NULL
882
883       For  DCC  RECV, while file is being sending, callback called as follow‐
884       ing:
885
886              · status is nonzero: socket I/O  error  (connect  error,  accept
887                error, recv error, send error). After returning from the call‐
888                back, the DCC session is automatically destroyed.
889
890              · status is zero, and data is NULL: the file has  been  received
891                successfully.  After returning from the callback, the DCC ses‐
892                sion is automatically destroyed.
893
894              · status is zero, and data is not NULL: new data received,  data
895                contains the data received, length contains the amount of data
896                received.
897
898   irc_eventcode_callback_t
899       Prototype:
900
901       typedef   void   (*irc_eventcode_callback_t)(irc_session_t   * session,
902       unsigned int event, const char * origin, const char ** params, unsigned
903       int count)
904
905       Parameters:
906
907                       ┌────────┬────────────────────────────┐
908session │ The  IRC  session,   which │
909                       │        │ generates  an  event  (the │
910                       │        │ one returned  by  irc_cre‐ │
911                       │        │ ate_session)               │
912                       ├────────┼────────────────────────────┤
913event   │ The  numeric  code  of the │
914                       │        │ event. Useful  in  case  a │
915                       │        │ single  event  handler  is │
916                       │        │ used  to  handle  multiple │
917                       │        │ events                     │
918                       ├────────┼────────────────────────────┤
919origin  │ The   originator   of  the │
920                       │        │ event.  Depends   on   the │
921                       │        │ event.                     │
922                       ├────────┼────────────────────────────┤
923params  │ Extra  parameters, if any, │
924                       │        │ for this event. The number │
925                       │        │ of     extra    parameters │
926                       │        │ depends on the event,  and │
927                       │        │ may be zero.  Each parame‐ │
928                       │        │ ter is  a  NULL-terminated │
929                       │        │ text  string.  None of the │
930                       │        │ params can  be  NULL,  but │
931                       │        │ the  params pointer itself │
932                       │        │ could  be  NULL  for  some │
933                       │        │ events.                    │
934                       ├────────┼────────────────────────────┤
935count   │ The  number  of entries in │
936                       │        │ the params  argument  sup‐ │
937                       │        │ plied.                     │
938                       └────────┴────────────────────────────┘
939
940       Description:
941
942       This  is  an  advanced  callback  for  those  who want to handle events
943       deeper. Most times the IRC server replies to your actions with  numeric
944       events.   Most of those events are error codes, and some are list-start
945       and list-stop markers. Every code  has  its  own  set  of  params;  for
946       details  you  can  either  experiment,  or  read RFC 1459 (don't expect
947       servers to follow it closely though).
948
949       Every event has an origin (i.e. who  originated  the  event).  In  some
950       cases  the origin variable may be NULL, which indicates that event ori‐
951       gin is unknown. The origin usually looks like nick!host@ircserver, i.e.
952       like  tim!home@irc.server.net. Such origins can not be used in IRC com‐
953       mands, and need to be stripped (i.e. host and server part should be cut
954       off)  before  using.  This  can  be  done  either  manually, by calling
955       irc_target_get_nick(), or automatically for all the events - by setting
956       the LIBIRC_OPTION_STRIPNICKS option with irc_option_set().
957
958   Functions
959       This  section  describes the functions defined in the library which are
960       grouped by the purpose.
961
962   Library initialization and shutdown
963   irc_create_session
964       Prototype:
965
966       irc_session_t * irc_create_session(irc_callbacks_t * callbacks)
967
968       Parameters:
969
970                      ┌────────────────────────────────────────┐
971callbacks | Event callbacks  structure, │
972                      │which  defines several callbacks, which │
973                      │will be called on  appropriate  events. │
974                      │Cannot be NULL.                         │
975                      └────────────────────────────────────────┘
976
977       Description:
978
979       Creates  and  initiates  a  new IRC session. Every session represents a
980       single user connection to a single IRC server, and possibly to  one  or
981       more users via DCC.  Almost every library function requires this object
982       to be passed to, and therefore this function should  be  called  first.
983       Multiple sessions could be allocated to support multiple connections.
984
985       When it is not needed anymore, the session must be destroyed by calling
986       the irc_destroy_session() function.
987
988       Return value:
989
990       An irc_session_t object, or 0 if creation failed. Usually,  failure  is
991       caused by out of memory error.
992
993       Thread safety:
994
995       This  function can be called simultaneously from multiple threads. Same
996       callback structure may be reused by multiple threads.
997
998   irc_destroy_session
999       Prototype:
1000
1001       void irc_destroy_session(irc_session_t * session)
1002
1003       Parameters:
1004
1005                         ┌─────────────────────────────────┐
1006session | The IRC session handle │
1007                         └─────────────────────────────────┘
1008
1009       Description:
1010
1011       This function destroys an IRC session, closes the connection to the IRC
1012       server,  and  frees all the used resources. After calling this function
1013       you should not use this session object anymore.
1014
1015       Thread safety:
1016
1017       This function can be called simultaneously from multiple threads.
1018
1019   Connecting, disconnecting and running the main event loop
1020   irc_connect6
1021       Prototype:
1022
1023       int irc_connect6(irc_session_t * session, const char * server, unsigned
1024       short port,  const  char  * password,  const  char  * nick,  const char
1025       * username, const char * realname)
1026
1027   irc_connect
1028       Prototype:
1029
1030       int irc_connect(irc_session_t * session, const char * server,  unsigned
1031       short port,  const  char  * password,  const  char  * nick,  const char
1032       * username, const char * realname)
1033
1034       Parameters:
1035
1036                       ┌─────────┬────────────────────────────┐
1037session  │ IRC session handle         │
1038                       ├─────────┼────────────────────────────┤
1039server   │ IP  address  or  the  host │
1040                       │         │ name  of  the  server.  If │
1041                       │         │ prefixed   with   #,   the │
1042                       │         │ library will try to estab‐ │
1043                       │         │ lish  the  SSL  connection │
1044                       │         │ IPv4  address should be in │
1045                       │         │ numeric   form   such   as │
1046                       │         │ 154.23.112.33;        IPv6 │
1047                       │         │ address should be in  IPv6 │
1048                       │         │ form                       │
1049                       ├─────────┼────────────────────────────┤
1050port     │ Port number to connect to, │
1051                       │         │ usually 6667               │
1052                       ├─────────┼────────────────────────────┤
1053password │ IRC  server  password,  if │
1054                       │         │ the  server  requires  it. │
1055                       │         │ May be NULL, in this  case │
1056                       │         │ password  will not be send │
1057                       │         │ to the  IRC  server.  Vast │
1058                       │         │ majority of IRC servers do │
1059                       │         │ not   require   passwords. │
1060                       │         │ This    is    NOT    Nick‐ │
1061                       │         │ Serv/ChanServ password     │
1062                       ├─────────┼────────────────────────────┤
1063nick     │ Nick which will be used to │
1064                       │         │ log  into  the IRC server. │
1065                       │         │ Cannot be NULL             │
1066                       ├─────────┼────────────────────────────┤
1067username │ Username   of   the   Unix │
1068                       │         │ account  which  is used to │
1069                       │         │ connect to the IRC server. │
1070                       │         │ This  is  for  information │
1071                       │         │ only,  will  be  shown  in │
1072                       │         │ "user  properties" dialogs │
1073                       │         │ and  returned  by   /whois │
1074                       │         │ request.  Can  be  NULL in │
1075                       │         │ which case "nobody"  would │
1076                       │         │ be used                    │
1077                       ├─────────┼────────────────────────────┤
1078realname │ A real name of the person, │
1079                       │         │ who connects to  the  IRC. │
1080                       │         │ In   reality  nobody  uses │
1081                       │         │ this   field   for   that. │
1082                       │         │ Instead this field is used │
1083                       │         │ as user  self-description, │
1084                       │         │ advertising, or other pur‐ │
1085                       │         │ poses.  This   information │
1086                       │         │ also   will  be  shown  in │
1087                       │         │ "user properties"  dialogs │
1088                       │         │ and   returned  by  /whois │
1089                       │         │ request. May be  NULL,  in │
1090                       │         │ this case "noname" will be │
1091                       │         │ used                       │
1092                       └─────────┴────────────────────────────┘
1093
1094       Description:
1095
1096       This function initiates the connection to  the  IPv4  (irc_connect)  or
1097       IPv6 (irc_connect6) IRC server. The server could be specified either by
1098       an IP address or by the DNS name.  The irc_connect6 works only  if  the
1099       library was built with the IPv6 support.
1100
1101       If  the  library was built with the OpenSSL support, and the IP address
1102       or the host name is prefixed by a hash, such as "#irc.example.com", the
1103       library attempts to establish the SSL connection.
1104
1105       The  connection is established asynchronously, and the event_connect is
1106       called once the connection is established.
1107
1108       A single IRC session object can only  be  connected  to  a  single  IRC
1109       server  and only with a single nick, meaning it is not possible to have
1110       multiple nicks sharing a single connection.
1111
1112       Return value:
1113
1114       Returns 0 if the connection is  initiated  successfully.  This  doesn't
1115       mean  the  connection is established - the event_connect is called when
1116       it happens. If the connection cannot be established,  either  irc_run()
1117       or irc_process_select_descriptors() will return an error.
1118
1119       Thread safety:
1120
1121       This  function  can be called simultaneously from multiple threads, but
1122       not using the same session object.
1123
1124   irc_disconnect
1125       Prototype:
1126
1127       void irc_disconnect(irc_session_t * session)
1128
1129       Parameters:
1130
1131                          ┌───────────────────────────────┐
1132session   | IRC session handle │
1133                          └───────────────────────────────┘
1134
1135       Description:
1136
1137       This function closes the  IRC  connection.  After  that  connection  is
1138       closed,  if  the  libirc was looped in the irc_run() loop, it automati‐
1139       cally leaves the loop and irc_run() returns.
1140
1141       Thread safety:
1142
1143       This function can be called simultaneously from multiple  threads,  but
1144       not using the same session object.
1145
1146   irc_is_connected
1147       Prototype:
1148
1149       int irc_is_connected(irc_session_t * session)
1150
1151       Parameters:
1152
1153                           ┌────────┬────────────────────┐
1154session │ IRC session handle │
1155                           └────────┴────────────────────┘
1156
1157       Return value:
1158
1159       This  function  returns 1 if the connection to the IRC server is estab‐
1160       lished or 0 if it is not.
1161
1162       Thread safety:
1163
1164       This function can be called simultaneously from multiple threads.
1165
1166   irc_run
1167       Prototype:
1168
1169       int irc_run(irc_session_t * session)
1170
1171       Parameters:
1172
1173                           ┌────────┬────────────────────┐
1174session │ IRC session handle │
1175                           └────────┴────────────────────┘
1176
1177       Description:
1178
1179       This function enters into forever loop, processing the IRC events,  and
1180       calling the relevant callbacks. This function will not return until the
1181       server connection is terminated -  either  by  server,  or  by  calling
1182       irc_cmd_quit. This function should only be used if you use a single IRC
1183       session and don't need asynchronous request processing (i.e.  your  bot
1184       just  reacts  on  the  events, and doesn't generate it asynchronously).
1185       Even in last case, you still can call this function and start the asyn‐
1186       chronous thread in event_connect handler.  See the examples.
1187
1188       Return value:
1189
1190       This  function  returns  a  nonzero  value if the connection to the IRC
1191       server could not be established, or was terminated.
1192
1193       Thread safety:
1194
1195       This  function  cannot   be   called   from   multiple   threads.   Use
1196       irc_add_select_descriptors()    and    irc_process_select_descriptors()
1197       instead.
1198
1199   irc_add_select_descriptors
1200       Prototype:
1201
1202       int irc_add_select_descriptors(irc_session_t * session, fd_set *in_set,
1203       fd_set *out_set, int * maxfd)
1204
1205       Parameters:
1206
1207                       ┌────────┬────────────────────────────┐
1208session │ IRC session handle         │
1209                       ├────────┼────────────────────────────┤
1210in_set  │ fd_set   input  descriptor │
1211                       │        │ set for select()           │
1212                       ├────────┼────────────────────────────┤
1213out_set │ fd_set  output  descriptor │
1214                       │        │ set for select()           │
1215                       ├────────┼────────────────────────────┤
1216maxfd   │ Largest descriptor already │
1217                       │        │ in all the sets.  Will  be │
1218                       │        │ updated   if  libirc  adds │
1219                       │        │ larger   number   to   the │
1220                       │        │ FD_SET array               │
1221                       └────────┴────────────────────────────┘
1222
1223       Description:
1224
1225       This function should be used after you called irc_connect(). It is use‐
1226       ful when you have your own select-based event processing loop.  To  use
1227       it  you  should put your own descriptors into the sets, call this func‐
1228       tion to add the library descriptor(s)  into  the  set,  and  then  call
1229       select().  When it returns, you should call irc_process_select_descrip‐
1230       tors() which will handle the events and calls your  callbacks(!).  Then
1231       you can process your sockets events from set. See the example.
1232
1233       What if you use epoll? See the FAQ
1234
1235       Return value:
1236
1237       This  function  returns  a  nonzero  value if the irc_connect() was not
1238       called before calling this function.
1239
1240       Thread safety:
1241
1242       This function can be called simultaneously from multiple  threads,  but
1243       it rarely makes sense.
1244
1245   irc_process_select_descriptors
1246       Prototype:
1247
1248       int       irc_process_select_descriptors(irc_session_t       * session,
1249       fd_set *in_set, fd_set *out_set)
1250
1251       Parameters:
1252
1253                       ┌────────┬────────────────────────────┐
1254session │ IRC session handle         │
1255                       ├────────┼────────────────────────────┤
1256in_set  │ fd_set  input   descriptor │
1257                       │        │ set for select()           │
1258                       ├────────┼────────────────────────────┤
1259out_set │ fd_set  output  descriptor │
1260                       │        │ set for select()           │
1261                       └────────┴────────────────────────────┘
1262
1263       Description:
1264
1265       This function should be used in pair with  irc_add_select_descriptors()
1266       function, which documentation describes how they work together.
1267
1268       Note  that  while  processing the events this function calls your call‐
1269       backs and it will not return until all your callbacks return. Keep that
1270       in  mind if you pop up a dialog in your application, such as a DCC CHAT
1271       or DCC SEND confirmation dialog.
1272
1273       Return value:
1274
1275       Return code 0 means success. Other value means error,  the  error  code
1276       may be obtained through irc_errno().
1277
1278       Thread safety:
1279
1280       This  function  can  be called simultaneously from multiple threads for
1281       different IRC session objects only.
1282
1283   Managing the IRC channels: joining, leaving, inviting
1284   irc_cmd_join
1285       Prototype:
1286
1287       int irc_cmd_join(irc_session_t * session, const char  * channel,  const
1288       char * key)
1289
1290       Parameters:
1291
1292                       ┌────────┬────────────────────────────┐
1293session │ IRC session handle         │
1294                       ├────────┼────────────────────────────┤
1295channel │ Channel name to join. Can‐ │
1296                       │        │ not be NULL.               │
1297                       ├────────┼────────────────────────────┤
1298key     │ Secret key for  the  chan‐ │
1299                       │        │ nel.  Can  be  NULL if not │
1300                       │        │ needed                     │
1301                       └────────┴────────────────────────────┘
1302
1303       Description:
1304
1305       Use this function to join the new IRC channel. If the channel does  not
1306       exist,  it  will be automatically created by the IRC server.  Note that
1307       to JOIN the password-protected channel, you must know the password, and
1308       specify  it in the key argument.  If join is successful, the event_join
1309       will be called (with your nick  as  the  origin),  then  typically  the
1310       event_topic is be called and then you receive the list of users who are
1311       on the channel (by using LIBIRC_RFC_RPL_NAMREPLY), which  will  include
1312       the user who just joined.
1313
1314       Return value:
1315
1316       Return  code  0  means  the command was sent to the IRC server success‐
1317       fully. This does not mean the operation succeed, and you need  to  wait
1318       for  the  appropriate  event  or  for  the error code via event_numeric
1319       event.
1320
1321       Possible error responces for this command from the RFC1459:
1322
1323              · LIBIRC_RFC_ERR_BANNEDFROMCHAN
1324
1325              · LIBIRC_RFC_ERR_INVITEONLYCHAN
1326
1327              · LIBIRC_RFC_ERR_BADCHANNELKEY
1328
1329              · LIBIRC_RFC_ERR_CHANNELISFULL
1330
1331              · LIBIRC_RFC_ERR_BADCHANMASK
1332
1333              · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1334
1335              · LIBIRC_RFC_ERR_TOOMANYCHANNELS
1336
1337       Thread safety:
1338
1339       This function can be called simultaneously from multiple threads.
1340
1341   irc_cmd_part
1342       Prototype:
1343
1344       int irc_cmd_part(irc_session_t * session, const char * channel)
1345
1346       Parameters:
1347
1348                       ┌────────┬────────────────────────────┐
1349session │ IRC session handle         │
1350                       ├────────┼────────────────────────────┤
1351channel │ Channel  name  to   leave. │
1352                       │        │ Cannot be NULL.            │
1353                       └────────┴────────────────────────────┘
1354
1355       Description:
1356
1357       Use this function to leave the IRC channel you've already joined to. An
1358       attempt   to   leave   the   channel   you   aren't   in   results    a
1359       LIBIRC_RFC_ERR_NOTONCHANNEL server error.
1360
1361       Return value:
1362
1363       Return  code  0  means  the command was sent to the IRC server success‐
1364       fully. This does not mean the operation succeed, and you need  to  wait
1365       for  the  appropriate  event  or  for  the error code via event_numeric
1366       event.
1367
1368       Possible error responces for this command from the RFC1459:
1369
1370              · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1371
1372              · LIBIRC_RFC_ERR_NOTONCHANNEL
1373
1374       Thread safety:
1375
1376       This function can be called simultaneously from multiple threads.
1377
1378   irc_cmd_invite
1379       Prototype:
1380
1381       int irc_cmd_invite(irc_session_t * session, const  char  * nick,  const
1382       char * channel)
1383
1384       Parameters:
1385
1386                       ┌────────┬────────────────────────────┐
1387session │ IRC session handle         │
1388                       ├────────┼────────────────────────────┤
1389nick    │ Nick  name  of the user to │
1390                       │        │ invite                     │
1391                       ├────────┼────────────────────────────┤
1392channel │ Channel name to join. Can‐ │
1393                       │        │ not be NULL                │
1394                       └────────┴────────────────────────────┘
1395
1396       Description:
1397
1398       This  function  is  used  to  invite  someone  to  invite-only channel.
1399       "Invite-only"  is  a  channel  mode,  which  restricts  anyone,  except
1400       invided,  to  join this channel.  After invitation, the user could join
1401       this channel. The user, who is invited, will receive  the  event_invite
1402       event. Note that you must be a channel operator to invite the users.
1403
1404       Return value:
1405
1406       Return  code  0  means  the command was sent to the IRC server success‐
1407       fully. This does not mean the operation succeed, and you need  to  wait
1408       for  the  appropriate  event  or  for  the error code via event_numeric
1409       event.
1410
1411       On success one of the following replies returned:
1412
1413              · LIBIRC_RFC_RPL_INVITING
1414
1415              · LIBIRC_RFC_RPL_AWAY
1416
1417       Possible error responces for this command from the RFC1459:
1418
1419              · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1420
1421              · LIBIRC_RFC_ERR_NOSUCHNICK
1422
1423              · LIBIRC_RFC_ERR_NOTONCHANNEL
1424
1425              · LIBIRC_RFC_ERR_ERR_USERONCHANNEL
1426
1427              · LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED
1428
1429       Thread safety:
1430
1431       This function can be called simultaneously from multiple threads.
1432
1433   irc_cmd_names
1434       Prototype:
1435
1436       int irc_cmd_names (irc_session_t * session, const char * channel);
1437
1438       Parameters:
1439
1440                       ┌────────┬────────────────────────────┐
1441session │ IRC session handle         │
1442                       └────────┴────────────────────────────┘
1443
1444
1445
1446channel │ A   channel   name(s)   to │
1447                       │        │ obtain user list. Multiple │
1448                       │        │ channel names must be sep‐ │
1449                       │        │ arated by a comma          │
1450                       └────────┴────────────────────────────┘
1451
1452       Description:
1453
1454       This  function  is  used  to  to ask the IRC server for the list of the
1455       users who are joined the specified channel. You can list all  nicknames
1456       that  are  visible  to you on any channel that you can see. The list of
1457       users   will   be   returned    using    LIBIRC_RFC_RPL_NAMREPLY    and
1458       LIBIRC_RFC_RPL_ENDOFNAMES numeric codes.
1459
1460       Return value:
1461
1462       Return  code  0  means  the command was sent to the IRC server success‐
1463       fully. This does not mean the operation succeed, and you need  to  wait
1464       for  the  appropriate  event  or  for  the error code via event_numeric
1465       event.
1466
1467       The channel names are returned by event_numeric event using the follow‐
1468       ing reply codes:
1469
1470              · LIBIRC_RFC_RPL_NAMREPLY
1471
1472              · LIBIRC_RFC_RPL_ENDOFNAMES
1473
1474       Thread safety:
1475
1476       This function can be called simultaneously from multiple threads.
1477
1478   irc_cmd_list
1479       Prototype:
1480
1481       int irc_cmd_list(irc_session_t * session, const char * channel)
1482
1483       Parameters:
1484
1485                       ┌────────┬────────────────────────────┐
1486session │ IRC session handle         │
1487                       ├────────┼────────────────────────────┤
1488channel │ A channel name(s) to list. │
1489                       │        │ Multiple   channel   names │
1490                       │        │ must  be  separated  by  a │
1491                       │        │ comma. If NULL, all  chan‐ │
1492                       │        │ nels are listed            │
1493                       └────────┴────────────────────────────┘
1494
1495       Description:
1496
1497       This  function  is used to ask the IRC server for the active (existing)
1498       channels list. The list will be returned using the LIBIRC_RFC_RPL_LIST‐
1499       START,  multiple  LIBIRC_RFC_RPL_LIST, and LIBIRC_RFC_RPL_LISTEND event
1500       sequence. Note that "private" channels are listed (without  their  top‐
1501       ics)  as  channel  "Prv" unless the client generating the LIST query is
1502       actually on that channel. Likewise, secret channels are not  listed  at
1503       all unless the client is active at the channel in question.
1504
1505       Return value:
1506
1507       Return  code  0  means  the command was sent to the IRC server success‐
1508       fully. This does not mean the operation succeed, and you need  to  wait
1509       for  the  appropriate  event  or  for  the error code via event_numeric
1510       event.
1511
1512       The list of channels is returned by event_numeric event using the  fol‐
1513       lowing reply codes:
1514
1515              · LIBIRC_RFC_RPL_LISTSTART
1516
1517              · LIBIRC_RFC_RPL_LISTEND
1518
1519              · LIBIRC_RFC_RPL_LIST
1520
1521       Thread safety:
1522
1523       This function can be called simultaneously from multiple threads.
1524
1525   irc_cmd_topic
1526       Prototype:
1527
1528       int  irc_cmd_topic(irc_session_t * session, const char * channel, const
1529       char * topic)
1530
1531       Parameters:
1532
1533                       ┌────────┬────────────────────────────┐
1534session │ IRC session handle         │
1535                       ├────────┼────────────────────────────┤
1536channel │ A channel name             │
1537                       ├────────┼────────────────────────────┤
1538topic   │ A new  channel  topic.  If │
1539                       │        │ NULL,  the old topic would │
1540                       │        │ be  returned  and  nothing │
1541                       │        │ would  change.  To set the │
1542                       │        │ empty topic use ""         │
1543                       └────────┴────────────────────────────┘
1544
1545       Description:
1546
1547       This function is used to change or view the topic (title) of a channel.
1548       Note  that  depending  on  +t channel mode, you may be required to be a
1549       channel operator to change the channel topic.
1550
1551       If  the  command   succeeds,   the   IRC   server   will   generate   a
1552       LIBIRC_RFC_RPL_NOTOPIC   or  LIBIRC_RFC_RPL_TOPIC  message,  containing
1553       either the old or changed topic. Also the IRC server can (but does  not
1554       have  to) generate the non-RFC LIBIRC_RFC_RPL_TOPIC_EXTRA message, con‐
1555       taining the nick of person who changed the topic, and the date/time  of
1556       the last change.
1557
1558       Return value:
1559
1560       Return  code  0  means  the command was sent to the IRC server success‐
1561       fully. This does not mean the operation succeed, and you need  to  wait
1562       for  the  appropriate  event  or  for  the error code via event_numeric
1563       event.
1564
1565       The topic information is returned using one of following reply codes:
1566
1567              · LIBIRC_RFC_RPL_NOTOPIC
1568
1569              · LIBIRC_RFC_RPL_TOPIC
1570
1571       If the topic change was requested and it was successfully changed,  the
1572       event_topic is generated as well.
1573
1574       Possible error responces for this command from the RFC1459:
1575
1576              · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1577
1578              · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1579
1580              · LIBIRC_RFC_ERR_NOTONCHANNEL
1581
1582       Thread safety:
1583
1584       This function can be called simultaneously from multiple threads.
1585
1586   irc_cmd_channel_mode
1587       Prototype:
1588
1589       int irc_cmd_channel_mode(irc_session_t * session, const char * channel,
1590       const char * mode)
1591
1592       Parameters:
1593
1594                       ┌────────┬────────────────────────────┐
1595session │ IRC session handle         │
1596                       ├────────┼────────────────────────────┤
1597channel │ A channel name             │
1598                       ├────────┼────────────────────────────┤
1599mode    │ A mode to change. If NULL, │
1600                       │        │ the  channel  mode  is not │
1601                       │        │ changed but the  old  mode │
1602                       │        │ is returned                │
1603                       └────────┴────────────────────────────┘
1604
1605       Description:
1606
1607       This  function  is used to is used to change or view the channel modes.
1608       Note that only the channel operators can change the channel mode.
1609
1610       Channel mode is represended by the multiple letters combination.  Every
1611       letter  has its own meaning in channel modes. Most channel mode letters
1612       are boolean (i.e. could only be set or reset), but a few  channel  mode
1613       letters  accept  a  parameter.  All channel options are set by adding a
1614       plus sign before the letter, and reset by adding a  minus  sign  before
1615       the letter.
1616
1617       Here is the list of 'standard' channel modes:
1618
1619                      ┌───────────┬────────────────────────────┐
1620                      │o nickname │ gives (+o nickname) to, or │
1621                      │           │ takes  (-o  nickname)  the │
1622                      │           │ channel   operator  privi‐ │
1623                      │           │ leges  from  a   nickname. │
1624                      │           │ This   mode   affects  the │
1625                      │           │ users in channel, not  the │
1626                      │           │ channel  itself. Examples: │
1627                      │           │ "+o tim", "-o watson"      │
1628                      ├───────────┼────────────────────────────┤
1629                      │p          │ sets (+p) or  resets  (-p) │
1630                      │           │ private channel flag. Pri‐ │
1631                      │           │ vate channels are shown in │
1632                      │           │ channel   list  as  'Prv', │
1633                      │           │ without the topic          │
1634                      ├───────────┼────────────────────────────┤
1635                      │s          │ sets (+s) or  resets  (-s) │
1636                      │           │ secret    channel    flag. │
1637                      │           │ Secret   channels   aren't │
1638                      │           │ shown  in  channel list at │
1639                      │           │ all                        │
1640                      ├───────────┼────────────────────────────┤
1641                      │i          │ sets (+i) or  resets  (-i) │
1642                      │           │ invite-only  channel flag. │
1643                      │           │ When the flag is set, only │
1644                      │           │ the people who are invited │
1645                      │           │ by  the   irc_cmd_invite() 
1646                      │           │ can join this channel      │
1647                      ├───────────┼────────────────────────────┤
1648                      │t          │ allows (+t) or denies (-t) │
1649                      │           │ changing the topic by  the │
1650                      │           │ non-channel       operator │
1651                      │           │ users. When  the  flag  is │
1652                      │           │ set,   only   the  channel │
1653                      │           │ operators can  change  the │
1654                      │           │ channel topic              │
1655                      └───────────┴────────────────────────────┘
1656
1657
1658
1659
1660
1661                      │n          │ sets  (+n)  or resets (-n) │
1662                      │           │ the  protection  from  the │
1663                      │           │ users who did not join the │
1664                      │           │ channel. When the +n  mode │
1665                      │           │ is set, only the users who │
1666                      │           │ have  joined  the  channel │
1667                      │           │ can  send  the messages to │
1668                      │           │ the channel                │
1669                      ├───────────┼────────────────────────────┤
1670                      │m          │ sets (+m) or  resets  (-m) │
1671                      │           │ the   moderation   of  the │
1672                      │           │ channel. When the  modera‐ │
1673                      │           │ tion  mode  is  set,  only │
1674                      │           │ channel operators and  the │
1675                      │           │ users  who  have  +v  user │
1676                      │           │ mode  can  speak  in   the │
1677                      │           │ channel                    │
1678                      ├───────────┼────────────────────────────┤
1679                      │v nickname │ gives  (+v  nick) or takes │
1680                      │           │ (-v nick)  from  user  the │
1681                      │           │ ability to speak on a mod‐ │
1682                      │           │ erated channel.  Examples: │
1683                      │           │ "+v bob", "-v joy"         │
1684                      ├───────────┼────────────────────────────┤
1685                      │l number   │ sets  (+l  20)  or removes │
1686                      │           │ (-l)  the  restriction  of │
1687                      │           │ maximum  number  of  users │
1688                      │           │ allowed in  channel.  When │
1689                      │           │ the restriction is set and │
1690                      │           │ there is a number of users │
1691                      │           │ in the channel, no one can │
1692                      │           │ join the channel anymore   │
1693                      ├───────────┼────────────────────────────┤
1694                      │k key      │ sets  (+k   password)   or │
1695                      │           │ removes  (-k) the password │
1696                      │           │ from the channel. When the │
1697                      │           │ restriction  is  set,  any │
1698                      │           │ user joining  the  channel │
1699                      │           │ required   to   provide  a │
1700                      │           │ channel key                │
1701                      ├───────────┼────────────────────────────┤
1702                      │b mask     │ sets   (+b   !*@.mil)   or │
1703                      │           │ removes  (-b  !*@.mil) the │
1704                      │           │ ban mask on a user to keep │
1705                      │           │ him  out  of channel. Note │
1706                      │           │ that to remove the ban you │
1707                      │           │ must  specify the ban mask │
1708                      │           │ to remove, not just "-b".  │
1709                      └───────────┴────────────────────────────┘
1710
1711       Note that the actual list of channel modes depends on the  IRC  server,
1712       and  can  be bigger. If you know the popular channel modes which aren't
1713       listed here - please contact me
1714
1715       Return value:
1716
1717       Return code 0 means the command was sent to  the  IRC  server  success‐
1718       fully.  This  does not mean the operation succeed, and you need to wait
1719       for the appropriate event or  for  the  error  code  via  event_numeric
1720       event.
1721
1722       The old mode information is returned by using following numeric codes:
1723
1724              · LIBIRC_RFC_RPL_CHANNELMODEIS
1725
1726              · LIBIRC_RFC_RPL_BANLIST
1727
1728              · LIBIRC_RFC_RPL_ENDOFBANLIST
1729
1730       Possible error responces for this command from the RFC1459:
1731
1732              · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1733
1734              · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1735
1736              · LIBIRC_RFC_ERR_NOSUCHNICK
1737
1738              · LIBIRC_RFC_ERR_NOTONCHANNEL
1739
1740              · LIBIRC_RFC_ERR_KEYSET
1741
1742              · LIBIRC_RFC_ERR_UNKNOWNMODE
1743
1744              · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1745
1746       Thread safety:
1747
1748       This function can be called simultaneously from multiple threads.
1749
1750   irc_cmd_user_mode
1751       Prototype:
1752
1753       int irc_cmd_user_mode(irc_session_t * session, const char * mode)
1754
1755       Parameters:
1756
1757                       ┌────────┬────────────────────────────┐
1758session │ IRC session handle         │
1759                       ├────────┼────────────────────────────┤
1760mode    │ A mode to change. If NULL, │
1761                       │        │ the  user  mode   is   not │
1762                       │        │ changed  but  the old mode │
1763                       │        │ is returned                │
1764                       └────────┴────────────────────────────┘
1765
1766       Description:
1767
1768       This function is used to change or view  the  user  modes.  Note  that,
1769       unlike channel modes, some user modes cannot be changed at all.
1770
1771       User  mode is represended by the letters combination. All the user mode
1772       letters are boolean (i.e. could only be set or reset), they are set  by
1773       adding  a plus sign before the letter, and reset by adding a minus sign
1774       before the letter.
1775
1776       Here is the list of 'standard' user modes:
1777
1778                          ┌──┬────────────────────────────┐
1779                          │o │ represents an IRC operator │
1780                          │  │ status.  Could  not be set │
1781                          │  │ directly (but can be reset │
1782                          │  │ though), to set it use the │
1783                          │  │ IRC a OPER command         │
1784                          ├──┼────────────────────────────┤
1785                          │i │ if set, marks  a  user  as │
1786                          │  │ 'invisible' - that is, not │
1787                          │  │ seen  by  lookups  if  the │
1788                          │  │ user is not in a channel   │
1789                          ├──┼────────────────────────────┤
1790                          │w │ if  set,  marks  a user as │
1791                          │  │ 'receiving wallops' - spe‐ │
1792                          │  │ cial messages generated by │
1793                          │  │ IRC operators  using  WAL‐ │
1794                          │  │ LOPS command               │
1795                          ├──┼────────────────────────────┤
1796                          │s │ if  set,  marks a user for │
1797                          │  │ receipt of server notices  │
1798                          ├──┼────────────────────────────┤
1799                          │r │ NON-STANDARD MODE. If set, │
1800                          │  │ user  has  been  authenti‐ │
1801                          │  │ cated  with  the  NickServ │
1802                          │  │ IRC service                │
1803                          └──┴────────────────────────────┘
1804
1805
1806
1807                          │x │ NON-STANDARD MODE. If set, │
1808                          │  │ user's real IP  is  masked │
1809                          │  │ by the IRC server          │
1810                          └──┴────────────────────────────┘
1811
1812       Note  that the actual list of user modes depends on the IRC server, and
1813       can be bigger. If you know the popular user modes,  which  aren't  men‐
1814       tioned here - please contact me.
1815
1816       Return value:
1817
1818       Return  code  0  means  the command was sent to the IRC server success‐
1819       fully. This does not mean the operation succeed, and you need  to  wait
1820       for  the  appropriate  event  or  for  the error code via event_numeric
1821       event.
1822
1823       The old  mode  information  is  returned  by  using  the  numeric  code
1824       LIBIRC_RFC_RPL_UMODEIS:
1825
1826       Possible error responces for this command from the RFC1459:
1827
1828              · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1829
1830              · LIBIRC_RFC_ERR_NOSUCHNICK
1831
1832              · LIBIRC_RFC_ERR_UNKNOWNMODE
1833
1834              · LIBIRC_RFC_ERR_USERSDONTMATCH
1835
1836              · LIBIRC_RFC_ERR_UMODEUNKNOWNFLAG
1837
1838       Thread safety:
1839
1840       This function can be called simultaneously from multiple threads.
1841
1842   irc_cmd_kick
1843       Prototype:
1844
1845       int  irc_cmd_kick  (irc_session_t  *  session, const char * nick, const
1846       char * channel, const char * reason);
1847
1848       Parameters:
1849
1850                       ┌────────┬────────────────────────────┐
1851session │ IRC session handle         │
1852                       ├────────┼────────────────────────────┤
1853nick    │ The nick to kick           │
1854                       ├────────┼────────────────────────────┤
1855channel │ The channel  to  kick  the │
1856                       │        │ nick from                  │
1857                       ├────────┼────────────────────────────┤
1858nick    │ If not NULL, the reason to │
1859                       │        │ kick the user              │
1860                       └────────┴────────────────────────────┘
1861
1862       Description:
1863
1864       This function is used to kick a person out of channel.  Note  that  you
1865       must be a channel operator to kick anyone from a channel.
1866
1867       Return value:
1868
1869       Return  code  0  means  the command was sent to the IRC server success‐
1870       fully. This does not mean the operation succeed, and you need  to  wait
1871       for  the  appropriate  event  or  for  the error code via event_numeric
1872       event.
1873
1874       If the command succeed, the event_kick will be generated.
1875
1876       If the command failed, one of  the  following  event_numeric  responses
1877       will be generated:
1878
1879              · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1880
1881              · LIBIRC_RFC_ERR_BADCHANMASK
1882
1883              · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1884
1885              · LIBIRC_RFC_ERR_NOTONCHANNEL
1886
1887              · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1888
1889       Thread safety:
1890
1891       This function can be called simultaneously from multiple threads.
1892
1893   Sending the messages, notices, /me messages and working with CTCP
1894   irc_cmd_msg
1895       Prototype:
1896
1897       int  irc_cmd_msg(irc_session_t  * session, const char * nch, const char
1898       * text)
1899
1900       Parameters:
1901
1902                       ┌────────┬────────────────────────────┐
1903session │ IRC session handle         │
1904                       ├────────┼────────────────────────────┤
1905nch     │ Target  nick   or   target │
1906                       │        │ channel                    │
1907                       ├────────┼────────────────────────────┤
1908text    │ Message text               │
1909                       └────────┴────────────────────────────┘
1910
1911       Description:
1912
1913       This  function  is used to send the message to the channel or privately
1914       to another nick. "Privately" here means the message is  not  posted  to
1915       the public, but the message still goes through the IRC server and could
1916       be seen by the IRC netwrk operators. The message target  is  determined
1917       by  the  nch argument: if it is a nick, this will be a private message,
1918       but if it is a channel name it will be posted into the channel.
1919
1920       The protocol does not require you to join the channel to post the  mes‐
1921       sage  into  it,  but  most channels set the channel mode preventing you
1922       from posting into a channel unless you join it.
1923
1924       Return value:
1925
1926       Return code 0 means the command was sent to  the  IRC  server  success‐
1927       fully.  This  does not mean the operation succeed. You need to wait for
1928       the appropriate event or for the error code via event_numeric event.
1929
1930       If the command succeed, no event is typically generated except the pos‐
1931       sibility of LIBIRC_RFC_RPL_AWAY.
1932
1933       However  if the command failed, one of the following numeric events may
1934       be generated:
1935
1936              · LIBIRC_RFC_ERR_NORECIPIENT
1937
1938              · LIBIRC_RFC_ERR_NOTEXTTOSEND
1939
1940              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1941
1942              · LIBIRC_RFC_ERR_NOTONCHANNEL
1943
1944              · LIBIRC_RFC_ERR_NOTOPLEVEL
1945
1946              · LIBIRC_RFC_ERR_WILDTOPLEVEL
1947
1948              · LIBIRC_RFC_ERR_TOOMANYTARGETS
1949
1950              · LIBIRC_RFC_ERR_NOSUCHNICK
1951
1952       Thread safety:
1953
1954       This function can be called simultaneously from multiple threads.
1955
1956   irc_cmd_me
1957       Prototype:
1958
1959       int irc_cmd_me(irc_session_t * session, const char  * nch,  const  char
1960       * text)
1961
1962       Parameters:
1963
1964                       ┌────────┬────────────────────────────┐
1965session │ IRC session handle         │
1966                       ├────────┼────────────────────────────┤
1967nch     │ Target   nick   or  target │
1968                       │        │ channel                    │
1969                       ├────────┼────────────────────────────┤
1970text    │ Message text               │
1971                       └────────┴────────────────────────────┘
1972
1973       Description:
1974
1975       This function is used to send the /me  message  (CTCP  ACTION)  to  the
1976       channel  or  privately to another nick. "Privately" here means the mes‐
1977       sage is not posted to the public, but the message  still  goes  through
1978       the  IRC server and could be seen by the IRC netwrk operators. The mes‐
1979       sage target is determined by the nch argument: if it is  a  nick,  this
1980       will  be  a  private  message,  but  if it is a channel name it will be
1981       posted into the channel.
1982
1983       The protocol does not require you to join the channel to post the  mes‐
1984       sage  into  it,  but  most channels set the channel mode preventing you
1985       from posting into a channel unless you join it.
1986
1987       Return value:
1988
1989       Return code 0 means the command was sent to  the  IRC  server  success‐
1990       fully.  This  does not mean the operation succeed. You need to wait for
1991       the appropriate event or for the error code via event_numeric event.
1992
1993       If the command succeed, no event is typically generated except the pos‐
1994       sibility of LIBIRC_RFC_RPL_AWAY.
1995
1996       However  if the command failed, one of the following numeric events may
1997       be generated:
1998
1999              · LIBIRC_RFC_ERR_NORECIPIENT
2000
2001              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2002
2003              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2004
2005              · LIBIRC_RFC_ERR_NOTONCHANNEL
2006
2007              · LIBIRC_RFC_ERR_NOTOPLEVEL
2008
2009              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2010
2011              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2012
2013              · LIBIRC_RFC_ERR_NOSUCHNICK
2014
2015       Thread safety:
2016
2017       This function can be called simultaneously from multiple threads.
2018
2019   irc_cmd_notice
2020       Prototype:
2021
2022       int irc_cmd_notice(irc_session_t * session,  const  char  * nch,  const
2023       char * text)
2024
2025       Parameters:
2026
2027
2028
2029                       ┌────────┬────────────────────────────┐
2030session │ IRC session handle         │
2031                       ├────────┼────────────────────────────┤
2032nch     │ Target   nick   or  target │
2033                       │        │ channel                    │
2034                       ├────────┼────────────────────────────┤
2035text    │ Message text               │
2036                       └────────┴────────────────────────────┘
2037
2038       Description:
2039
2040       This function is used to send the notice to the channel or privately to
2041       another  nick.  "Privately" here means the message is not posted to the
2042       public, but the message still goes through the IRC server and could  be
2043       seen  by  the IRC netwrk operators. The message target is determined by
2044       the nch argument: if it is a nick, this will be a private message,  but
2045       if it is a channel name it will be posted into the channel.
2046
2047       The  protocol  does  not  require  you  to join the channel to post the
2048       notice into it, but most channels set the channel mode  preventing  you
2049       from posting into a channel unless you join it.
2050
2051       The  only  difference  between  a  message and a notice is that the RFC
2052       explicitly says the automatic bots must not reply to  NOTICE  automati‐
2053       cally.
2054
2055       Return value:
2056
2057       Return  code  0  means  the command was sent to the IRC server success‐
2058       fully. This does not mean the operation succeed, and you need  to  wait
2059       for  the  appropriate  event  or  for  the error code via event_numeric
2060       event.
2061
2062       If the command succeed, no event is typically generated except the pos‐
2063       sibility of LIBIRC_RFC_RPL_AWAY.
2064
2065       However  if the command failed, one of the following numeric events may
2066       be generated:
2067
2068              · LIBIRC_RFC_ERR_NORECIPIENT
2069
2070              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2071
2072              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2073
2074              · LIBIRC_RFC_ERR_NOTONCHANNEL
2075
2076              · LIBIRC_RFC_ERR_NOTOPLEVEL
2077
2078              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2079
2080              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2081
2082              · LIBIRC_RFC_ERR_NOSUCHNICK
2083
2084       Thread safety:
2085
2086       This function can be called simultaneously from multiple threads.
2087
2088   irc_cmd_ctcp_request
2089       Prototype:
2090
2091       int irc_cmd_ctcp_request(irc_session_t * session,  const  char  * nick,
2092       const char * request)
2093
2094       Parameters:
2095
2096                           ┌────────┬────────────────────┐
2097session │ IRC session handle │
2098                           ├────────┼────────────────────┤
2099nick    │ Target nick        │
2100                           └────────┴────────────────────┘
2101
2102
2103request │ CTCP request tex   │
2104                           └────────┴────────────────────┘
2105
2106       Description:
2107
2108       This  function  is  used  to  send  a CTCP request. There are four CTCP
2109       requests supported by most IRC clients:
2110
2111          · VERSION - get the client software name and version
2112
2113          · FINGER  - get the client username, host and real name.
2114
2115          · PING    - get the client delay.
2116
2117          · TIME    - get the client local time.
2118
2119       Some clients may support other requests. The  RFC  does  not  list  the
2120       requests and does not mandate any CTCP support.
2121
2122       If  you send the CTCP request, make sure you define the handler for the
2123       event_ctcp_rep to process the reply;
2124
2125       Return value:
2126
2127       Return code 0 means the command was sent to  the  IRC  server  success‐
2128       fully.  This  does not mean the operation succeed, and you need to wait
2129       for the appropriate event or  for  the  error  code  via  event_numeric
2130       event.
2131
2132       Possible error responces for this command from the RFC1459:
2133
2134              · LIBIRC_RFC_ERR_NORECIPIENT
2135
2136              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2137
2138              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2139
2140              · LIBIRC_RFC_ERR_NOTONCHANNEL
2141
2142              · LIBIRC_RFC_ERR_NOTOPLEVEL
2143
2144              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2145
2146              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2147
2148              · LIBIRC_RFC_ERR_NOSUCHNICK
2149
2150       Thread safety:
2151
2152       This function can be called simultaneously from multiple threads.
2153
2154   irc_cmd_ctcp_reply
2155       Prototype:
2156
2157       int  irc_cmd_ctcp_reply(irc_session_t  * session,  const  char  * nick,
2158       const char * reply)
2159
2160       Parameters:
2161
2162                           ┌────────┬────────────────────┐
2163session │ IRC session handle │
2164                           ├────────┼────────────────────┤
2165nick    │ Target nick        │
2166                           ├────────┼────────────────────┤
2167reply   │ CTCP reply         │
2168                           └────────┴────────────────────┘
2169
2170       Description:
2171
2172       This function is used to send a reply to the CTCP request received from
2173       event_ctcp_req  event. Note that you will not receive this event unless
2174       you specify your own handler during the IRC session initialization.
2175
2176       Return value:
2177
2178       Return code 0 means the command was sent to  the  IRC  server  success‐
2179       fully.  This  does not mean the operation succeed, and you need to wait
2180       for the appropriate event or  for  the  error  code  via  event_numeric
2181       event.
2182
2183       Possible error responces for this command from the RFC1459:
2184
2185              · LIBIRC_RFC_ERR_NORECIPIENT
2186
2187              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2188
2189              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2190
2191              · LIBIRC_RFC_ERR_NOTONCHANNEL
2192
2193              · LIBIRC_RFC_ERR_NOTOPLEVEL
2194
2195              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2196
2197              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2198
2199              · LIBIRC_RFC_ERR_NOSUCHNICK
2200
2201       Thread safety:
2202
2203       This function can be called simultaneously from multiple threads.
2204
2205   Miscellaneous: library version, raw data, changing nick, quitting
2206   irc_cmd_nick
2207       Prototype:
2208
2209       int irc_cmd_nick(irc_session_t * session, const char * newnick)
2210
2211       Parameters:
2212
2213                           ┌────────┬────────────────────┐
2214session │ IRC session handle │
2215                           ├────────┼────────────────────┤
2216nick    │ New nick           │
2217                           └────────┴────────────────────┘
2218
2219       Description:
2220
2221       This function is used to change your current nick to another nick. Note
2222       that such a change is not  always  possible;  for  example  you  cannot
2223       change  nick  to  the existing nick, or (on some servers) to the regis‐
2224       tered nick.
2225
2226       Return value:
2227
2228       Return code 0 means the command was sent to  the  IRC  server  success‐
2229       fully.  This  does not mean the operation succeed, and you need to wait
2230       for the appropriate event or  for  the  error  code  via  event_numeric
2231       event.
2232
2233       If the operation succeed, the server will send the event_nick event. If
2234       not, it will send a numeric error. Possible error  responces  for  this
2235       command from the RFC1459:
2236
2237              · LIBIRC_RFC_ERR_NONICKNAMEGIVEN
2238
2239              · LIBIRC_RFC_ERR_ERRONEUSNICKNAME
2240
2241              · LIBIRC_RFC_ERR_NICKNAMEINUSE
2242
2243              · LIBIRC_RFC_ERR_NICKCOLLISION
2244
2245       Thread safety:
2246
2247       This function can be called simultaneously from multiple threads.
2248
2249   irc_cmd_whois
2250       Prototype:
2251
2252       int irc_cmd_whois(irc_session_t * session, const char * nick)
2253
2254       Parameters:
2255
2256                       ┌────────┬────────────────────────────┐
2257session │ IRC session handle         │
2258                       ├────────┼────────────────────────────┤
2259nick    │ Nick   or  comma-separated │
2260                       │        │ list of nicks to query the │
2261                       │        │ information about          │
2262                       └────────┴────────────────────────────┘
2263
2264       Description:
2265
2266       This function queries various information about the nick. The amount of
2267       information depends on the IRC server but typically includes  username,
2268       real name (as defined by the client at login), the IRC server used, the
2269       channels user is in, idle time, away mode and so on.
2270
2271       Return value:
2272
2273       Return code 0 means the command was sent to  the  IRC  server  success‐
2274       fully.  This  does not mean the operation succeed, and you need to wait
2275       for the appropriate event_numeric event.
2276
2277       If the request succeed, the information is returned through the follow‐
2278       ing numeric codes which return the information:
2279
2280              · LIBIRC_RFC_RPL_WHOISUSER
2281
2282              · LIBIRC_RFC_RPL_WHOISCHANNELS
2283
2284              · LIBIRC_RFC_RPL_WHOISSERVER
2285
2286              · LIBIRC_RFC_RPL_AWAY
2287
2288              · LIBIRC_RFC_RPL_WHOISOPERATOR
2289
2290              · LIBIRC_RFC_RPL_WHOISIDLE
2291
2292              · LIBIRC_RFC_RPL_ENDOFWHOIS  -  this  event terminates the WHOIS
2293                information
2294
2295       Possible error responces for this command from the RFC1459:
2296
2297              · LIBIRC_RFC_ERR_NOSUCHSERVER
2298
2299              · LIBIRC_RFC_ERR_NOSUCHNICK
2300
2301              · LIBIRC_RFC_ERR_NONICKNAMEGIVEN
2302
2303       Thread safety:
2304
2305       This function can be called simultaneously from multiple threads.
2306
2307   irc_cmd_quit
2308       Prototype:
2309
2310       int irc_cmd_quit(irc_session_t * session, const char * reason)
2311
2312       Parameters:
2313
2314                       ┌────────┬────────────────────────────┐
2315session │ IRC session handle         │
2316                       ├────────┼────────────────────────────┤
2317reason  │ If not NULL, the reason to │
2318                       │        │ quit                       │
2319                       └────────┴────────────────────────────┘
2320
2321       Description:  This  function  sends the QUIT command to the IRC server.
2322       This command forces the IRC server to close  the  IRC  connection,  and
2323       terminate the session.
2324
2325       The  difference  between this command and calling the irc_disconnect is
2326       that this command allows to specify the reason to quit  which  will  be
2327       shown  to  all the users in the channels you joined. Also it would make
2328       it clear that you left the IRC channels by purpose, and not merely  got
2329       disconnected.
2330
2331       Return value:
2332
2333       Return  code  0  means  the command was sent to the IRC server success‐
2334       fully. This does not mean the operation succeed, and you need  to  wait
2335       for  the  appropriate  event  or  for  the error code via event_numeric
2336       event.
2337
2338       Thread safety:
2339
2340       This function can be called simultaneously from multiple threads.
2341
2342   irc_send_raw
2343       Prototype:
2344
2345       int irc_send_raw (irc_session_t * session, const char * format, ...);
2346
2347       Parameters:
2348
2349                       ┌────────┬────────────────────────────┐
2350session │ IRC session handle         │
2351                       ├────────┼────────────────────────────┤
2352format  │ printf-type     formatting │
2353                       │        │ string   followed  by  the │
2354                       │        │ format arguments           │
2355                       └────────┴────────────────────────────┘
2356
2357       Description:
2358
2359       This function sends the raw data as-is to the IRC  server.  Use  it  to
2360       generate  a server command, which is not (yet) provided by libircclient
2361       directly.
2362
2363       Return value:
2364
2365       Return code 0 means the command was sent to  the  IRC  server  success‐
2366       fully.  This  does not mean the operation succeed, and you need to wait
2367       for the appropriate event or  for  the  error  code  via  event_numeric
2368       event.
2369
2370       Thread safety:
2371
2372       This function can be called simultaneously from multiple threads.
2373
2374   irc_target_get_nick
2375       Prototype:
2376
2377       void irc_target_get_nick(const char * origin, char *nick, size_t size)
2378
2379       Parameters:
2380
2381                        ┌───────┬────────────────────────────┐
2382origin │ Nick  in  the  common  IRC │
2383                        │       │ server  format   such   as │
2384                        │       │ tim!root@mycomain.com      │
2385                        ├───────┼────────────────────────────┤
2386nick   │ Buffer   to  retrieve  the │
2387                        │       │ parsed nick name           │
2388                        ├───────┼────────────────────────────┤
2389size   │ Size of the  nick  buffer. │
2390                        │       │ If   the  parsed  nick  is │
2391                        │       │ larger  than  the   buffer │
2392                        │       │ size it will be truncated  │
2393                        └───────┴────────────────────────────┘
2394
2395       Description:
2396
2397       For  most events IRC server returns 'origin' (i.e. the person, who gen‐
2398       erated this event) in so-called "common" form,  like  nick!host@domain.
2399       However, all the irc_cmd_* functions require just a nick. This function
2400       parses this origin,  and  retrieves  the  nick,  storing  it  into  the
2401       user-provided buffer.
2402
2403       A buffer of size 128 should be enough for most nicks.
2404
2405       Thread safety:
2406
2407       This function can be called simultaneously from multiple threads.
2408
2409   irc_target_get_host
2410       Prototype:
2411
2412       void irc_target_get_host(const char * target, char *host, size_t size)
2413
2414       Parameters:
2415
2416                        ┌───────┬────────────────────────────┐
2417origin │ Nick  in  the  common  IRC │
2418                        │       │ server  format   such   as │
2419                        │       │ tim!root@mycomain.com      │
2420                        ├───────┼────────────────────────────┤
2421host   │ Buffer   to  retrieve  the │
2422                        │       │ parsed hostname            │
2423                        ├───────┼────────────────────────────┤
2424size   │ Size of the  host  buffer. │
2425                        │       │ If   the  parsed  nick  is │
2426                        │       │ larger  than  the   buffer │
2427                        │       │ size it will be truncated  │
2428                        └───────┴────────────────────────────┘
2429
2430       Description:
2431
2432       For  most events IRC server returns 'origin' (i.e. the person, who gen‐
2433       erated this event) in so-called "common" form,  like  nick!host@domain.
2434       This  function  parses  this origin, and retrieves the host, storing it
2435       into the user-provided buffer.
2436
2437       Thread safety:
2438
2439       This function can be called simultaneously from multiple threads.
2440
2441   DCC initiating and accepting chat sessions, sending and receiving files
2442   irc_dcc_chat
2443       Prototype:
2444
2445       int  irc_dcc_chat(irc_session_t  * session,  void  * ctx,  const   char
2446       * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid)
2447
2448       Parameters:
2449
2450                       ┌─────────┬────────────────────────────┐
2451session  │ IRC session handle         │
2452                       ├─────────┼────────────────────────────┤
2453ctx      │ User-defined context which │
2454                       │         │ will  be  passed  to   the │
2455                       │         │ callback. May be NULL      │
2456                       ├─────────┼────────────────────────────┤
2457nick     │ Target nick                │
2458                       ├─────────┼────────────────────────────┤
2459callback │ DCC callback which will be │
2460                       │         │ used  for  DCC  and   chat │
2461                       │         │ events                     │
2462                       ├─────────┼────────────────────────────┤
2463dccid    │ If this function succeeds, │
2464                       │         │ the DCC session identifier │
2465                       │         │ is stored in this field    │
2466                       └─────────┴────────────────────────────┘
2467
2468       Description:
2469
2470       This  function  requests a DCC CHAT between you and other IRC user. DCC
2471       CHAT is like private chat, but it goes directly between two users,  and
2472       bypasses  the  IRC  server.  DCC CHAT request must be accepted by other
2473       side before you can send anything.
2474
2475       When the chat is  accepted,  declined,  terminated,  or  some  data  is
2476       received, the callback function is called. To be specific, the callback
2477       will be called when:
2478
2479          · The chat request is accepted;
2480
2481          · The chat request is denied;
2482
2483          · The new chat message is received;
2484
2485          · The chat is terminated by the remote party;
2486
2487       See the details in irc_dcc_callback_t declaration.
2488
2489       Return value:
2490
2491       Return code 0 means the command was sent to  the  IRC  server  success‐
2492       fully.  This  does not mean the operation succeed, and you need to wait
2493       for the appropriate event or  for  the  error  code  via  event_numeric
2494       event.
2495
2496       Possible error responces for this command from the RFC1459:
2497
2498              · LIBIRC_RFC_ERR_NORECIPIENT
2499
2500              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2501
2502              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2503
2504              · LIBIRC_RFC_ERR_NOTONCHANNEL
2505
2506              · LIBIRC_RFC_ERR_NOTOPLEVEL
2507
2508              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2509
2510              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2511
2512              · LIBIRC_RFC_ERR_NOSUCHNICK
2513
2514       Thread safety:
2515
2516       This function can be called simultaneously from multiple threads.
2517
2518   irc_dcc_msg
2519       Prototype:
2520
2521       int  irc_dcc_msg(irc_session_t  * session,  irc_dcc_t dccid, const char
2522       * text)
2523
2524       Parameters:
2525
2526                       ┌────────┬────────────────────────────┐
2527session │ IRC session handle         │
2528                       ├────────┼────────────────────────────┤
2529dccid   │ DCC session identifier for │
2530                       │        │ the DCC CHAT session which │
2531                       │        │ is active                  │
2532                       ├────────┼────────────────────────────┤
2533text    │ NULL-terminated message to │
2534                       │        │ send                       │
2535                       └────────┴────────────────────────────┘
2536
2537       Description:
2538
2539       This  function  is  used  to send the DCC CHAT message to an active DCC
2540       CHAT. To be active, DCC CHAT request must be initiated by one side  and
2541       accepted by another side.
2542
2543       Return value:
2544
2545       Return  code  0  means success. Other value means error, the error code
2546       may be obtained through irc_errno().
2547
2548       Thread safety:
2549
2550       This function can be called simultaneously from multiple threads.
2551
2552   irc_dcc_accept
2553       Prototype:
2554
2555       int  irc_dcc_accept(irc_session_t  * session,   irc_dcc_t dccid,   void
2556       * ctx, irc_dcc_callback_t callback)
2557
2558       Parameters:
2559
2560                       ┌─────────┬────────────────────────────┐
2561session  │ IRC session handle         │
2562                       ├─────────┼────────────────────────────┤
2563dccid    │ DCC   session   identifier │
2564                       │         │ returned by the callback   │
2565                       ├─────────┼────────────────────────────┤
2566ctx      │ User-defined context which │
2567                       │         │ will   be  passed  to  the │
2568                       │         │ callback. May be NULL      │
2569                       ├─────────┼────────────────────────────┤
2570callback │ DCC callback which will be │
2571                       │         │ used   for  DCC  and  chat │
2572                       │         │ events                     │
2573                       └─────────┴────────────────────────────┘
2574
2575       Description:
2576
2577       This function accepts a remote DCC chat or file transfer request. After
2578       the request is accepted the callback will be called for the further DCC
2579       events, including the termination of the DCC session. See the DCC call‐
2580       back information.
2581
2582       This  function should be called only after either event_dcc_chat_req or
2583       event_dcc_send_req  events  are  received.  You  don't  have  to   call
2584       irc_dcc_accept() or irc_dcc_decline() immediately in the event process‐
2585       ing function - you may just store the dccid and return, and call  those
2586       functions  later.  However to prevent memory leaks you must call either
2587       irc_dcc_decline() or irc_dcc_accept()  for  any  incoming  DCC  request
2588       within 60 seconds after receiving it.
2589
2590       Return value:
2591
2592       Return  code  0  means success. Other value means error, the error code
2593       may be obtained through irc_errno().
2594
2595       Thread safety:
2596
2597       This function can be called simultaneously from multiple threads.
2598
2599   irc_dcc_decline
2600       Prototype:
2601
2602       int irc_dcc_decline(irc_session_t * session, irc_dcc_t dccid)
2603
2604       Parameters:
2605
2606                       ┌────────┬────────────────────────────┐
2607session │ IRC session handle         │
2608                       ├────────┼────────────────────────────┤
2609dccid   │ DCC   session   identifier │
2610                       │        │ returned by the callback   │
2611                       └────────┴────────────────────────────┘
2612
2613       Description:
2614
2615       This function declines a remote DCC chat or file transfer request.
2616
2617       This  function should be called only after either event_dcc_chat_req or
2618       event_dcc_send_req  events  are  received.  You  don't  have  to   call
2619       irc_dcc_accept() or irc_dcc_decline() immediately in the event process‐
2620       ing function - you may just store the dccid and return, and call  those
2621       functions  later.  However to prevent memory leaks you must call either
2622       irc_dcc_decline() or irc_dcc_accept()  for  any  incoming  DCC  request
2623       within 60 seconds after receiving it.
2624
2625       Do  not  use this function to forecefully close the previously accepted
2626       or initiated DCC session. Use irc_dcc_destroy() instead.
2627
2628       Return value:
2629
2630       Return code 0 means success. Other value means error,  the  error  code
2631       may be obtained through irc_errno().
2632
2633       Thread safety:
2634
2635       This function can be called simultaneously from multiple threads.
2636
2637   irc_dcc_sendfile
2638       Prototype:
2639
2640       int  irc_dcc_sendfile(irc_session_t  * session,  void * ctx, const char
2641       * nick, const char * filename,  irc_dcc_callback_t callback,  irc_dcc_t
2642       * dccid)
2643
2644       Parameters:
2645
2646                       ┌─────────┬────────────────────────────┐
2647session  │ IRC session handle         │
2648                       ├─────────┼────────────────────────────┤
2649ctx      │ User-defined context which │
2650                       │         │ will  be  passed  to   the │
2651                       │         │ callback. May be NULL      │
2652                       ├─────────┼────────────────────────────┤
2653nick     │ Target nick                │
2654                       ├─────────┼────────────────────────────┤
2655filename │ Full   path  to  the  file │
2656                       │         │ which will be  sent.  Must │
2657                       │         │ be an existing file        │
2658                       ├─────────┼────────────────────────────┤
2659callback │ DCC callback which will be │
2660                       │         │ used  for  DCC  and   chat │
2661                       │         │ events                     │
2662                       ├─────────┼────────────────────────────┤
2663dccid    │ If this function succeeds, │
2664                       │         │ the DCC session identifier │
2665                       │         │ is stored in this field    │
2666                       └─────────┴────────────────────────────┘
2667
2668       Description:
2669
2670       This function generates a DCC SEND request to send the file. When it is
2671       accepted, the file is sent to the remote party, and the DCC session  is
2672       closed.  The  send  operation progress and result can be checked in the
2673       callback. See the DCC callback information.
2674
2675       Return value:
2676
2677       Return code 0 means the command was sent to  the  IRC  server  success‐
2678       fully.  This  does not mean the operation succeed, and you need to wait
2679       for the appropriate event or  for  the  error  code  via  event_numeric
2680       event.
2681
2682       Possible error responces for this command from the RFC1459:
2683
2684              · LIBIRC_RFC_ERR_NORECIPIENT
2685
2686              · LIBIRC_RFC_ERR_NOTEXTTOSEND
2687
2688              · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2689
2690              · LIBIRC_RFC_ERR_NOTONCHANNEL
2691
2692              · LIBIRC_RFC_ERR_NOTOPLEVEL
2693
2694              · LIBIRC_RFC_ERR_WILDTOPLEVEL
2695
2696              · LIBIRC_RFC_ERR_TOOMANYTARGETS
2697
2698              · LIBIRC_RFC_ERR_NOSUCHNICK
2699
2700       Thread safety:
2701
2702       This function can be called simultaneously from multiple threads.
2703
2704   irc_dcc_destroy
2705       Prototype:
2706
2707       int irc_dcc_destroy(irc_session_t * session, irc_dcc_t dccid)
2708
2709       Parameters:
2710
2711                       ┌────────┬────────────────────────────┐
2712session │ IRC session handle         │
2713                       ├────────┼────────────────────────────┤
2714dccid   │ DCC  session identifier of │
2715                       │        │ a session to destroy       │
2716                       └────────┴────────────────────────────┘
2717
2718       Description:
2719
2720       This function closes the DCC connection (if  available),  and  destroys
2721       the  DCC session, freeing the used resources. It can be called anytime,
2722       even from callbacks or from different threads.
2723
2724       Note that when DCC session is finished (either with  success  or  fail‐
2725       ure), you should not destroy it - it will be destroyed automatically.
2726
2727       Return value:
2728
2729       Return  code  0  means success. Other value means error, the error code
2730       may be obtained through irc_errno().
2731
2732       Thread safety:
2733
2734       This function can be called simultaneously from multiple threads.
2735
2736   Handling the colored messages
2737   irc_color_strip_from_mirc
2738       Prototype:
2739
2740       char * irc_color_strip_from_mirc(const char * message)
2741
2742       Parameters:
2743
2744                       ┌────────┬────────────────────────────┐
2745message │ Original message with col‐ │
2746                       │        │ ors                        │
2747                       └────────┴────────────────────────────┘
2748
2749       Description:
2750
2751       This  function  strips  all  the ANSI color codes from the message, and
2752       returns a new message with no color information. Useful  for  the  bots
2753       which  react  to  strings,  to make sure the bot is not confused if the
2754       string uses colors.
2755
2756       This function does not modify the message which doesn't use colors.
2757
2758       Return value:
2759
2760       Returns a new message with stripped color codes. Note that  the  memory
2761       for  the new message is allocated using malloc(), so you should free it
2762       using free() when it is not used anymore. If memory allocation  failed,
2763       returns 0.
2764
2765       Thread safety:
2766
2767       This function can be called simultaneously from multiple threads.
2768
2769   irc_color_convert_from_mirc
2770       Prototype:
2771
2772       char * irc_color_convert_from_mirc(const char * message)
2773
2774       Parameters:
2775
2776
2777                       ┌────────┬────────────────────────────┐
2778message │ Original message with col‐ │
2779                       │        │ ors                        │
2780                       └────────┴────────────────────────────┘
2781
2782       Description:
2783
2784       This function converts all the color codes and format options to libir‐
2785       cclient internal colors.
2786
2787       Return value:
2788
2789       Returns  a  pointer  to the new message with converted ANSI color codes
2790       and format options. See the irc_color_convert_to_mirc help for details.
2791
2792       Note that the memory for the new message is allocated  using  malloc(),
2793       so  you  should  free  it using free() when it is not used anymore.  If
2794       memory allocation failed, returns 0.
2795
2796       Thread safety:
2797
2798       This function can be called simultaneously from multiple threads.
2799
2800   irc_color_convert_to_mirc
2801       Prototype:
2802
2803       char * irc_color_convert_to_mirc(const char * message)
2804
2805       Parameters:
2806
2807                       ┌────────┬────────────────────────────┐
2808message │ Original message with col‐ │
2809                       │        │ ors                        │
2810                       └────────┴────────────────────────────┘
2811
2812       Description:
2813
2814       This  function  converts  all  the  color codes and format options from
2815       internal libircclient colors  to  ANSI  used  by  mIRC  and  other  IRC
2816       clients.
2817
2818       Return value:
2819
2820       Returns a new message with converted color codes and format options, or
2821       0 if memory could not be allocated. Note that the memory  for  the  new
2822       message is allocated using malloc(), so you should free it using free()
2823       when it is not used anymore.
2824
2825       Thread safety:
2826
2827       This function can be called simultaneously from multiple threads.
2828
2829       The color system of libircclient is designed to be  easy  to  use,  and
2830       portable between different IRC clients. Every color or format option is
2831       described using plain text commands written between square brackets.
2832
2833       The possible codes are:
2834
2835              · [B] ... [/B] - bold format mode. Everything  between  [B]  and
2836                [/B] is written in bold.
2837
2838              · [I]  ... [/I] - italic/reverse format mode. Everything between
2839                [I] and [/I] is  written  in  italic,  or  reversed  (however,
2840                because  some  clients are incapable of rendering italic text,
2841                most clients display this as normal text with  the  background
2842                and foreground colors swapped).
2843
2844              · [U]  ...  [/U] - underline format mode. Everything between [U]
2845                and [/U] is written underlined.
2846
2847              · [COLOR=RED] ... [/COLOR] -  write  the  text  using  specified
2848                foreground color. The color is set by using the COLOR keyword,
2849                and equal sign followed by text color code (see below).
2850
2851              · [COLOR=RED/BLUE] ... [/COLOR] - write the text using specified
2852                foreground and background color. The color is set by using the
2853                COLOR keyword, an equal sign followed by text foreground color
2854                code, a dash and a text background color code.
2855
2856       The following colors are supported:
2857
2858              · WHITE
2859
2860              · BLACK
2861
2862              · DARKBLUE
2863
2864              · DARKGREEN
2865
2866              · RED
2867
2868              · BROWN
2869
2870              · PURPLE
2871
2872              · OLIVE
2873
2874              · YELLOW
2875
2876              · GREEN
2877
2878              · TEAL
2879
2880              · CYAN
2881
2882              · BLUE
2883
2884              · MAGENTA
2885
2886              · DARKGRAY
2887
2888              · LIGHTGRAY
2889
2890       Examples of color sequences:
2891
2892          Hello, [B]Tim[/B].
2893          [U]Arsenal[/U] got a [COLOR=RED]red card[/COLOR]
2894          The tree[U]s[/U] are [COLOR=GREEN/BLACK]green[/COLOR]
2895
2896   Changing the library options
2897   irc_get_version
2898       Prototype:
2899
2900       void irc_get_version(unsigned int * high, unsigned int * low)
2901
2902       Parameters:
2903
2904                         ┌─────┬────────────────────────────┐
2905high │ Stores  the  high  version │
2906                         │     │ number                     │
2907                         ├─────┼────────────────────────────┤
2908low  │ Stores  the  low   version │
2909                         │     │ number                     │
2910                         └─────┴────────────────────────────┘
2911
2912       Description:
2913
2914       This function returns the libircclient version. You can use the version
2915       either to check whether required options are available,  or  to  output
2916       the  version.   The  preferred  printf-like format string to output the
2917       version is:
2918
2919       printf ("Version: %d.%02d", high, low);
2920
2921       Thread safety:
2922
2923       This function can be called simultaneously from multiple threads.
2924
2925   irc_set_ctx
2926       Prototype:
2927
2928       void irc_set_ctx(irc_session_t * session, void * ctx)
2929
2930       Parameters:
2931
2932                          ┌────────┬──────────────────────┐
2933session │ IRC session handle   │
2934                          ├────────┼──────────────────────┤
2935ctx     │ User-defined context │
2936                          └────────┴──────────────────────┘
2937
2938       Description:
2939
2940       This function sets the user-defined context for this IRC session.  This
2941       context  is  not  used  by  libircclient.  Its purpose is to store ses‐
2942       sion-specific user  data,  which  may  be  obtained  later  by  calling
2943       irc_get_ctx.  Note  that libircclient just carries out this pointer. If
2944       you allocate some memory, and store its address  in  ctx  (most  common
2945       usage),   it   is   your  responsibility  to  free  it  before  calling
2946       irc_destroy_session().
2947
2948       Thread safety:
2949
2950       This function can be called simultaneously from multiple threads.
2951
2952   irc_get_ctx
2953       Prototype:
2954
2955       void * irc_get_ctx(irc_session_t * session)
2956
2957       Parameters:
2958
2959                           ┌────────┬────────────────────┐
2960session │ IRC session handle │
2961                           └────────┴────────────────────┘
2962
2963       Description:
2964
2965       This function returns  the  IRC  session  context,  which  was  set  by
2966       irc_set_ctx.
2967
2968       Return value:
2969
2970       If no context was set, this function returns NULL.
2971
2972       Thread safety:
2973
2974       This function can be called simultaneously from multiple threads.
2975
2976   irc_option_set
2977       Prototype:
2978
2979       void irc_option_set(irc_session_t * session, unsigned int option)
2980
2981       Parameters:
2982
2983                       ┌────────┬────────────────────────────┐
2984session │ IRC session handle         │
2985                       ├────────┼────────────────────────────┤
2986option  │ One  of the Libirc options
2987                       │        │ to set                     │
2988                       └────────┴────────────────────────────┘
2989
2990       Description:
2991
2992       This function  sets  the  libircclient  option,  changing  libircclient
2993       behavior. See the options list for the meaning for every option.
2994
2995       Thread safety:
2996
2997       This function can be called simultaneously from multiple threads.
2998
2999   irc_option_reset
3000       Prototype:
3001
3002       void irc_option_reset(irc_session_t * session, unsigned int option)
3003
3004       Parameters:
3005
3006
3007
3008
3009                       ┌────────┬────────────────────────────┐
3010session │ IRC session handle         │
3011                       ├────────┼────────────────────────────┤
3012option  │ One  of the Libirc options
3013                       │        │ to set                     │
3014                       └────────┴────────────────────────────┘
3015
3016       Description:
3017
3018       This function resets the  libircclient  option,  changing  libircclient
3019       behavior. See the options list for the meaning for every option.
3020
3021       Thread safety:
3022
3023       This function can be called simultaneously from multiple threads.
3024
3025   Handling the errors
3026   irc_errno
3027       Prototype:
3028
3029       int irc_errno(irc_session_t * session)
3030
3031       Parameters:
3032
3033                           ┌────────┬────────────────────┐
3034session │ IRC session handle │
3035                           └────────┴────────────────────┘
3036
3037       Description:
3038
3039       This  function  returns the last error code associated with last opera‐
3040       tion  of  this  IRC  session.  Possible  error  codes  are  defined  in
3041       libirc_errors.h
3042
3043       As usual, typical errno rules apply:
3044
3045          · irc_errno() should be called ONLY if the called function fails;
3046
3047          · irc_errno()  doesn't  return  0 if function succeed; actually, the
3048            return value will be undefined.
3049
3050          · you should call  irc_errno()  IMMEDIATELY  after  function  fails,
3051            before calling any other libircclient function.
3052
3053       Return value:
3054
3055       The error code.
3056
3057       Thread safety:
3058
3059       This function can be called simultaneously from multiple threads. Local
3060       error code is per IRC context, not per thread.
3061
3062   irc_strerror
3063       Prototype:
3064
3065       const char * irc_strerror(int ircerrno)
3066
3067       Parameters:
3068
3069                       ┌─────────┬────────────────────────────┐
3070ircerrno │ IRC error code returned by │
3071                       │         │ irc_errno()                
3072                       └─────────┴────────────────────────────┘
3073
3074       Description:
3075
3076       This function returns the text representation of the given error code.
3077
3078       Return value:
3079
3080       Returns  an  internal  English  string  with a short description of the
3081       error code.
3082
3083       Thread safety:
3084
3085       This function can be called simultaneously from multiple threads.
3086
3087   Types
3088       This section describes various types defined by the library.
3089
3090   irc_session_t
3091       typedef struct irc_session_s irc_session_t
3092
3093       The IRC session handle created by callind irc_create_session(). Most of
3094       the  library  function calls expect this handle as a parameter. You can
3095       create as many handles as you want.   Each  handle  could  be  used  to
3096       establish a single IRC connection to an IRC server as a single user.
3097
3098       Once  the handle is not used anymore, it should be destroyed by calling
3099       irc_destroy_session().
3100
3101   irc_dcc_session_t
3102       typedef struct irc_dcc_session_s irc_dcc_session_t
3103
3104       This structure describes a DCC session used by libircclient.  Its  mem‐
3105       bers are internal to libircclient, and should not be used directly.
3106
3107   irc_dcc_t
3108       typedef unsigned int irc_dcc_t
3109
3110       This  type  is  a DCC session identifier, used to identify the DCC ses‐
3111       sions in callbacks and various functions.
3112
3113   irc_callbacks_t
3114       typedef struct irc_callbacks_t
3115
3116          typedef struct
3117          {
3118            irc_event_callback_t         event_connect;
3119            irc_event_callback_t         event_nick;
3120            irc_event_callback_t         event_quit;
3121            irc_event_callback_t         event_join;
3122            irc_event_callback_t         event_part;
3123            irc_event_callback_t         event_mode;
3124            irc_event_callback_t         event_umode;
3125            irc_event_callback_t         event_topic;
3126            irc_event_callback_t         event_kick;
3127            irc_event_callback_t         event_channel;
3128            irc_event_callback_t         event_privmsg;
3129            irc_event_callback_t         event_notice;
3130            irc_event_callback_t         event_channel_notice;
3131            irc_event_callback_t         event_invite;
3132            irc_event_callback_t         event_ctcp_req;
3133            irc_event_callback_t         event_ctcp_rep;
3134            irc_event_callback_t         event_ctcp_action;
3135            irc_event_callback_t         event_unknown;
3136            irc_eventcode_callback_t     event_numeric;
3137            irc_event_dcc_chat_t         event_dcc_chat_req;
3138            irc_event_dcc_send_t         event_dcc_send_req;
3139          }
3140
3141       Describes the event callbacks structure which is  used  in  registering
3142       the callbacks.
3143
3144       All  the  communication with the IRC network is based on events. Gener‐
3145       ally speaking, event is anything generated by someone else in the  net‐
3146       work,  or  by  the  IRC  server itself.  "Someone sends you a message",
3147       "Someone has joined the channel", "Someone has quits IRC" -  all  these
3148       messages are events.
3149
3150       Every  event has its own event handler, which is called when the appro‐
3151       priate event is received.  You don't have to define all the event  han‐
3152       dlers;  define  only the handlers for the events you need to intercept,
3153       and set the remaining handler pointers to NULL.
3154
3155       event_connect
3156
3157       This event is triggered when the connection to the IRC server  is  suc‐
3158       cessfully  established,  and  the  MOTD  is  received. Depending on the
3159       server it may also be possible to send the commands before this event.
3160
3161       This event uses irc_event_callback_t callback with the  following  val‐
3162       ues:
3163
3164
3165                           ┌───────┬─────────────────────┐
3166origin │ Unused, set to NULL │
3167                           ├───────┼─────────────────────┤
3168params │ Unused, set to NULL │
3169                           └───────┴─────────────────────┘
3170
3171       event_nick
3172
3173       This  event  is triggered when the NICK message is received. It happens
3174       when one of the users (including you) in one of the  channels  you  are
3175       watching (have joined) changed their nick.
3176
3177       Changing  your  own  nick  will also generate this event. Note that the
3178       server may change your nick  independently,  so  you  must  track  this
3179       event.
3180
3181       This  event  uses irc_event_callback_t callback with the following val‐
3182       ues:
3183
3184                        ┌───────┬────────────────────────────┐
3185origin │ The original nick (may  be │
3186                        │       │ yours!)                    │
3187                        ├───────┼────────────────────────────┤
3188params │ params[0]  contains  a new │
3189                        │       │ nick.                      │
3190                        └───────┴────────────────────────────┘
3191
3192       event_quit
3193
3194       This event is triggered when the QUIT message is received.  It  happens
3195       when  one  of  the  users in one of the channels you are watching (have
3196       joined) disconnected from the IRC server.
3197
3198       This event uses irc_event_callback_t callback with the  following  val‐
3199       ues:
3200
3201                        ┌───────┬────────────────────────────┐
3202origin │ The user who disconnected  │
3203                        ├───────┼────────────────────────────┤
3204params │ params[0]   is   optional, │
3205                        │       │ contains  the  user-speci‐ │
3206                        │       │ fied reason to quit        │
3207                        └───────┴────────────────────────────┘
3208
3209       event_join
3210
3211       This event is triggered upon receipt of a JOIN message. It happens when
3212       a new user joins the channel you are watching (have  joined).  It  also
3213       happens when you joined the new channel.
3214
3215       Note  that  you  may  be  "forced"  to  join the channel (and therefore
3216       receive this event) without issuing the JOIN command. A typical case is
3217       when  the  NickServ bot on the server is configured to auto-join you to
3218       specific channels.
3219
3220       This event uses irc_event_callback_t callback with the  following  val‐
3221       ues:
3222
3223                        ┌───────┬────────────────────────────┐
3224origin │ The  user  who  joined the │
3225                        │       │ channel (this may be you!) │
3226                        ├───────┼────────────────────────────┤
3227params │ params[0]   contains   the │
3228                        │       │ channel name               │
3229                        └───────┴────────────────────────────┘
3230
3231       event_part
3232
3233       This event is triggered upon receipt of a PART message. It happens when
3234       a user leaves the channel you are watching (have joined). It also  hap‐
3235       pens when you leave a channel.
3236
3237       This  event  uses irc_event_callback_t callback with the following val‐
3238       ues:
3239
3240
3241
3242
3243                        ┌───────┬────────────────────────────┐
3244origin │ The  user  who  left   the │
3245                        │       │ channel (this may be you!) │
3246                        ├───────┼────────────────────────────┤
3247params │ params[0]   contains   the │
3248                        │       │ channel name params[1]  is │
3249                        │       │ optional  and contains the │
3250                        │       │ user-specified reason      │
3251                        └───────┴────────────────────────────┘
3252
3253       event_mode
3254
3255       This event is triggered upon receipt of a channel MODE message. It hap‐
3256       pens  when  someone changed the mode(s) of the channel you are watching
3257       (have joined).
3258
3259       This event uses irc_event_callback_t callback with the  following  val‐
3260       ues:
3261
3262                        ┌───────┬────────────────────────────┐
3263origin │ The user who performed the │
3264                        │       │ change                     │
3265                        ├───────┼────────────────────────────┤
3266params │ params[0]   contains   the │
3267                        │       │ channel   name   params[1] │
3268                        │       │ contains the channel  mode │
3269                        │       │ changes,   such  as  "+t", │
3270                        │       │ "-i"  params[2]  optional, │
3271                        │       │ contains  the argument for │
3272                        │       │ the  channel   mode   (for │
3273                        │       │ example, a nick for the +o │
3274                        │       │ mode)                      │
3275                        └───────┴────────────────────────────┘
3276
3277       event_umode
3278
3279       This event is triggered upon receipt of a user MODE message. It happens
3280       when your user mode is changed.
3281
3282       This  event  uses irc_event_callback_t callback with the following val‐
3283       ues:
3284
3285                        ┌───────┬────────────────────────────┐
3286origin │ The user who performed the │
3287                        │       │ change                     │
3288                        ├───────┼────────────────────────────┤
3289params │ params[0]   contains   the │
3290                        │       │ channel   name   params[1] │
3291                        │       │ contains   the  user  mode │
3292                        │       │ changes,  such  as   "+t", │
3293                        │       │ "-i"                       │
3294                        └───────┴────────────────────────────┘
3295
3296       event_topic
3297
3298       This  event  is  triggered  upon receipt of a TOPIC message. It happens
3299       when someone changed the topic on the channel you  are  watching  (have
3300       joined).
3301
3302       This  event  uses irc_event_callback_t callback with the following val‐
3303       ues:
3304
3305                        ┌───────┬────────────────────────────┐
3306origin │ The user who performed the │
3307                        │       │ change                     │
3308                        ├───────┼────────────────────────────┤
3309params │ params[0]   contains   the │
3310                        │       │ channel   name   params[1] │
3311                        │       │ optional, contains the new │
3312                        │       │ topic                      │
3313                        └───────┴────────────────────────────┘
3314
3315       event_kick
3316
3317       This event is triggered upon receipt of a KICK message. It happens when
3318       someone (including you) kicked someone (including you) from the channel
3319       you are watching (have joined).
3320
3321       It is possible to kick yourself from the channel.
3322
3323       This event uses irc_event_callback_t callback with the  following  val‐
3324       ues:
3325
3326                        ┌───────┬────────────────────────────┐
3327origin │ The user who performed the │
3328                        │       │ action (may be you)        │
3329                        ├───────┼────────────────────────────┤
3330params │ params[0]   contains   the │
3331                        │       │ channel   name   params[1] │
3332                        │       │ optional,   contains   the │
3333                        │       │ nick    of    the   kicked │
3334                        │       │ params[2]  optional,  con‐ │
3335                        │       │ tains  the  reason for the │
3336                        │       │ kick                       │
3337                        └───────┴────────────────────────────┘
3338
3339       event_channel
3340
3341       This event is triggered upon receipt of a PRIVMSG message sent  to  the
3342       channel.  It  happens  when someone (but not you) sent a message to the
3343       channel you are watching (have joined).
3344
3345       Your own messages do not trigger this event.  However  the  server  can
3346       still  "force"  you to send a message to the channel by generating this
3347       event.
3348
3349       This event uses irc_event_callback_t callback with the  following  val‐
3350       ues:
3351
3352                        ┌───────┬────────────────────────────┐
3353origin │ The  user  who sent a mes‐ │
3354                        │       │ sage                       │
3355                        ├───────┼────────────────────────────┤
3356params │ params[0]   contains   the │
3357                        │       │ channel   name   params[1] │
3358                        │       │ optional,   contains   the │
3359                        │       │ message text               │
3360                        └───────┴────────────────────────────┘
3361
3362       event_privmsg
3363
3364       This  event  is  triggered  upon receipt of a PRIVMSG message sent pri‐
3365       vately to you. It happens when someone sent you a message.
3366
3367       This event uses irc_event_callback_t callback with the  following  val‐
3368       ues:
3369
3370                        ┌───────┬────────────────────────────┐
3371origin │ The  user  who sent a mes‐ │
3372                        │       │ sage                       │
3373                        ├───────┼────────────────────────────┤
3374params │ params[0]  contains   your │
3375                        │       │ nick  params[1]  optional, │
3376                        │       │ contains the message text  │
3377                        └───────┴────────────────────────────┘
3378
3379       event_notice
3380
3381       This event is triggered upon receipt of a NOTICE message. This  message
3382       is  similar to PRIVMSG and matches the event_privmsg.  According to RFC
3383       1459, the only difference between NOTICE and PRIVMSG is that you should
3384       NEVER automatically reply to NOTICE messages.  Unfortunately, this rule
3385       is frequently violated by IRC servers itself -  for  example,  NICKSERV
3386       messages require reply, and are sent as NOTICE.
3387
3388       This  event  uses irc_event_callback_t callback with the following val‐
3389       ues:
3390
3391                        ┌───────┬────────────────────────────┐
3392origin │ The user who sent  a  mes‐ │
3393                        │       │ sage                       │
3394                        └───────┴────────────────────────────┘
3395
3396
3397
3398
3399params │ params[0]   contains   the │
3400                        │       │ target nick name params[1] │
3401                        │       │ optional,   contains   the │
3402                        │       │ message text               │
3403                        └───────┴────────────────────────────┘
3404
3405       event_channel_notice
3406
3407       This event is triggered upon receipt of a NOTICE message. This  message
3408       is  similar to PRIVMSG and matches the event_channel.  According to RFC
3409       1459, the only difference between NOTICE and PRIVMSG is that you should
3410       NEVER automatically reply to NOTICE messages.  Unfortunately, this rule
3411       is frequently violated by IRC servers itself -  for  example,  NICKSERV
3412       messages require reply, and are sent as NOTICE.
3413
3414       This  event  uses irc_event_callback_t callback with the following val‐
3415       ues:
3416
3417                        ┌───────┬────────────────────────────┐
3418origin │ The user who sent  a  mes‐ │
3419                        │       │ sage                       │
3420                        ├───────┼────────────────────────────┤
3421params │ params[0]   contains   the │
3422                        │       │ channel   name   params[1] │
3423                        │       │ optional,   contains   the │
3424                        │       │ message text               │
3425                        └───────┴────────────────────────────┘
3426
3427       event_invite
3428
3429       This event is triggered upon receipt of an INVITE message.  It  happens
3430       when someone invited you to a channel which has +i (invite-only) mode.
3431
3432       This  event  uses irc_event_callback_t callback with the following val‐
3433       ues:
3434
3435                        ┌───────┬────────────────────────────┐
3436origin │ The user who invited you   │
3437                        ├───────┼────────────────────────────┤
3438params │ params[0]  contains   your │
3439                        │       │ nick  params[1]  optional, │
3440                        │       │ contains the channel name  │
3441                        └───────┴────────────────────────────┘
3442
3443       See also: irc_cmd_invite()
3444
3445       event_ctcp_req
3446
3447       This event is triggered upon receipt of an CTCP  request.  By  default,
3448       the built-in CTCP request handler is used.
3449
3450       Mirc  generates  PING,  FINGER, VERSION, TIME and ACTION messages which
3451       are automatically handled by the library if this event is  not  handled
3452       by  your  application.  Those messages are replied automatically except
3453       the ACTION message which triggers event_ctcp_action event.  If you need
3454       to  handle  more  types of the message, define this event handler,  and
3455       check the source code of libirc_event_ctcp_internal function to see how
3456       to  write your own CTCP request handler.  Note that you must support at
3457       least CTCP PING to pass the spoof check by some IRC servers.
3458
3459       Also you may find useful this question in FAQ: ref faq4
3460
3461       This event uses irc_event_callback_t callback with the  following  val‐
3462       ues:
3463
3464                        ┌───────┬────────────────────────────┐
3465origin │ The user who generated the │
3466                        │       │ message                    │
3467                        ├───────┼────────────────────────────┤
3468params │ params[0]   contains   the │
3469                        │       │ complete CTCP message      │
3470                        └───────┴────────────────────────────┘
3471
3472       event_ctcp_rep
3473
3474       This  event  is triggered upon receipt of an CTCP response. Thus if you
3475       generate the CTCP message and the remote  user  responded,  this  event
3476       handler will be called.
3477
3478       This  event  uses irc_event_callback_t callback with the following val‐
3479       ues:
3480
3481                        ┌───────┬────────────────────────────┐
3482origin │ The user who generated the │
3483                        │       │ message                    │
3484                        ├───────┼────────────────────────────┤
3485params │ params[0]   contains   the │
3486                        │       │ complete CTCP message      │
3487                        └───────┴────────────────────────────┘
3488
3489       event_ctcp_action
3490
3491       This event is triggered upon receipt of an CTCP ACTION message.  It  is
3492       only invoked if you did not define the event_ctcp_req event handler.
3493
3494       Such messages typically look like that in the IRC client:
3495
3496       ::     [08:32:55]  * Michael is having fun [08:32:55] * Bobby's getting
3497              jealous
3498
3499       This event uses irc_event_callback_t callback with the  following  val‐
3500       ues:
3501
3502                        ┌───────┬────────────────────────────┐
3503origin │ The user who generated the │
3504                        │       │ message                    │
3505                        ├───────┼────────────────────────────┤
3506params │ params[0]   contains   the │
3507                        │       │ content of ACTION message  │
3508                        └───────┴────────────────────────────┘
3509
3510       event_unknown
3511
3512       This event is triggered upon receipt of an unknown message which is not
3513       handled by the library.
3514
3515       This event uses irc_event_callback_t callback with the  following  val‐
3516       ues:
3517
3518                        ┌───────┬────────────────────────────┐
3519origin │ The user who generated the │
3520                        │       │ event                      │
3521                        ├───────┼────────────────────────────┤
3522params │ Zero  or  more  parameters │
3523                        │       │ provided with the event    │
3524                        └───────┴────────────────────────────┘
3525
3526       event_numeric
3527
3528       This  event is triggered upon receipt of every numeric message from the
3529       server. The incomplete list of those responses could be  found  in  RFC
3530       1429. This event is necessary to handle for any meaningful client.
3531
3532       This event uses the dedicated
3533       irc_eventcode_callback_t_
3534        callback. See the callback documentation.
3535
3536       event_dcc_chat_req
3537
3538       This event is triggered when someone attempts to establish the DCC CHAT
3539       with you.
3540
3541       This event uses the dedicated irc_event_dcc_chat_t  callback.  See  the
3542       callback documentation.
3543
3544       event_dcc_send_req
3545
3546       This  event is triggered when someone attempts to send you the file via
3547       DCC SEND.
3548
3549       This event uses the dedicated irc_event_dcc_send_t  callback.  See  the
3550       callback documentation.
3551
3552   Constants
3553       This section describes contstants such as options and the error codes.
3554
3555   Errors
3556       LIBIRC_ERR_OK
3557
3558       (0): No error
3559
3560       LIBIRC_ERR_INVAL
3561
3562       (1): An invalid value was given for one of the arguments to a function.
3563       For example,  supplying  the  NULL  value  as  a  channel  argument  of
3564       irc_cmd_join() produces this error.
3565
3566       LIBIRC_ERR_RESOLV
3567
3568       (2):  The  host  name  supplied for irc_connect() function could not be
3569       resolved into valid IP address.
3570
3571       LIBIRC_ERR_SOCKET
3572
3573       (3): The new socket could not be created or made non-blocking.  Usually
3574       means  that the server is out of resources, or (hopefully not) a bug in
3575       libircclient. See also faq_err_socket
3576
3577       LIBIRC_ERR_CONNECT
3578
3579       (4): The socket could not connect to the IRC server, or to the destina‐
3580       tion  DCC part. Usually means that either the IRC server is down or its
3581       address is invalid.  For DCC the reason usually is the firewall on your
3582       or destination computer, which refuses DCC transfer.
3583
3584       LIBIRC_ERR_CLOSED
3585
3586       (5):  The IRC connection was closed by the IRC server (which could mean
3587       that an IRC operator just have banned you from the server -  test  your
3588       client before connecting to a public server), or the DCC connection was
3589       closed by remote peer - for example, the other side just terminates the
3590       IRC application.  Usually it is not an error.
3591
3592       LIBIRC_ERR_NOMEM
3593
3594       (6):  There are two possible reasons for this error. First is that mem‐
3595       ory could not be allocated for  libircclient  internal  use,  and  this
3596       error  is  usually  fatal.   Second  reason  is that the command buffer
3597       (which queues the commands ready to be sent to the IRC server) is full,
3598       and  could  not  accept more commands yet.  In the last case you should
3599       just wait, and repeat the command later.
3600
3601       LIBIRC_ERR_ACCEPT
3602
3603       (7): A DCC chat/send connection from  the  remote  peer  could  not  be
3604       accepted.  Either  the  connection  was  just  terminated  before it is
3605       accepted, or there is a bug in libircclient.
3606
3607       LIBIRC_ERR_NODCCSEND
3608
3609       (9):  A filename supplied to  irc_dcc_sendfile()  could  not  be  sent.
3610       Either is is not a regular file (a directory or a socket, for example),
3611       or it could not be read. See also LIBIRC_ERR_OPENFILE
3612
3613       LIBIRC_ERR_READ
3614
3615       (10): Either a DCC file could not be read (for example,  was  truncated
3616       during  sending),  or  a DCC socket returns a read error, which usually
3617       means that the network connection is terminated.
3618
3619       LIBIRC_ERR_WRITE
3620
3621       (11):  Either a DCC file could not be written (for example, there is no
3622       free  space on disk), or a DCC socket returns a write error, which usu‐
3623       ally means that the network connection is terminated.
3624
3625       LIBIRC_ERR_STATE
3626
3627       (12):  The function is called when it is not allowed to be called.  For
3628       example,  irc_cmd_join() was called before the connection to IRC server
3629       succeed, and event_connect is called.
3630
3631       LIBIRC_ERR_TIMEOUT
3632
3633       (13):  The DCC request is timed out. There is  a  timer  for  each  DCC
3634       request,  which tracks connecting, accepting  and non-accepted/declined
3635       DCC requests. For every request this timer is currently set to 60  sec‐
3636       onds. If the DCC request was not connected, accepted or declined during
3637       this time, it will be terminated with this error.
3638
3639       LIBIRC_ERR_OPENFILE
3640
3641       (14): The file specified in irc_dcc_sendfile() could not be opened.
3642
3643       LIBIRC_ERR_TERMINATED
3644
3645       (15): The connection to the IRC server was terminated.
3646
3647       LIBIRC_ERR_NOIPV6
3648
3649       (16): The function which requires IPv6 support was called, but the IPv6
3650       support was not compiled into the application
3651
3652       LIBIRC_ERR_SSL_NOT_SUPPORTED
3653
3654       (17):  The SSL connection was required but the library was not compiled
3655       with SSL support
3656
3657       LIBIRC_ERR_SSL_INIT_FAILED
3658
3659       (18): The SSL library could not be initialized.
3660
3661       LIBIRC_ERR_CONNECT_SSL_FAILED
3662
3663       (19): SSL handshare failed when attempting to connect  to  the  server.
3664       Typically this means you're trying to use SSL but attempting to connect
3665       to a non-SSL port.
3666
3667       LIBIRC_ERR_SSL_CERT_VERIFY_FAILED
3668
3669       (20): The server is using an invalid or  the  self-signed  certificate.
3670       Use LIBIRC_OPTION_SSL_NO_VERIFY option to connect to it.
3671
3672   Options
3673       LIBIRC_OPTION_DEBUG
3674
3675       If set, enables additional debug output which goes to STDOUT.
3676
3677       LIBIRC_OPTION_STRIPNICKS
3678
3679       If set, strips the event origins automatically. Every event has an ori‐
3680       gin (i.e. who originated the event).  The  origin  usually  looks  like
3681       nick!host@ircserver,  i.e.  like  tim!home@irc.server.net. Such origins
3682       can not be used in IRC commands, and need to be stripped (i.e. host and
3683       server  part  should be cut off) before using.  This can be done either
3684       manually by calling irc_target_get_nick(), or automatically for all the
3685       events if this option is set.
3686
3687       LIBIRC_OPTION_SSL_NO_VERIFY
3688
3689       By  default  the  SSL connection is authenticated by verifying that the
3690       certificate presented by the server is signed by a known  trusted  cer‐
3691       tificate authority.  Since those typically cost money, some IRC servers
3692       use the self-signed certificates. They provide the benefits of the  SSL
3693       connection  but since they are not signed by the Certificate Authority,
3694       their authencity cannot be verified. This option, if set, disables  the
3695       certificate verification - the library will accept any certificate pre‐
3696       sented by the server.
3697
3698       This option must be set before the irc_connect function is called.
3699

APPENDIX

3701   Frequently asked questions
3702   Why do I get a LIBIRC_ERR_SOCKET error under  Win32  when  using  a  static
3703       library?
3704       Because  on  Win32  you have to initialize the Winsock API before using
3705       it:
3706
3707          WSADATA wsaData;
3708
3709          if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
3710              // report an error
3711
3712          // Now you can use libircclient
3713
3714       You have to do it ONCE in your application, and since libircclient does
3715       not know whether you already initialized it or not, it does not contain
3716       any Winsock initialization code.
3717
3718   What does it mean that the IRC protocol is event-based?
3719       The IRC protocol itself is asynchronous  and  server-driven.  For  you,
3720       this means the following:
3721
3722          · For  any  IRC  command,  it is not possible to obtain an immediate
3723            response whether the command succeed or not.  Instead  the  server
3724            will send the reply in a short (or long) period of time.
3725
3726          · For  some  IRC  command there is no ‘success’ response at all. For
3727            example, when you send a text message, IRC server  will  not  send
3728            anything to confirm that the message is already sent.
3729
3730          · You  can send several commands to the IRC server, and then receive
3731            several replies regarding every command. The order of the  replies
3732            you receive is generally undefined.
3733
3734          · A  lot  of  IRC events sent to you is generated by other users, or
3735            the IRC server itself, and are sent to you just when they are gen‐
3736            erated.
3737
3738          · Long  lists  (for example, channel lists) are also sent as events.
3739            Moreover, these events could be separated by other events (message
3740            or  notices).  And  it is your responsibility to separate the data
3741            (using event codes), and use some sort of data structure that will
3742            hold  it until the data is complete.  It is not possible to simply
3743            query the list of channels, and expect that its content will imme‐
3744            diately arrive.
3745
3746          · You  may  send  the request, and not receive a response in case of
3747            success (such as when you send  a  message).   You  may  send  the
3748            request  and  it  will  only  succeed  when you receive a response
3749            (which may be after you receive ten more unrelated events). Or you
3750            can  receive  a  response without even sending a request, as it is
3751            the case with JOIN - it is possible for the server to JOIN you  to
3752            a specific channel implicitly.
3753
3754          · You  should  be  prepared  to  expect  the unexpected from the IRC
3755            server. For example, the server can change your nick (seen on most
3756            servers, which use nickserv authentication. You can be “forced” to
3757            join the channel, to say something, to leave a channel, to  change
3758            your  usermode and so on. Listen what IRC server tells you, and do
3759            so.
3760
3761   Why the irc_cmd_join function does not return an error?
3762       A typical example is the irc_cmd_join()  call  always  returns  success
3763       even  when  you attempt to join a password-protected channel. Then some
3764       time later the IRC server returns an error. This is because the irc_cmd
3765       family  of functions return success when the command is sent to the IRC
3766       server. The asynchronous nature of IRC makes it  impossible  to  obtain
3767       the command result immediately. Please read the question above.
3768
3769   How to register/auth with NICKSERV?
3770       There is no ‘standard’ way. NICKSERV, CHANSERV and so on are not speci‐
3771       fied by the RFC. They are IRC extensions which behave exactly like  the
3772       other  IRC users but with more power. Typically their messages are sent
3773       via Notice events, so you can use following algorithm to  handle  Nick‐
3774       serv registration:
3775
3776          static void event_notice (irc_session_t * session, const char * event,
3777                                                           const char * origin, const char ** params, unsigned int count)
3778          {
3779                  char buf[256];
3780
3781                  if ( !origin )
3782                          return;
3783
3784                  if ( strcasecmp (origin, "nickserv") )
3785                          return;
3786
3787                  if ( strstr (params[1], "This nick is not registered") == params[1] )
3788                  {
3789                          sprintf (buf, "REGISTER %s NOMAIL", gCfg.irc_nickserv_password);
3790                          irc_cmd_msg(session, "nickserv", buf);
3791                  }
3792                  else if ( strstr (params[1], "This nickname is registered and protected") == params[1] )
3793                  {
3794                          sprintf (buf, "IDENTIFY %s", gCfg.irc_nickserv_password);
3795                          irc_cmd_msg(session, "nickserv", buf);
3796                  }
3797                  else if ( strstr (params[1], "Password accepted - you are now recognized") == params[1] )
3798                          printf ("Nickserv authentication succeed.");
3799          }
3800
3801       The  idea  is  to parse the messages sent from NICKSERV, and if they’re
3802       matched the specific patterns, react on them appropriately.
3803
3804   What is CTCP?
3805       CTCP abbreviature is deciphered as “Client-to-Client Protocol”.  It  is
3806       used  between the IRC clients to query the remote client for some data,
3807       or to send some information – for example, /me messages  are  sent  via
3808       CTCP.
3809
3810       There  is no standard list of possible CTCP requests, and different IRC
3811       clients often add their own CTCP codes.  The built-in handler reacts on
3812       TIME,  VERSION,  PING  and FINGER CTCP queries. If you need to react on
3813       other requests, you’ll have to write your own  CTCP  handler.  See  the
3814       source  code  of libirc_event_ctcp_internal function to get an idea how
3815       to write it.
3816
3817   When I am made a chanop (+o) why do I not receive the event_umode?
3818       Becoming a channel operator channes the channel mode,  not  user  mode.
3819       Therefore you will receive event_mode and not event_umode
3820
3821       If  you  receive the event_umode with +o this means your user is an IRC
3822       server operator.
3823
3824   What if my application uses epoll?
3825       The library only directly supports the select()-based  loops  for  his‐
3826       toric  reasons,  so  epoll  and other polling methods are not supported
3827       directly by the library.  However but if necessart, it  could  be  emu‐
3828       lated by converting descriptors between select and epoll as following:
3829
3830          · Call irc_add_select_descriptors with an empty FD_SET
3831
3832          · Extract  the descriptors from the fd_set arrays (remember fd_array
3833            is a bitarray, not the value array). There may be  more  than  one
3834            descriptor in case there are DCC sessions.
3835
3836          · Pass  those  descriptors to poll/epoll using relevant events (i.e.
3837            use the EPOLLIN for the descriptors in the in_set)
3838
3839          · For those descriptors which triggered the events, fill up the rel‐
3840            evant  in_set  and  out_set  structures  (again, remember the bit‐
3841            masks!) and pass them to irc_process_select_descriptors()
3842
3843       While this is cumbersome, the operations  are  very  simple  (basically
3844       bitmask  operations on a small structure) and will not add any signifi‐
3845       cant slowdown to your application.
3846
3847   GNU LESSER GENERAL PUBLIC LICENSE
3848       Version 3, 29 June 2007
3849
3850       Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>
3851
3852       Everyone is permitted to copy and distribute verbatim  copies  of  this
3853       license document, but changing it is not allowed.
3854
3855       This  version of the GNU Lesser General Public License incorporates the
3856       terms and conditions of version 3 of the GNU  General  Public  License,
3857       supplemented by the additional permissions listed below.
3858
3859       0.  Additional Definitions.
3860
3861       As  used  herein,  “this License” refers to version 3 of the GNU Lesser
3862       General Public License, and the “GNU GPL” refers to version  3  of  the
3863       GNU General Public License.
3864
3865       “The  Library” refers to a covered work governed by this License, other
3866       than an Application or a Combined Work as defined below.
3867
3868       An “Application” is any work that makes use of an interface provided by
3869       the  Library, but which is not otherwise based on the Library. Defining
3870       a subclass of a class defined by the Library is deemed a mode of  using
3871       an interface provided by the Library.
3872
3873       A  “Combined Work” is a work produced by combining or linking an Appli‐
3874       cation with the Library. The particular version  of  the  Library  with
3875       which the Combined Work was made is also called the “Linked Version”.
3876
3877       The “Minimal Corresponding Source” for a Combined Work means the Corre‐
3878       sponding Source for the Combined Work, excluding any  source  code  for
3879       portions  of the Combined Work that, considered in isolation, are based
3880       on the Application, and not on the Linked Version.
3881
3882       The “Corresponding Application Code” for  a  Combined  Work  means  the
3883       object  code and/or source code for the Application, including any data
3884       and utility programs needed for reproducing the Combined Work from  the
3885       Application,  but  excluding the System Libraries of the Combined Work.
3886       1. Exception to Section 3 of the GNU GPL.
3887
3888       You may convey a covered work under sections 3 and 4  of  this  License
3889       without being bound by section 3 of the GNU GPL.  2. Conveying Modified
3890       Versions.
3891
3892       If you modify a copy of the Library,  and,  in  your  modifications,  a
3893       facility  refers to a function or data to be supplied by an Application
3894       that uses the facility (other than  as  an  argument  passed  when  the
3895       facility  is  invoked), then you may convey a copy of the modified ver‐
3896       sion:
3897
3898          a. under this License, provided that you make a good faith effort to
3899             ensure  that,  in  the  event  an Application does not supply the
3900             function or data, the facility still operates, and performs what‐
3901             ever part of its purpose remains meaningful, or
3902
3903          b. under  the  GNU  GPL,  with none of the additional permissions of
3904             this License applicable to that copy.
3905
3906       3. Object Code Incorporating Material from Library Header Files.
3907
3908       The object code form of an Application may incorporate material from  a
3909       header  file  that  is  part of the Library. You may convey such object
3910       code under terms of your choice, provided  that,  if  the  incorporated
3911       material is not limited to numerical parameters, data structure layouts
3912       and accessors, or small macros, inline functions and templates (ten  or
3913       fewer lines in length), you do both of the following:
3914
3915          a. Give  prominent notice with each copy of the object code that the
3916             Library is used in it and that the Library and its use  are  cov‐
3917             ered by this License.
3918
3919          b. Accompany  the  object  code  with a copy of the GNU GPL and this
3920             license document.
3921
3922       4. Combined Works.
3923
3924       You may convey a Combined Work under terms of your choice  that,  taken
3925       together,  effectively  do not restrict modification of the portions of
3926       the Library contained in the Combined Work and reverse engineering  for
3927       debugging such modifications, if you also do each of the following:
3928
3929          a. Give  prominent  notice  with each copy of the Combined Work that
3930             the Library is used in it and that the Library and  its  use  are
3931             covered by this License.
3932
3933          b. Accompany  the  Combined Work with a copy of the GNU GPL and this
3934             license document.
3935
3936          c. For a Combined Work that displays copyright notices during execu‐
3937             tion,  include  the  copyright notice for the Library among these
3938             notices, as well as a reference directing the user to the  copies
3939             of the GNU GPL and this license document.
3940
3941          d.
3942
3943             Do one of the following:
3944
3945                    0.  Convey  the  Minimal  Corresponding  Source  under the
3946                        terms of this License, and the Corresponding  Applica‐
3947                        tion Code in a form suitable for, and under terms that
3948                        permit, the user to recombine or relink  the  Applica‐
3949                        tion  with a modified version of the Linked Version to
3950                        produce a modified Combined Work, in the manner speci‐
3951                        fied  by section 6 of the GNU GPL for conveying Corre‐
3952                        sponding Source.
3953
3954                    1.  Use a suitable shared library  mechanism  for  linking
3955                        with the Library. A suitable mechanism is one that (a)
3956                        uses at run time a copy of the Library already present
3957                        on  the  user's  computer system, and (b) will operate
3958                        properly with a modified version of the  Library  that
3959                        is interface-compatible with the Linked Version.
3960
3961          e. Provide Installation Information, but only if you would otherwise
3962             be required to provide such information under section  6  of  the
3963             GNU  GPL,  and only to the extent that such information is neces‐
3964             sary to install and execute a modified version  of  the  Combined
3965             Work  produced by recombining or relinking the Application with a
3966             modified version of the Linked Version. (If you use  option  4d0,
3967             the  Installation  Information  must accompany the Minimal Corre‐
3968             sponding Source and Corresponding Application Code.  If  you  use
3969             option  4d1, you must provide the Installation Information in the
3970             manner specified by section 6 of the GNU GPL for conveying Corre‐
3971             sponding Source.)
3972
3973       5. Combined Libraries.
3974
3975       You  may  place library facilities that are a work based on the Library
3976       side by side in a single library together with other library facilities
3977       that are not Applications and are not covered by this License, and con‐
3978       vey such a combined library under terms of your choice, if you do  both
3979       of the following:
3980
3981          a. Accompany the combined library with a copy of the same work based
3982             on the Library, uncombined with  any  other  library  facilities,
3983             conveyed under the terms of this License.
3984
3985          b. Give  prominent  notice with the combined library that part of it
3986             is a work based on the Library, and explaining where to find  the
3987             accompanying uncombined form of the same work.
3988
3989       6. Revised Versions of the GNU Lesser General Public License.
3990
3991       The Free Software Foundation may publish revised and/or new versions of
3992       the GNU Lesser General Public License from time to time. Such new  ver‐
3993       sions  will be similar in spirit to the present version, but may differ
3994       in detail to address new problems or concerns.
3995
3996       Each version is given a distinguishing version number. If  the  Library
3997       as you received it specifies that a certain numbered version of the GNU
3998       Lesser General Public License “or any later version” applies to it, you
3999       have  the  option  of following the terms and conditions either of that
4000       published version or of any later version published by the  Free  Soft‐
4001       ware  Foundation.  If the Library as you received it does not specify a
4002       version number of the GNU Lesser General Public License, you may choose
4003       any  version of the GNU Lesser General Public License ever published by
4004       the Free Software Foundation.
4005
4006       If the Library as you received it specifies that  a  proxy  can  decide
4007       whether  future versions of the GNU Lesser General Public License shall
4008       apply, that proxy's public statement of acceptance of  any  version  is
4009       permanent authorization for you to choose that version for the Library.
4010
4011   Indices and tables
4012       · genindex
4013
4014       · modindex
4015
4016       · search
4017

AUTHOR

4019       George Yunaev
4020
4022       2013, George Yunaev
4023
4024
4025
4026
40271.7                              May 09, 2014                  LIBIRCCLIENT(1)
Impressum