1LIBIRCCLIENT(1) Libircclient LIBIRCCLIENT(1)
2
6 libircclient - Libircclient Documentation
7
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 Features
17 · Comprehensive C API;
18 · Full coverage of the IRC protocol using providing functions;
20 · Supports multiple simultaneous connection to different IRC servers
22 or even to the same server;
23 · Supports both plain and SSL connections to the IRC servers with
25 the optional certificate check;
26 · Full multi-threading support, the library is thread-safe;
28 · All the processing could be handled by a single thread even if
30 multiple connections are used;
31 · Non-blocking, asynchronous event-based interface implemented with
33 callbacks;
34 · Extra support for the socket-based applications, which use
36 select();
37 · CTCP support with optional build-in reply code;
39 · Supports CTCP PING necessary to pass the “spoof check” implemented
41 by most IRC servers;
42 · Flexible DCC support, including both DCC chat, and DCC file trans‐
44 fer;
45 · Can both initiate and react to initiated DCC;
47 · Can accept or decline DCC sessions asynchronously;
49 · Written in plain C, very small binary size (around 30K depending
51 on platform);
52 · Compatible all tested IRC clients;
54 · Free software licensed under the LGPLv3 license;
56 · Supports Linux as well as any POSIX-compliant Unix, Mac OS X and
58 Microsoft Windows;
59 · Supports 32/64bit architectures as well as non-x86 architectures;
61 · IPv6 support (optional, must be compiled in);
63 · OpenSSL support (optional, must be compiled in);
65 · Cocoa interface by Nathan Ollerenshaw;
67 · Comprehensive documentation, examples and the FAQ;
69 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 · 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 · You'd have to handle reconnections separately by processing the
79 relevant irc_process_select_descriptors() return values
80 · 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 · 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 Author
89 This library is created by George Yunaev, copyright 2004-2013.
90 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
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 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 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 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 If the library is built with SSL support, the openssl development pack‐
122 age (openssl-devel) needs to be installed.
123 On Microsoft Windows the Cygwin with necessary development packages
125 must be installed (and openssl-devel as well).
126 Compiling
128 The library is configured and built the standard Unix way:
129 ./configure [--enable-openssl] [--enable-ipv6]
131 make
132 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 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 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 On Microsoft Windows please link with libircclient.lib which implicitly
147 links with libircclient.dll
148 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 #include "libircclient.h"
157 #include "libirc_rfcnumeric.h"
158 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 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 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 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 WSADATA wsaData;
187 if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
189 // report an error
190 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 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 To create a session, call the irc_create_session() function:
202 // The IRC callbacks structure
204 irc_callbacks_t callbacks;
205 // Init it
207 memset ( &callbacks, 0, sizeof(callbacks) );
208 // Set up the mandatory events
210 callbacks.event_connect = event_connect;
211 callbacks.event_numeric = event_numeric;
212 // Set up the rest of events
214 // Now create the session
216 irc_session_t * session = irc_create_session( &callbacks );
217 if ( !session )
219 // Handle the error
220 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 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 irc_option_set( session, LIBIRC_OPTION_STRIPNICKS );
232 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 Connect to the server
238 To initiate the connection to the IRC server, call the irc_connect()
239 function:
240 // 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 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 // 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 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 · If the connection is established, you will receive the event_con‐
258 nect - this is why it is important to handle it
259 · If the connection failed, the networking handler function will
261 return failure
262 Connect to the IPv6 server
264 To initiate the connection to the IPv6 server, call the irc_connect6()
265 function:
266 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 The rest of the details, including the return value and the SSL are the
271 same as with regular connect.
272 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 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 To start the event loop call the irc_run() function:
286 if ( irc_run (s) )
288 // Either the connection to the server could not be established or terminated. See irc_errno()
289 Remember that irc_run() call will not return until the server connec‐
291 tion is not active anymore.
292 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 // Make sure that all the IRC sessions are connected
300 if ( !irc_is_connected(session) )
301 // reconnect it, or abort
302 // Create the structures for select()
304 struct timeval tv;
305 fd_set in_set, out_set;
306 int maxfd = 0;
307 // 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 // Initialize the sets
314 FD_ZERO (&in_set);
315 FD_ZERO (&out_set);
316 // Add your own descriptors you need to wait for, if any
318 ...
319 // 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 // Call select()
324 if ( select (maxfd + 1, &in_set, &out_set, 0, &tv) < 0 )
325 // Error
326 // 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 // 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 // Do it again
336 Channels and users
338 Before calling any of those functions make sure you have connected to
339 the server.
340 Join and leave a channel
342 To join the channel call the irc_cmd_join() function with the channel
343 name:
344 // Join the channel #linux
346 if ( irc_cmd_join( session, "#linux", 0 ) )
347 // most likely connection error
348 // Join the channel $science protected by the secret key *superpassword*
350 if ( irc_cmd_join( session, "$science", "superpassword" ) )
351 // most likely connection error
352 You can join as many channels as you want, although the serer may
354 restrict the number of channels you can join simultaneously.
355 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 If the join was not successful, you will receive the error via
363 event_numeric.
364 To leave the channel call the irc_cmd_part() function with the channel
366 name:
367 // Leave the channel #linux
369 if ( irc_cmd_part( session, "#linux" ) )
370 // most likely connection error
371 // Leave the channel $science
373 if ( irc_cmd_part( session, "$science" ) )
374 // most likely connection error
375 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 // Say "Hi!" to everyone in the channel #linux
381 if ( irc_cmd_msg( session, "#linux", "Hi!" ) )
382 // most likely connection error
383 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 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 // Say "Hi!" to IRC user john
395 if ( irc_cmd_msg( session, "john", "Hi!" ) )
396 // most likely connection error
397 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 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 You receive the "private" messages from other users by handling the
407 event_privmsg.
408 Those event handlers should be created in your application and passed
410 to the library when you create an IRC session
411 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 Same as with sending messages no confirmation is received on success.
419 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 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 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 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 Initiating the DCC CHAT
454 You can initiate the DCC chat with another user by calling
455 irc_dcc_chat():
456 // The DCC chat session id will be returned in this variable
458 irc_dcc_t dccid;
459 // Initiate the DCC chat with the IRC user "john"
461 if ( irc_dcc_chat( session, 0, "john", dcc_callback, &dccid ) )
462 // report error
463 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 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 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 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 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 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 // 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 ...
508 // 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 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 irc_dcc_text( session, dccid, "Hello there!" );
522 Handling DCC file transfer
524 This section covers handling sending and receiving files via DCC.
525 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 // 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 // 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 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 Sending the file via DCC
571 You can initiate sending the file via DCC to another user by calling
572 irc_dcc_sendfile():
573 // The DCC session id will be returned in this variable
575 irc_dcc_t dccid;
576 // 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 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 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 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 If your application does not handle DCC at all you can just call the
601 irc_dcc_decline() function inside the callback.
602 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 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 // 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 ...
625 // 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 Note that it is not possible to request a remote user to send you a
634 file.
635 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 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 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 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 Do not forget to free() the returned pointer once it is not used any‐
660 more.
661 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
671 Callbacks
672 This section describes the callbacks supported by the library.
673 irc_event_callback_t
675 Prototype:
676 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 Parameters:
682 ┌────────┬────────────────────────────┐
684 │session │ The IRC session, which │
685 │ │ generated the event │
686 ├────────┼────────────────────────────┤
687 │event │ The text name of the │
688 │ │ event. Useful in case a │
689 │ │ single event handler is │
690 │ │ used to handle multiple │
691 │ │ events │
692 ├────────┼────────────────────────────┤
693 │origin │ The originator of the │
694 │ │ event. Depends on the │
695 │ │ event. │
696 ├────────┼────────────────────────────┤
697 │params │ 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 ├────────┼────────────────────────────┤
709 │count │ The number of entries in │
710 │ │ the params argument sup‐ │
711 │ │ plied. │
712 └────────┴────────────────────────────┘
713 Description:
715 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 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 irc_event_dcc_chat_t
732 Prototype:
733 typedef void (*irc_event_dcc_chat_t)(irc_session_t * session, const
735 char * nick, const char * addr, irc_dcc_t dccid)
736 Parameters:
738 ┌────────┬────────────────────────────┐
740 │session │ IRC session, which gener‐ │
741 │ │ ates an event (the one │
742 │ │ returned by irc_cre‐ │
743 │ │ ate_session) │
744 └────────┴────────────────────────────┘
745 │nick │ User who requested the │
749 │ │ chat │
750 ├────────┼────────────────────────────┤
751 │addr │ IP address of the person │
752 │ │ such as 189.12.34.56 │
753 ├────────┼────────────────────────────┤
754 │dccid │ 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 Description:
763 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 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 irc_event_dcc_send_t
775 Prototype:
776 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 Parameters:
782 ┌─────────┬────────────────────────────┐
784 │session │ The IRC session, which │
785 │ │ generates an event (the │
786 │ │ one returned by irc_cre‐ │
787 │ │ ate_session) │
788 ├─────────┼────────────────────────────┤
789 │nick │ The user who requested the │
790 │ │ chat │
791 ├─────────┼────────────────────────────┤
792 │addr │ The IP address of the per‐ │
793 │ │ son such as 189.12.34.56 │
794 ├─────────┼────────────────────────────┤
795 │filename │ The name of the file the │
796 │ │ user is trying to send you │
797 ├─────────┼────────────────────────────┤
798 │size │ The size of the file │
799 ├─────────┼────────────────────────────┤
800 │dccid │ 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 Description:
809 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 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 irc_dcc_callback_t
820 Prototype:
821 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 Parameters:
827 ┌────────┬────────────────────────────┐
829 │session │ The IRC session, which │
830 │ │ generates an event (the │
831 │ │ one returned by irc_cre‐ │
832 │ │ ate_session) │
833 ├────────┼────────────────────────────┤
834 │id │ The DCC session id │
835 ├────────┼────────────────────────────┤
836 │status │ The DCC connection status. │
837 │ │ 0 means there is no error, │
838 │ │ otherwise contains an │
839 │ │ error code │
840 ├────────┼────────────────────────────┤
841 │ctx │ The user-provided context │
842 ├────────┼────────────────────────────┤
843 │data │ Data received (if avail‐ │
844 │ │ able), otherwise NULL │
845 ├────────┼────────────────────────────┤
846 │length │ Size of the data received │
847 │ │ if any data │
848 └────────┴────────────────────────────┘
849 Description:
851 This callback is called for all DCC functions when state change occurs.
853 For DCC CHAT, the callback is called as following:
855 · 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 · 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 · status is zero and length is zero: the remote side accepted
866 the chat request
867 · 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 For DCC SEND, while file is being sent, the callback is called as fol‐
874 lowing:
875 · 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 · 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 For DCC RECV, while file is being sending, callback called as follow‐
884 ing:
885 · 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 · 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 · 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 irc_eventcode_callback_t
899 Prototype:
900 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 Parameters:
906 ┌────────┬────────────────────────────┐
908 │session │ The IRC session, which │
909 │ │ generates an event (the │
910 │ │ one returned by irc_cre‐ │
911 │ │ ate_session) │
912 ├────────┼────────────────────────────┤
913 │event │ The numeric code of the │
914 │ │ event. Useful in case a │
915 │ │ single event handler is │
916 │ │ used to handle multiple │
917 │ │ events │
918 ├────────┼────────────────────────────┤
919 │origin │ The originator of the │
920 │ │ event. Depends on the │
921 │ │ event. │
922 ├────────┼────────────────────────────┤
923 │params │ 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 ├────────┼────────────────────────────┤
935 │count │ The number of entries in │
936 │ │ the params argument sup‐ │
937 │ │ plied. │
938 └────────┴────────────────────────────┘
939 Description:
941 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 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 Functions
959 This section describes the functions defined in the library which are
960 grouped by the purpose.
961 Library initialization and shutdown
963 irc_create_session
964 Prototype:
965 irc_session_t * irc_create_session(irc_callbacks_t * callbacks)
967 Parameters:
969 ┌────────────────────────────────────────┐
971 │callbacks | Event callbacks structure, │
972 │which defines several callbacks, which │
973 │will be called on appropriate events. │
974 │Cannot be NULL. │
975 └────────────────────────────────────────┘
976 Description:
978 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 When it is not needed anymore, the session must be destroyed by calling
986 the irc_destroy_session() function.
987 Return value:
989 An irc_session_t object, or 0 if creation failed. Usually, failure is
991 caused by out of memory error.
992 Thread safety:
994 This function can be called simultaneously from multiple threads. Same
996 callback structure may be reused by multiple threads.
997 irc_destroy_session
999 Prototype:
1000 void irc_destroy_session(irc_session_t * session)
1002 Parameters:
1004 ┌─────────────────────────────────┐
1006 │session | The IRC session handle │
1007 └─────────────────────────────────┘
1008 Description:
1010 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 Thread safety:
1016 This function can be called simultaneously from multiple threads.
1018 Connecting, disconnecting and running the main event loop
1020 irc_connect6
1021 Prototype:
1022 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 irc_connect
1028 Prototype:
1029 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 Parameters:
1035 ┌─────────┬────────────────────────────┐
1037 │session │ IRC session handle │
1038 ├─────────┼────────────────────────────┤
1039 │server │ 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 ├─────────┼────────────────────────────┤
1050 │port │ Port number to connect to, │
1051 │ │ usually 6667 │
1052 ├─────────┼────────────────────────────┤
1053 │password │ 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 ├─────────┼────────────────────────────┤
1063 │nick │ Nick which will be used to │
1064 │ │ log into the IRC server. │
1065 │ │ Cannot be NULL │
1066 ├─────────┼────────────────────────────┤
1067 │username │ 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 ├─────────┼────────────────────────────┤
1078 │realname │ 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 Description:
1095 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 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 The connection is established asynchronously, and the event_connect is
1106 called once the connection is established.
1107 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 Return value:
1113 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 Thread safety:
1120 This function can be called simultaneously from multiple threads, but
1122 not using the same session object.
1123 irc_disconnect
1125 Prototype:
1126 void irc_disconnect(irc_session_t * session)
1128 Parameters:
1130 ┌───────────────────────────────┐
1132 │session | IRC session handle │
1133 └───────────────────────────────┘
1134 Description:
1136 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 Thread safety:
1142 This function can be called simultaneously from multiple threads, but
1144 not using the same session object.
1145 irc_is_connected
1147 Prototype:
1148 int irc_is_connected(irc_session_t * session)
1150 Parameters:
1152 ┌────────┬────────────────────┐
1154 │session │ IRC session handle │
1155 └────────┴────────────────────┘
1156 Return value:
1158 This function returns 1 if the connection to the IRC server is estab‐
1160 lished or 0 if it is not.
1161 Thread safety:
1163 This function can be called simultaneously from multiple threads.
1165 irc_run
1167 Prototype:
1168 int irc_run(irc_session_t * session)
1170 Parameters:
1172 ┌────────┬────────────────────┐
1174 │session │ IRC session handle │
1175 └────────┴────────────────────┘
1176 Description:
1178 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 Return value:
1189 This function returns a nonzero value if the connection to the IRC
1191 server could not be established, or was terminated.
1192 Thread safety:
1194 This function cannot be called from multiple threads. Use
1196 irc_add_select_descriptors() and irc_process_select_descriptors()
1197 instead.
1198 irc_add_select_descriptors
1200 Prototype:
1201 int irc_add_select_descriptors(irc_session_t * session, fd_set *in_set,
1203 fd_set *out_set, int * maxfd)
1204 Parameters:
1206 ┌────────┬────────────────────────────┐
1208 │session │ IRC session handle │
1209 ├────────┼────────────────────────────┤
1210 │in_set │ fd_set input descriptor │
1211 │ │ set for select() │
1212 ├────────┼────────────────────────────┤
1213 │out_set │ fd_set output descriptor │
1214 │ │ set for select() │
1215 ├────────┼────────────────────────────┤
1216 │maxfd │ 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 Description:
1224 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 What if you use epoll? See the FAQ
1234 Return value:
1236 This function returns a nonzero value if the irc_connect() was not
1238 called before calling this function.
1239 Thread safety:
1241 This function can be called simultaneously from multiple threads, but
1243 it rarely makes sense.
1244 irc_process_select_descriptors
1246 Prototype:
1247 int irc_process_select_descriptors(irc_session_t * session,
1249 fd_set *in_set, fd_set *out_set)
1250 Parameters:
1252 ┌────────┬────────────────────────────┐
1254 │session │ IRC session handle │
1255 ├────────┼────────────────────────────┤
1256 │in_set │ fd_set input descriptor │
1257 │ │ set for select() │
1258 ├────────┼────────────────────────────┤
1259 │out_set │ fd_set output descriptor │
1260 │ │ set for select() │
1261 └────────┴────────────────────────────┘
1262 Description:
1264 This function should be used in pair with irc_add_select_descriptors()
1266 function, which documentation describes how they work together.
1267 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 Return value:
1274 Return code 0 means success. Other value means error, the error code
1276 may be obtained through irc_errno().
1277 Thread safety:
1279 This function can be called simultaneously from multiple threads for
1281 different IRC session objects only.
1282 Managing the IRC channels: joining, leaving, inviting
1284 irc_cmd_join
1285 Prototype:
1286 int irc_cmd_join(irc_session_t * session, const char * channel, const
1288 char * key)
1289 Parameters:
1291 ┌────────┬────────────────────────────┐
1293 │session │ IRC session handle │
1294 ├────────┼────────────────────────────┤
1295 │channel │ Channel name to join. Can‐ │
1296 │ │ not be NULL. │
1297 ├────────┼────────────────────────────┤
1298 │key │ Secret key for the chan‐ │
1299 │ │ nel. Can be NULL if not │
1300 │ │ needed │
1301 └────────┴────────────────────────────┘
1302 Description:
1304 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 Return value:
1315 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 Possible error responces for this command from the RFC1459:
1322 · LIBIRC_RFC_ERR_BANNEDFROMCHAN
1324 · LIBIRC_RFC_ERR_INVITEONLYCHAN
1326 · LIBIRC_RFC_ERR_BADCHANNELKEY
1328 · LIBIRC_RFC_ERR_CHANNELISFULL
1330 · LIBIRC_RFC_ERR_BADCHANMASK
1332 · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1334 · LIBIRC_RFC_ERR_TOOMANYCHANNELS
1336 Thread safety:
1338 This function can be called simultaneously from multiple threads.
1340 irc_cmd_part
1342 Prototype:
1343 int irc_cmd_part(irc_session_t * session, const char * channel)
1345 Parameters:
1347 ┌────────┬────────────────────────────┐
1349 │session │ IRC session handle │
1350 ├────────┼────────────────────────────┤
1351 │channel │ Channel name to leave. │
1352 │ │ Cannot be NULL. │
1353 └────────┴────────────────────────────┘
1354 Description:
1356 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 Return value:
1362 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 Possible error responces for this command from the RFC1459:
1369 · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1371 · LIBIRC_RFC_ERR_NOTONCHANNEL
1373 Thread safety:
1375 This function can be called simultaneously from multiple threads.
1377 irc_cmd_invite
1379 Prototype:
1380 int irc_cmd_invite(irc_session_t * session, const char * nick, const
1382 char * channel)
1383 Parameters:
1385 ┌────────┬────────────────────────────┐
1387 │session │ IRC session handle │
1388 ├────────┼────────────────────────────┤
1389 │nick │ Nick name of the user to │
1390 │ │ invite │
1391 ├────────┼────────────────────────────┤
1392 │channel │ Channel name to join. Can‐ │
1393 │ │ not be NULL │
1394 └────────┴────────────────────────────┘
1395 Description:
1397 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 Return value:
1405 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 On success one of the following replies returned:
1412 · LIBIRC_RFC_RPL_INVITING
1414 · LIBIRC_RFC_RPL_AWAY
1416 Possible error responces for this command from the RFC1459:
1418 · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1420 · LIBIRC_RFC_ERR_NOSUCHNICK
1422 · LIBIRC_RFC_ERR_NOTONCHANNEL
1424 · LIBIRC_RFC_ERR_ERR_USERONCHANNEL
1426 · LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED
1428 Thread safety:
1430 This function can be called simultaneously from multiple threads.
1432 irc_cmd_names
1434 Prototype:
1435 int irc_cmd_names (irc_session_t * session, const char * channel);
1437 Parameters:
1439 ┌────────┬────────────────────────────┐
1441 │session │ IRC session handle │
1442 └────────┴────────────────────────────┘
1443 │channel │ A channel name(s) to │
1447 │ │ obtain user list. Multiple │
1448 │ │ channel names must be sep‐ │
1449 │ │ arated by a comma │
1450 └────────┴────────────────────────────┘
1451 Description:
1453 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 Return value:
1461 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 The channel names are returned by event_numeric event using the follow‐
1468 ing reply codes:
1469 · LIBIRC_RFC_RPL_NAMREPLY
1471 · LIBIRC_RFC_RPL_ENDOFNAMES
1473 Thread safety:
1475 This function can be called simultaneously from multiple threads.
1477 irc_cmd_list
1479 Prototype:
1480 int irc_cmd_list(irc_session_t * session, const char * channel)
1482 Parameters:
1484 ┌────────┬────────────────────────────┐
1486 │session │ IRC session handle │
1487 ├────────┼────────────────────────────┤
1488 │channel │ 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 Description:
1496 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 Return value:
1506 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 The list of channels is returned by event_numeric event using the fol‐
1513 lowing reply codes:
1514 · LIBIRC_RFC_RPL_LISTSTART
1516 · LIBIRC_RFC_RPL_LISTEND
1518 · LIBIRC_RFC_RPL_LIST
1520 Thread safety:
1522 This function can be called simultaneously from multiple threads.
1524 irc_cmd_topic
1526 Prototype:
1527 int irc_cmd_topic(irc_session_t * session, const char * channel, const
1529 char * topic)
1530 Parameters:
1532 ┌────────┬────────────────────────────┐
1534 │session │ IRC session handle │
1535 ├────────┼────────────────────────────┤
1536 │channel │ A channel name │
1537 ├────────┼────────────────────────────┤
1538 │topic │ 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 Description:
1546 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 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 Return value:
1559 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 The topic information is returned using one of following reply codes:
1566 · LIBIRC_RFC_RPL_NOTOPIC
1568 · LIBIRC_RFC_RPL_TOPIC
1570 If the topic change was requested and it was successfully changed, the
1572 event_topic is generated as well.
1573 Possible error responces for this command from the RFC1459:
1575 · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1577 · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1579 · LIBIRC_RFC_ERR_NOTONCHANNEL
1581 Thread safety:
1583 This function can be called simultaneously from multiple threads.
1585 irc_cmd_channel_mode
1587 Prototype:
1588 int irc_cmd_channel_mode(irc_session_t * session, const char * channel,
1590 const char * mode)
1591 Parameters:
1593 ┌────────┬────────────────────────────┐
1595 │session │ IRC session handle │
1596 ├────────┼────────────────────────────┤
1597 │channel │ A channel name │
1598 ├────────┼────────────────────────────┤
1599 │mode │ A mode to change. If NULL, │
1600 │ │ the channel mode is not │
1601 │ │ changed but the old mode │
1602 │ │ is returned │
1603 └────────┴────────────────────────────┘
1604 Description:
1606 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 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 Here is the list of 'standard' channel modes:
1618 ┌───────────┬────────────────────────────┐
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 │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 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 Return value:
1716 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 The old mode information is returned by using following numeric codes:
1723 · LIBIRC_RFC_RPL_CHANNELMODEIS
1725 · LIBIRC_RFC_RPL_BANLIST
1727 · LIBIRC_RFC_RPL_ENDOFBANLIST
1729 Possible error responces for this command from the RFC1459:
1731 · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1733 · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1735 · LIBIRC_RFC_ERR_NOSUCHNICK
1737 · LIBIRC_RFC_ERR_NOTONCHANNEL
1739 · LIBIRC_RFC_ERR_KEYSET
1741 · LIBIRC_RFC_ERR_UNKNOWNMODE
1743 · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1745 Thread safety:
1747 This function can be called simultaneously from multiple threads.
1749 irc_cmd_user_mode
1751 Prototype:
1752 int irc_cmd_user_mode(irc_session_t * session, const char * mode)
1754 Parameters:
1756 ┌────────┬────────────────────────────┐
1758 │session │ IRC session handle │
1759 ├────────┼────────────────────────────┤
1760 │mode │ A mode to change. If NULL, │
1761 │ │ the user mode is not │
1762 │ │ changed but the old mode │
1763 │ │ is returned │
1764 └────────┴────────────────────────────┘
1765 Description:
1767 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 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 Here is the list of 'standard' user modes:
1777 ┌──┬────────────────────────────┐
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 │x │ NON-STANDARD MODE. If set, │
1808 │ │ user's real IP is masked │
1809 │ │ by the IRC server │
1810 └──┴────────────────────────────┘
1811 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 Return value:
1817 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 The old mode information is returned by using the numeric code
1824 LIBIRC_RFC_RPL_UMODEIS:
1825 Possible error responces for this command from the RFC1459:
1827 · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1829 · LIBIRC_RFC_ERR_NOSUCHNICK
1831 · LIBIRC_RFC_ERR_UNKNOWNMODE
1833 · LIBIRC_RFC_ERR_USERSDONTMATCH
1835 · LIBIRC_RFC_ERR_UMODEUNKNOWNFLAG
1837 Thread safety:
1839 This function can be called simultaneously from multiple threads.
1841 irc_cmd_kick
1843 Prototype:
1844 int irc_cmd_kick (irc_session_t * session, const char * nick, const
1846 char * channel, const char * reason);
1847 Parameters:
1849 ┌────────┬────────────────────────────┐
1851 │session │ IRC session handle │
1852 ├────────┼────────────────────────────┤
1853 │nick │ The nick to kick │
1854 ├────────┼────────────────────────────┤
1855 │channel │ The channel to kick the │
1856 │ │ nick from │
1857 ├────────┼────────────────────────────┤
1858 │nick │ If not NULL, the reason to │
1859 │ │ kick the user │
1860 └────────┴────────────────────────────┘
1861 Description:
1863 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 Return value:
1868 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 If the command succeed, the event_kick will be generated.
1875 If the command failed, one of the following event_numeric responses
1877 will be generated:
1878 · LIBIRC_RFC_ERR_NEEDMOREPARAMS
1880 · LIBIRC_RFC_ERR_BADCHANMASK
1882 · LIBIRC_RFC_ERR_NOSUCHCHANNEL
1884 · LIBIRC_RFC_ERR_NOTONCHANNEL
1886 · LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
1888 Thread safety:
1890 This function can be called simultaneously from multiple threads.
1892 Sending the messages, notices, /me messages and working with CTCP
1894 irc_cmd_msg
1895 Prototype:
1896 int irc_cmd_msg(irc_session_t * session, const char * nch, const char
1898 * text)
1899 Parameters:
1901 ┌────────┬────────────────────────────┐
1903 │session │ IRC session handle │
1904 ├────────┼────────────────────────────┤
1905 │nch │ Target nick or target │
1906 │ │ channel │
1907 ├────────┼────────────────────────────┤
1908 │text │ Message text │
1909 └────────┴────────────────────────────┘
1910 Description:
1912 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 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 Return value:
1925 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 If the command succeed, no event is typically generated except the pos‐
1931 sibility of LIBIRC_RFC_RPL_AWAY.
1932 However if the command failed, one of the following numeric events may
1934 be generated:
1935 · LIBIRC_RFC_ERR_NORECIPIENT
1937 · LIBIRC_RFC_ERR_NOTEXTTOSEND
1939 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1941 · LIBIRC_RFC_ERR_NOTONCHANNEL
1943 · LIBIRC_RFC_ERR_NOTOPLEVEL
1945 · LIBIRC_RFC_ERR_WILDTOPLEVEL
1947 · LIBIRC_RFC_ERR_TOOMANYTARGETS
1949 · LIBIRC_RFC_ERR_NOSUCHNICK
1951 Thread safety:
1953 This function can be called simultaneously from multiple threads.
1955 irc_cmd_me
1957 Prototype:
1958 int irc_cmd_me(irc_session_t * session, const char * nch, const char
1960 * text)
1961 Parameters:
1963 ┌────────┬────────────────────────────┐
1965 │session │ IRC session handle │
1966 ├────────┼────────────────────────────┤
1967 │nch │ Target nick or target │
1968 │ │ channel │
1969 ├────────┼────────────────────────────┤
1970 │text │ Message text │
1971 └────────┴────────────────────────────┘
1972 Description:
1974 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 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 Return value:
1988 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 If the command succeed, no event is typically generated except the pos‐
1994 sibility of LIBIRC_RFC_RPL_AWAY.
1995 However if the command failed, one of the following numeric events may
1997 be generated:
1998 · LIBIRC_RFC_ERR_NORECIPIENT
2000 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2002 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2004 · LIBIRC_RFC_ERR_NOTONCHANNEL
2006 · LIBIRC_RFC_ERR_NOTOPLEVEL
2008 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2010 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2012 · LIBIRC_RFC_ERR_NOSUCHNICK
2014 Thread safety:
2016 This function can be called simultaneously from multiple threads.
2018 irc_cmd_notice
2020 Prototype:
2021 int irc_cmd_notice(irc_session_t * session, const char * nch, const
2023 char * text)
2024 Parameters:
2026 ┌────────┬────────────────────────────┐
2030 │session │ IRC session handle │
2031 ├────────┼────────────────────────────┤
2032 │nch │ Target nick or target │
2033 │ │ channel │
2034 ├────────┼────────────────────────────┤
2035 │text │ Message text │
2036 └────────┴────────────────────────────┘
2037 Description:
2039 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 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 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 Return value:
2056 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 If the command succeed, no event is typically generated except the pos‐
2063 sibility of LIBIRC_RFC_RPL_AWAY.
2064 However if the command failed, one of the following numeric events may
2066 be generated:
2067 · LIBIRC_RFC_ERR_NORECIPIENT
2069 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2071 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2073 · LIBIRC_RFC_ERR_NOTONCHANNEL
2075 · LIBIRC_RFC_ERR_NOTOPLEVEL
2077 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2079 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2081 · LIBIRC_RFC_ERR_NOSUCHNICK
2083 Thread safety:
2085 This function can be called simultaneously from multiple threads.
2087 irc_cmd_ctcp_request
2089 Prototype:
2090 int irc_cmd_ctcp_request(irc_session_t * session, const char * nick,
2092 const char * request)
2093 Parameters:
2095 ┌────────┬────────────────────┐
2097 │session │ IRC session handle │
2098 ├────────┼────────────────────┤
2099 │nick │ Target nick │
2100 └────────┴────────────────────┘
2101 │request │ CTCP request tex │
2104 └────────┴────────────────────┘
2105 Description:
2107 This function is used to send a CTCP request. There are four CTCP
2109 requests supported by most IRC clients:
2110 · VERSION - get the client software name and version
2112 · FINGER - get the client username, host and real name.
2114 · PING - get the client delay.
2116 · TIME - get the client local time.
2118 Some clients may support other requests. The RFC does not list the
2120 requests and does not mandate any CTCP support.
2121 If you send the CTCP request, make sure you define the handler for the
2123 event_ctcp_rep to process the reply;
2124 Return value:
2126 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 Possible error responces for this command from the RFC1459:
2133 · LIBIRC_RFC_ERR_NORECIPIENT
2135 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2137 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2139 · LIBIRC_RFC_ERR_NOTONCHANNEL
2141 · LIBIRC_RFC_ERR_NOTOPLEVEL
2143 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2145 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2147 · LIBIRC_RFC_ERR_NOSUCHNICK
2149 Thread safety:
2151 This function can be called simultaneously from multiple threads.
2153 irc_cmd_ctcp_reply
2155 Prototype:
2156 int irc_cmd_ctcp_reply(irc_session_t * session, const char * nick,
2158 const char * reply)
2159 Parameters:
2161 ┌────────┬────────────────────┐
2163 │session │ IRC session handle │
2164 ├────────┼────────────────────┤
2165 │nick │ Target nick │
2166 ├────────┼────────────────────┤
2167 │reply │ CTCP reply │
2168 └────────┴────────────────────┘
2169 Description:
2171 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 Return value:
2177 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 Possible error responces for this command from the RFC1459:
2184 · LIBIRC_RFC_ERR_NORECIPIENT
2186 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2188 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2190 · LIBIRC_RFC_ERR_NOTONCHANNEL
2192 · LIBIRC_RFC_ERR_NOTOPLEVEL
2194 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2196 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2198 · LIBIRC_RFC_ERR_NOSUCHNICK
2200 Thread safety:
2202 This function can be called simultaneously from multiple threads.
2204 Miscellaneous: library version, raw data, changing nick, quitting
2206 irc_cmd_nick
2207 Prototype:
2208 int irc_cmd_nick(irc_session_t * session, const char * newnick)
2210 Parameters:
2212 ┌────────┬────────────────────┐
2214 │session │ IRC session handle │
2215 ├────────┼────────────────────┤
2216 │nick │ New nick │
2217 └────────┴────────────────────┘
2218 Description:
2220 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 Return value:
2227 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 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 · LIBIRC_RFC_ERR_NONICKNAMEGIVEN
2238 · LIBIRC_RFC_ERR_ERRONEUSNICKNAME
2240 · LIBIRC_RFC_ERR_NICKNAMEINUSE
2242 · LIBIRC_RFC_ERR_NICKCOLLISION
2244 Thread safety:
2246 This function can be called simultaneously from multiple threads.
2248 irc_cmd_whois
2250 Prototype:
2251 int irc_cmd_whois(irc_session_t * session, const char * nick)
2253 Parameters:
2255 ┌────────┬────────────────────────────┐
2257 │session │ IRC session handle │
2258 ├────────┼────────────────────────────┤
2259 │nick │ Nick or comma-separated │
2260 │ │ list of nicks to query the │
2261 │ │ information about │
2262 └────────┴────────────────────────────┘
2263 Description:
2265 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 Return value:
2272 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 If the request succeed, the information is returned through the follow‐
2278 ing numeric codes which return the information:
2279 · LIBIRC_RFC_RPL_WHOISUSER
2281 · LIBIRC_RFC_RPL_WHOISCHANNELS
2283 · LIBIRC_RFC_RPL_WHOISSERVER
2285 · LIBIRC_RFC_RPL_AWAY
2287 · LIBIRC_RFC_RPL_WHOISOPERATOR
2289 · LIBIRC_RFC_RPL_WHOISIDLE
2291 · LIBIRC_RFC_RPL_ENDOFWHOIS - this event terminates the WHOIS
2293 information
2294 Possible error responces for this command from the RFC1459:
2296 · LIBIRC_RFC_ERR_NOSUCHSERVER
2298 · LIBIRC_RFC_ERR_NOSUCHNICK
2300 · LIBIRC_RFC_ERR_NONICKNAMEGIVEN
2302 Thread safety:
2304 This function can be called simultaneously from multiple threads.
2306 irc_cmd_quit
2308 Prototype:
2309 int irc_cmd_quit(irc_session_t * session, const char * reason)
2311 Parameters:
2313 ┌────────┬────────────────────────────┐
2315 │session │ IRC session handle │
2316 ├────────┼────────────────────────────┤
2317 │reason │ If not NULL, the reason to │
2318 │ │ quit │
2319 └────────┴────────────────────────────┘
2320 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 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 Return value:
2332 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 Thread safety:
2339 This function can be called simultaneously from multiple threads.
2341 irc_send_raw
2343 Prototype:
2344 int irc_send_raw (irc_session_t * session, const char * format, ...);
2346 Parameters:
2348 ┌────────┬────────────────────────────┐
2350 │session │ IRC session handle │
2351 ├────────┼────────────────────────────┤
2352 │format │ printf-type formatting │
2353 │ │ string followed by the │
2354 │ │ format arguments │
2355 └────────┴────────────────────────────┘
2356 Description:
2358 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 Return value:
2364 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 Thread safety:
2371 This function can be called simultaneously from multiple threads.
2373 irc_target_get_nick
2375 Prototype:
2376 void irc_target_get_nick(const char * origin, char *nick, size_t size)
2378 Parameters:
2380 ┌───────┬────────────────────────────┐
2382 │origin │ Nick in the common IRC │
2383 │ │ server format such as │
2384 │ │ tim!root@mycomain.com │
2385 ├───────┼────────────────────────────┤
2386 │nick │ Buffer to retrieve the │
2387 │ │ parsed nick name │
2388 ├───────┼────────────────────────────┤
2389 │size │ Size of the nick buffer. │
2390 │ │ If the parsed nick is │
2391 │ │ larger than the buffer │
2392 │ │ size it will be truncated │
2393 └───────┴────────────────────────────┘
2394 Description:
2396 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 A buffer of size 128 should be enough for most nicks.
2404 Thread safety:
2406 This function can be called simultaneously from multiple threads.
2408 irc_target_get_host
2410 Prototype:
2411 void irc_target_get_host(const char * target, char *host, size_t size)
2413 Parameters:
2415 ┌───────┬────────────────────────────┐
2417 │origin │ Nick in the common IRC │
2418 │ │ server format such as │
2419 │ │ tim!root@mycomain.com │
2420 ├───────┼────────────────────────────┤
2421 │host │ Buffer to retrieve the │
2422 │ │ parsed hostname │
2423 ├───────┼────────────────────────────┤
2424 │size │ Size of the host buffer. │
2425 │ │ If the parsed nick is │
2426 │ │ larger than the buffer │
2427 │ │ size it will be truncated │
2428 └───────┴────────────────────────────┘
2429 Description:
2431 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 Thread safety:
2438 This function can be called simultaneously from multiple threads.
2440 DCC initiating and accepting chat sessions, sending and receiving files
2442 irc_dcc_chat
2443 Prototype:
2444 int irc_dcc_chat(irc_session_t * session, void * ctx, const char
2446 * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid)
2447 Parameters:
2449 ┌─────────┬────────────────────────────┐
2451 │session │ IRC session handle │
2452 ├─────────┼────────────────────────────┤
2453 │ctx │ User-defined context which │
2454 │ │ will be passed to the │
2455 │ │ callback. May be NULL │
2456 ├─────────┼────────────────────────────┤
2457 │nick │ Target nick │
2458 ├─────────┼────────────────────────────┤
2459 │callback │ DCC callback which will be │
2460 │ │ used for DCC and chat │
2461 │ │ events │
2462 ├─────────┼────────────────────────────┤
2463 │dccid │ If this function succeeds, │
2464 │ │ the DCC session identifier │
2465 │ │ is stored in this field │
2466 └─────────┴────────────────────────────┘
2467 Description:
2469 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 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 · The chat request is accepted;
2480 · The chat request is denied;
2482 · The new chat message is received;
2484 · The chat is terminated by the remote party;
2486 See the details in irc_dcc_callback_t declaration.
2488 Return value:
2490 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 Possible error responces for this command from the RFC1459:
2497 · LIBIRC_RFC_ERR_NORECIPIENT
2499 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2501 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2503 · LIBIRC_RFC_ERR_NOTONCHANNEL
2505 · LIBIRC_RFC_ERR_NOTOPLEVEL
2507 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2509 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2511 · LIBIRC_RFC_ERR_NOSUCHNICK
2513 Thread safety:
2515 This function can be called simultaneously from multiple threads.
2517 irc_dcc_msg
2519 Prototype:
2520 int irc_dcc_msg(irc_session_t * session, irc_dcc_t dccid, const char
2522 * text)
2523 Parameters:
2525 ┌────────┬────────────────────────────┐
2527 │session │ IRC session handle │
2528 ├────────┼────────────────────────────┤
2529 │dccid │ DCC session identifier for │
2530 │ │ the DCC CHAT session which │
2531 │ │ is active │
2532 ├────────┼────────────────────────────┤
2533 │text │ NULL-terminated message to │
2534 │ │ send │
2535 └────────┴────────────────────────────┘
2536 Description:
2538 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 Return value:
2544 Return code 0 means success. Other value means error, the error code
2546 may be obtained through irc_errno().
2547 Thread safety:
2549 This function can be called simultaneously from multiple threads.
2551 irc_dcc_accept
2553 Prototype:
2554 int irc_dcc_accept(irc_session_t * session, irc_dcc_t dccid, void
2556 * ctx, irc_dcc_callback_t callback)
2557 Parameters:
2559 ┌─────────┬────────────────────────────┐
2561 │session │ IRC session handle │
2562 ├─────────┼────────────────────────────┤
2563 │dccid │ DCC session identifier │
2564 │ │ returned by the callback │
2565 ├─────────┼────────────────────────────┤
2566 │ctx │ User-defined context which │
2567 │ │ will be passed to the │
2568 │ │ callback. May be NULL │
2569 ├─────────┼────────────────────────────┤
2570 │callback │ DCC callback which will be │
2571 │ │ used for DCC and chat │
2572 │ │ events │
2573 └─────────┴────────────────────────────┘
2574 Description:
2576 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 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 Return value:
2591 Return code 0 means success. Other value means error, the error code
2593 may be obtained through irc_errno().
2594 Thread safety:
2596 This function can be called simultaneously from multiple threads.
2598 irc_dcc_decline
2600 Prototype:
2601 int irc_dcc_decline(irc_session_t * session, irc_dcc_t dccid)
2603 Parameters:
2605 ┌────────┬────────────────────────────┐
2607 │session │ IRC session handle │
2608 ├────────┼────────────────────────────┤
2609 │dccid │ DCC session identifier │
2610 │ │ returned by the callback │
2611 └────────┴────────────────────────────┘
2612 Description:
2614 This function declines a remote DCC chat or file transfer request.
2616 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 Do not use this function to forecefully close the previously accepted
2626 or initiated DCC session. Use irc_dcc_destroy() instead.
2627 Return value:
2629 Return code 0 means success. Other value means error, the error code
2631 may be obtained through irc_errno().
2632 Thread safety:
2634 This function can be called simultaneously from multiple threads.
2636 irc_dcc_sendfile
2638 Prototype:
2639 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 Parameters:
2645 ┌─────────┬────────────────────────────┐
2647 │session │ IRC session handle │
2648 ├─────────┼────────────────────────────┤
2649 │ctx │ User-defined context which │
2650 │ │ will be passed to the │
2651 │ │ callback. May be NULL │
2652 ├─────────┼────────────────────────────┤
2653 │nick │ Target nick │
2654 ├─────────┼────────────────────────────┤
2655 │filename │ Full path to the file │
2656 │ │ which will be sent. Must │
2657 │ │ be an existing file │
2658 ├─────────┼────────────────────────────┤
2659 │callback │ DCC callback which will be │
2660 │ │ used for DCC and chat │
2661 │ │ events │
2662 ├─────────┼────────────────────────────┤
2663 │dccid │ If this function succeeds, │
2664 │ │ the DCC session identifier │
2665 │ │ is stored in this field │
2666 └─────────┴────────────────────────────┘
2667 Description:
2669 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 Return value:
2676 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 Possible error responces for this command from the RFC1459:
2683 · LIBIRC_RFC_ERR_NORECIPIENT
2685 · LIBIRC_RFC_ERR_NOTEXTTOSEND
2687 · LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
2689 · LIBIRC_RFC_ERR_NOTONCHANNEL
2691 · LIBIRC_RFC_ERR_NOTOPLEVEL
2693 · LIBIRC_RFC_ERR_WILDTOPLEVEL
2695 · LIBIRC_RFC_ERR_TOOMANYTARGETS
2697 · LIBIRC_RFC_ERR_NOSUCHNICK
2699 Thread safety:
2701 This function can be called simultaneously from multiple threads.
2703 irc_dcc_destroy
2705 Prototype:
2706 int irc_dcc_destroy(irc_session_t * session, irc_dcc_t dccid)
2708 Parameters:
2710 ┌────────┬────────────────────────────┐
2712 │session │ IRC session handle │
2713 ├────────┼────────────────────────────┤
2714 │dccid │ DCC session identifier of │
2715 │ │ a session to destroy │
2716 └────────┴────────────────────────────┘
2717 Description:
2719 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 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 Return value:
2728 Return code 0 means success. Other value means error, the error code
2730 may be obtained through irc_errno().
2731 Thread safety:
2733 This function can be called simultaneously from multiple threads.
2735 Handling the colored messages
2737 irc_color_strip_from_mirc
2738 Prototype:
2739 char * irc_color_strip_from_mirc(const char * message)
2741 Parameters:
2743 ┌────────┬────────────────────────────┐
2745 │message │ Original message with col‐ │
2746 │ │ ors │
2747 └────────┴────────────────────────────┘
2748 Description:
2750 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 This function does not modify the message which doesn't use colors.
2757 Return value:
2759 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 Thread safety:
2766 This function can be called simultaneously from multiple threads.
2768 irc_color_convert_from_mirc
2770 Prototype:
2771 char * irc_color_convert_from_mirc(const char * message)
2773 Parameters:
2775 ┌────────┬────────────────────────────┐
2778 │message │ Original message with col‐ │
2779 │ │ ors │
2780 └────────┴────────────────────────────┘
2781 Description:
2783 This function converts all the color codes and format options to libir‐
2785 cclient internal colors.
2786 Return value:
2788 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 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 Thread safety:
2797 This function can be called simultaneously from multiple threads.
2799 irc_color_convert_to_mirc
2801 Prototype:
2802 char * irc_color_convert_to_mirc(const char * message)
2804 Parameters:
2806 ┌────────┬────────────────────────────┐
2808 │message │ Original message with col‐ │
2809 │ │ ors │
2810 └────────┴────────────────────────────┘
2811 Description:
2813 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 Return value:
2819 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 Thread safety:
2826 This function can be called simultaneously from multiple threads.
2828 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 The possible codes are:
2834 · [B] ... [/B] - bold format mode. Everything between [B] and
2836 [/B] is written in bold.
2837 · [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 · [U] ... [/U] - underline format mode. Everything between [U]
2845 and [/U] is written underlined.
2846 · [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 · [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 The following colors are supported:
2857 · WHITE
2859 · BLACK
2861 · DARKBLUE
2863 · DARKGREEN
2865 · RED
2867 · BROWN
2869 · PURPLE
2871 · OLIVE
2873 · YELLOW
2875 · GREEN
2877 · TEAL
2879 · CYAN
2881 · BLUE
2883 · MAGENTA
2885 · DARKGRAY
2887 · LIGHTGRAY
2889 Examples of color sequences:
2891 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 Changing the library options
2897 irc_get_version
2898 Prototype:
2899 void irc_get_version(unsigned int * high, unsigned int * low)
2901 Parameters:
2903 ┌─────┬────────────────────────────┐
2905 │high │ Stores the high version │
2906 │ │ number │
2907 ├─────┼────────────────────────────┤
2908 │low │ Stores the low version │
2909 │ │ number │
2910 └─────┴────────────────────────────┘
2911 Description:
2913 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 printf ("Version: %d.%02d", high, low);
2920 Thread safety:
2922 This function can be called simultaneously from multiple threads.
2924 irc_set_ctx
2926 Prototype:
2927 void irc_set_ctx(irc_session_t * session, void * ctx)
2929 Parameters:
2931 ┌────────┬──────────────────────┐
2933 │session │ IRC session handle │
2934 ├────────┼──────────────────────┤
2935 │ctx │ User-defined context │
2936 └────────┴──────────────────────┘
2937 Description:
2939 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 Thread safety:
2949 This function can be called simultaneously from multiple threads.
2951 irc_get_ctx
2953 Prototype:
2954 void * irc_get_ctx(irc_session_t * session)
2956 Parameters:
2958 ┌────────┬────────────────────┐
2960 │session │ IRC session handle │
2961 └────────┴────────────────────┘
2962 Description:
2964 This function returns the IRC session context, which was set by
2966 irc_set_ctx.
2967 Return value:
2969 If no context was set, this function returns NULL.
2971 Thread safety:
2973 This function can be called simultaneously from multiple threads.
2975 irc_option_set
2977 Prototype:
2978 void irc_option_set(irc_session_t * session, unsigned int option)
2980 Parameters:
2982 ┌────────┬────────────────────────────┐
2984 │session │ IRC session handle │
2985 ├────────┼────────────────────────────┤
2986 │option │ One of the Libirc options │
2987 │ │ to set │
2988 └────────┴────────────────────────────┘
2989 Description:
2991 This function sets the libircclient option, changing libircclient
2993 behavior. See the options list for the meaning for every option.
2994 Thread safety:
2996 This function can be called simultaneously from multiple threads.
2998 irc_option_reset
3000 Prototype:
3001 void irc_option_reset(irc_session_t * session, unsigned int option)
3003 Parameters:
3005 ┌────────┬────────────────────────────┐
3010 │session │ IRC session handle │
3011 ├────────┼────────────────────────────┤
3012 │option │ One of the Libirc options │
3013 │ │ to set │
3014 └────────┴────────────────────────────┘
3015 Description:
3017 This function resets the libircclient option, changing libircclient
3019 behavior. See the options list for the meaning for every option.
3020 Thread safety:
3022 This function can be called simultaneously from multiple threads.
3024 Handling the errors
3026 irc_errno
3027 Prototype:
3028 int irc_errno(irc_session_t * session)
3030 Parameters:
3032 ┌────────┬────────────────────┐
3034 │session │ IRC session handle │
3035 └────────┴────────────────────┘
3036 Description:
3038 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 As usual, typical errno rules apply:
3044 · irc_errno() should be called ONLY if the called function fails;
3046 · irc_errno() doesn't return 0 if function succeed; actually, the
3048 return value will be undefined.
3049 · you should call irc_errno() IMMEDIATELY after function fails,
3051 before calling any other libircclient function.
3052 Return value:
3054 The error code.
3056 Thread safety:
3058 This function can be called simultaneously from multiple threads. Local
3060 error code is per IRC context, not per thread.
3061 irc_strerror
3063 Prototype:
3064 const char * irc_strerror(int ircerrno)
3066 Parameters:
3068 ┌─────────┬────────────────────────────┐
3070 │ircerrno │ IRC error code returned by │
3071 │ │ irc_errno() │
3072 └─────────┴────────────────────────────┘
3073 Description:
3075 This function returns the text representation of the given error code.
3077 Return value:
3079 Returns an internal English string with a short description of the
3081 error code.
3082 Thread safety:
3084 This function can be called simultaneously from multiple threads.
3086 Types
3088 This section describes various types defined by the library.
3089 irc_session_t
3091 typedef struct irc_session_s irc_session_t
3092 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 Once the handle is not used anymore, it should be destroyed by calling
3099 irc_destroy_session().
3100 irc_dcc_session_t
3102 typedef struct irc_dcc_session_s irc_dcc_session_t
3103 This structure describes a DCC session used by libircclient. Its mem‐
3105 bers are internal to libircclient, and should not be used directly.
3106 irc_dcc_t
3108 typedef unsigned int irc_dcc_t
3109 This type is a DCC session identifier, used to identify the DCC ses‐
3111 sions in callbacks and various functions.
3112 irc_callbacks_t
3114 typedef struct irc_callbacks_t
3115 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 Describes the event callbacks structure which is used in registering
3142 the callbacks.
3143 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 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 event_connect
3156 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 This event uses irc_event_callback_t callback with the following val‐
3162 ues:
3163 ┌───────┬─────────────────────┐
3166 │origin │ Unused, set to NULL │
3167 ├───────┼─────────────────────┤
3168 │params │ Unused, set to NULL │
3169 └───────┴─────────────────────┘
3170 event_nick
3172 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 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 This event uses irc_event_callback_t callback with the following val‐
3182 ues:
3183 ┌───────┬────────────────────────────┐
3185 │origin │ The original nick (may be │
3186 │ │ yours!) │
3187 ├───────┼────────────────────────────┤
3188 │params │ params[0] contains a new │
3189 │ │ nick. │
3190 └───────┴────────────────────────────┘
3191 event_quit
3193 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 This event uses irc_event_callback_t callback with the following val‐
3199 ues:
3200 ┌───────┬────────────────────────────┐
3202 │origin │ The user who disconnected │
3203 ├───────┼────────────────────────────┤
3204 │params │ params[0] is optional, │
3205 │ │ contains the user-speci‐ │
3206 │ │ fied reason to quit │
3207 └───────┴────────────────────────────┘
3208 event_join
3210 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 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 This event uses irc_event_callback_t callback with the following val‐
3221 ues:
3222 ┌───────┬────────────────────────────┐
3224 │origin │ The user who joined the │
3225 │ │ channel (this may be you!) │
3226 ├───────┼────────────────────────────┤
3227 │params │ params[0] contains the │
3228 │ │ channel name │
3229 └───────┴────────────────────────────┘
3230 event_part
3232 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 This event uses irc_event_callback_t callback with the following val‐
3238 ues:
3239 ┌───────┬────────────────────────────┐
3244 │origin │ The user who left the │
3245 │ │ channel (this may be you!) │
3246 ├───────┼────────────────────────────┤
3247 │params │ params[0] contains the │
3248 │ │ channel name params[1] is │
3249 │ │ optional and contains the │
3250 │ │ user-specified reason │
3251 └───────┴────────────────────────────┘
3252 event_mode
3254 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 This event uses irc_event_callback_t callback with the following val‐
3260 ues:
3261 ┌───────┬────────────────────────────┐
3263 │origin │ The user who performed the │
3264 │ │ change │
3265 ├───────┼────────────────────────────┤
3266 │params │ 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 event_umode
3278 This event is triggered upon receipt of a user MODE message. It happens
3280 when your user mode is changed.
3281 This event uses irc_event_callback_t callback with the following val‐
3283 ues:
3284 ┌───────┬────────────────────────────┐
3286 │origin │ The user who performed the │
3287 │ │ change │
3288 ├───────┼────────────────────────────┤
3289 │params │ params[0] contains the │
3290 │ │ channel name params[1] │
3291 │ │ contains the user mode │
3292 │ │ changes, such as "+t", │
3293 │ │ "-i" │
3294 └───────┴────────────────────────────┘
3295 event_topic
3297 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 This event uses irc_event_callback_t callback with the following val‐
3303 ues:
3304 ┌───────┬────────────────────────────┐
3306 │origin │ The user who performed the │
3307 │ │ change │
3308 ├───────┼────────────────────────────┤
3309 │params │ params[0] contains the │
3310 │ │ channel name params[1] │
3311 │ │ optional, contains the new │
3312 │ │ topic │
3313 └───────┴────────────────────────────┘
3314 event_kick
3316 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 It is possible to kick yourself from the channel.
3322 This event uses irc_event_callback_t callback with the following val‐
3324 ues:
3325 ┌───────┬────────────────────────────┐
3327 │origin │ The user who performed the │
3328 │ │ action (may be you) │
3329 ├───────┼────────────────────────────┤
3330 │params │ 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 event_channel
3340 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 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 This event uses irc_event_callback_t callback with the following val‐
3350 ues:
3351 ┌───────┬────────────────────────────┐
3353 │origin │ The user who sent a mes‐ │
3354 │ │ sage │
3355 ├───────┼────────────────────────────┤
3356 │params │ params[0] contains the │
3357 │ │ channel name params[1] │
3358 │ │ optional, contains the │
3359 │ │ message text │
3360 └───────┴────────────────────────────┘
3361 event_privmsg
3363 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 This event uses irc_event_callback_t callback with the following val‐
3368 ues:
3369 ┌───────┬────────────────────────────┐
3371 │origin │ The user who sent a mes‐ │
3372 │ │ sage │
3373 ├───────┼────────────────────────────┤
3374 │params │ params[0] contains your │
3375 │ │ nick params[1] optional, │
3376 │ │ contains the message text │
3377 └───────┴────────────────────────────┘
3378 event_notice
3380 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 This event uses irc_event_callback_t callback with the following val‐
3389 ues:
3390 ┌───────┬────────────────────────────┐
3392 │origin │ The user who sent a mes‐ │
3393 │ │ sage │
3394 └───────┴────────────────────────────┘
3395 │params │ params[0] contains the │
3400 │ │ target nick name params[1] │
3401 │ │ optional, contains the │
3402 │ │ message text │
3403 └───────┴────────────────────────────┘
3404 event_channel_notice
3406 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 This event uses irc_event_callback_t callback with the following val‐
3415 ues:
3416 ┌───────┬────────────────────────────┐
3418 │origin │ The user who sent a mes‐ │
3419 │ │ sage │
3420 ├───────┼────────────────────────────┤
3421 │params │ params[0] contains the │
3422 │ │ channel name params[1] │
3423 │ │ optional, contains the │
3424 │ │ message text │
3425 └───────┴────────────────────────────┘
3426 event_invite
3428 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 This event uses irc_event_callback_t callback with the following val‐
3433 ues:
3434 ┌───────┬────────────────────────────┐
3436 │origin │ The user who invited you │
3437 ├───────┼────────────────────────────┤
3438 │params │ params[0] contains your │
3439 │ │ nick params[1] optional, │
3440 │ │ contains the channel name │
3441 └───────┴────────────────────────────┘
3442 See also: irc_cmd_invite()
3444 event_ctcp_req
3446 This event is triggered upon receipt of an CTCP request. By default,
3448 the built-in CTCP request handler is used.
3449 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 Also you may find useful this question in FAQ: ref faq4
3460 This event uses irc_event_callback_t callback with the following val‐
3462 ues:
3463 ┌───────┬────────────────────────────┐
3465 │origin │ The user who generated the │
3466 │ │ message │
3467 ├───────┼────────────────────────────┤
3468 │params │ params[0] contains the │
3469 │ │ complete CTCP message │
3470 └───────┴────────────────────────────┘
3471 event_ctcp_rep
3473 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 This event uses irc_event_callback_t callback with the following val‐
3479 ues:
3480 ┌───────┬────────────────────────────┐
3482 │origin │ The user who generated the │
3483 │ │ message │
3484 ├───────┼────────────────────────────┤
3485 │params │ params[0] contains the │
3486 │ │ complete CTCP message │
3487 └───────┴────────────────────────────┘
3488 event_ctcp_action
3490 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 Such messages typically look like that in the IRC client:
3495 :: [08:32:55] * Michael is having fun [08:32:55] * Bobby's getting
3497 jealous
3498 This event uses irc_event_callback_t callback with the following val‐
3500 ues:
3501 ┌───────┬────────────────────────────┐
3503 │origin │ The user who generated the │
3504 │ │ message │
3505 ├───────┼────────────────────────────┤
3506 │params │ params[0] contains the │
3507 │ │ content of ACTION message │
3508 └───────┴────────────────────────────┘
3509 event_unknown
3511 This event is triggered upon receipt of an unknown message which is not
3513 handled by the library.
3514 This event uses irc_event_callback_t callback with the following val‐
3516 ues:
3517 ┌───────┬────────────────────────────┐
3519 │origin │ The user who generated the │
3520 │ │ event │
3521 ├───────┼────────────────────────────┤
3522 │params │ Zero or more parameters │
3523 │ │ provided with the event │
3524 └───────┴────────────────────────────┘
3525 event_numeric
3527 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 This event uses the dedicated
3533 irc_eventcode_callback_t_
3534 callback. See the callback documentation.
3535 event_dcc_chat_req
3537 This event is triggered when someone attempts to establish the DCC CHAT
3539 with you.
3540 This event uses the dedicated irc_event_dcc_chat_t callback. See the
3542 callback documentation.
3543 event_dcc_send_req
3545 This event is triggered when someone attempts to send you the file via
3547 DCC SEND.
3548 This event uses the dedicated irc_event_dcc_send_t callback. See the
3550 callback documentation.
3551 Constants
3553 This section describes contstants such as options and the error codes.
3554 Errors
3556 LIBIRC_ERR_OK
3557 (0): No error
3559 LIBIRC_ERR_INVAL
3561 (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 LIBIRC_ERR_RESOLV
3567 (2): The host name supplied for irc_connect() function could not be
3569 resolved into valid IP address.
3570 LIBIRC_ERR_SOCKET
3572 (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 LIBIRC_ERR_CONNECT
3578 (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 LIBIRC_ERR_CLOSED
3585 (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 LIBIRC_ERR_NOMEM
3593 (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 LIBIRC_ERR_ACCEPT
3602 (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 LIBIRC_ERR_NODCCSEND
3608 (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 LIBIRC_ERR_READ
3614 (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 LIBIRC_ERR_WRITE
3620 (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 LIBIRC_ERR_STATE
3626 (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 LIBIRC_ERR_TIMEOUT
3632 (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 LIBIRC_ERR_OPENFILE
3640 (14): The file specified in irc_dcc_sendfile() could not be opened.
3642 LIBIRC_ERR_TERMINATED
3644 (15): The connection to the IRC server was terminated.
3646 LIBIRC_ERR_NOIPV6
3648 (16): The function which requires IPv6 support was called, but the IPv6
3650 support was not compiled into the application
3651 LIBIRC_ERR_SSL_NOT_SUPPORTED
3653 (17): The SSL connection was required but the library was not compiled
3655 with SSL support
3656 LIBIRC_ERR_SSL_INIT_FAILED
3658 (18): The SSL library could not be initialized.
3660 LIBIRC_ERR_CONNECT_SSL_FAILED
3662 (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 LIBIRC_ERR_SSL_CERT_VERIFY_FAILED
3668 (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 Options
3673 LIBIRC_OPTION_DEBUG
3674 If set, enables additional debug output which goes to STDOUT.
3676 LIBIRC_OPTION_STRIPNICKS
3678 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 LIBIRC_OPTION_SSL_NO_VERIFY
3688 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 This option must be set before the irc_connect function is called.
3699
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 WSADATA wsaData;
3708 if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
3710 // report an error
3711 // Now you can use libircclient
3713 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 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 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 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 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 if ( !origin )
3782 return;
3783 if ( strcasecmp (origin, "nickserv") )
3785 return;
3786 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 The idea is to parse the messages sent from NICKSERV, and if they’re
3802 matched the specific patterns, react on them appropriately.
3803 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 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 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 If you receive the event_umode with +o this means your user is an IRC
3822 server operator.
3823 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 · Call irc_add_select_descriptors with an empty FD_SET
3831 · 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 · Pass those descriptors to poll/epoll using relevant events (i.e.
3837 use the EPOLLIN for the descriptors in the in_set)
3838 · 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 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 GNU LESSER GENERAL PUBLIC LICENSE
3848 Version 3, 29 June 2007
3849 Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>
3851 Everyone is permitted to copy and distribute verbatim copies of this
3853 license document, but changing it is not allowed.
3854 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 0. Additional Definitions.
3860 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 “The Library” refers to a covered work governed by this License, other
3866 than an Application or a Combined Work as defined below.
3867 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 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 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 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 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 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 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 b. under the GNU GPL, with none of the additional permissions of
3904 this License applicable to that copy.
3905 3. Object Code Incorporating Material from Library Header Files.
3907 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 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 b. Accompany the object code with a copy of the GNU GPL and this
3920 license document.
3921 4. Combined Works.
3923 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 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 b. Accompany the Combined Work with a copy of the GNU GPL and this
3934 license document.
3935 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 d.
3942 Do one of the following:
3944 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 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 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 5. Combined Libraries.
3974 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 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 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 6. Revised Versions of the GNU Lesser General Public License.
3990 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 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 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 Indices and tables
4012 · genindex
4013 · modindex
4015 · search
4017
4019 George Yunaev
4020
4022 2013, George Yunaev
40231.7 May 09, 2014 LIBIRCCLIENT(1)