Mercurial > irccd
comparison extern/libircclient/include/libircclient.h @ 0:1158cffe5a5e
Initial import
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 08 Feb 2016 16:43:14 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:1158cffe5a5e |
---|---|
1 /* | |
2 * Copyright (C) 2004-2012 George Yunaev gyunaev@ulduzsoft.com | |
3 * | |
4 * This library is free software; you can redistribute it and/or modify it | |
5 * under the terms of the GNU Lesser General Public License as published by | |
6 * the Free Software Foundation; either version 3 of the License, or (at your | |
7 * option) any later version. | |
8 * | |
9 * This library is distributed in the hope that it will be useful, but WITHOUT | |
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public | |
12 * License for more details. | |
13 */ | |
14 | |
15 /*! | |
16 * \file libircclient.h | |
17 * \author George Yunaev | |
18 * \version 1.5 | |
19 * \date 01.2012 | |
20 * \brief This file defines all prototypes and functions to use libircclient. | |
21 * | |
22 * libircclient is a small but powerful library, which implements client-server IRC | |
23 * protocol. It is designed to be small, fast, portable and compatible to RFC | |
24 * standards, and most IRC clients. libircclient features include: | |
25 * - Full multi-threading support. | |
26 * - Single threads handles all the IRC processing. | |
27 * - Support for single-threaded applications, and socket-based applications, | |
28 * which use select() | |
29 * - Synchronous and asynchronous interfaces. | |
30 * - CTCP support with optional build-in reply code. | |
31 * - Flexible DCC support, including both DCC chat, and DCC file transfer. | |
32 * - Can both initiate and react to initiated DCC. | |
33 * - Can accept or decline DCC sessions asynchronously. | |
34 * - Plain C interface and implementation (possible to use from C++ code, | |
35 * obviously) | |
36 * - Compatible with RFC 1459 and most IRC clients. | |
37 * - SSL support if compiled with --enable-openssl. | |
38 * - Free, licensed under LGPL license. | |
39 * | |
40 * Note that to use libircclient, only libircclient.h should be included into your | |
41 * program. Do not include other libirc_* headers. | |
42 */ | |
43 | |
44 #ifndef INCLUDE_LIBIRC_H | |
45 #define INCLUDE_LIBIRC_H | |
46 | |
47 #include <stdlib.h> | |
48 | |
49 #if !defined (_WIN32) | |
50 #include <sys/select.h> /* fd_set */ | |
51 #else | |
52 #include <winsock2.h> | |
53 #include <ws2tcpip.h> | |
54 #if defined (ENABLE_IPV6) | |
55 typedef int (WSAAPI * getaddrinfo_ptr_t) (const char *, const char* , const struct addrinfo *, struct addrinfo **); | |
56 typedef void (WSAAPI * freeaddrinfo_ptr_t) (struct addrinfo*); | |
57 #endif | |
58 #endif | |
59 | |
60 #ifdef __cplusplus | |
61 extern "C" { | |
62 #endif | |
63 | |
64 /*! \brief A libircclient IRC session. | |
65 * | |
66 * This structure describes an IRC session. Its members are internal to | |
67 * libircclient, and should not be used directly. | |
68 */ | |
69 typedef struct irc_session_s irc_session_t; | |
70 | |
71 /*! \brief A libircclient DCC session. | |
72 * | |
73 * This structure describes a DCC session used by libircclient. | |
74 * Its members are internal to libircclient, and should not be used directly. | |
75 */ | |
76 typedef struct irc_dcc_session_s irc_dcc_session_t; | |
77 | |
78 | |
79 /*! \brief A DCC session identifier. | |
80 * | |
81 * The irc_dcc_t type is a DCC session identifier, used to identify the | |
82 * DCC sessions in callbacks and various functions. | |
83 */ | |
84 typedef unsigned int irc_dcc_t; | |
85 | |
86 | |
87 /*! | |
88 * \fn typedef void (*irc_dcc_callback_t) (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length) | |
89 * \brief A common DCC callback, used to inform you about the current DCC state or event. | |
90 * | |
91 * \param session An IRC session which generates the callback | |
92 * \param id A DCC session id. | |
93 * \param status An error status. 0 means no error, otherwise error code. | |
94 * \param ctx A user-supplied context. | |
95 * \param data Data supplied (if available) | |
96 * \param length data length (if available) | |
97 * | |
98 * This callback is called for all DCC functions when state change occurs. | |
99 * | |
100 * For DCC CHAT, the callback is called in next circumstances: | |
101 * - \a status is LIBIRC_ERR_CLOSED: connection is closed by remote peer. | |
102 * After returning from the callback, the DCC session is automatically | |
103 * destroyed. | |
104 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error | |
105 * (connect error, accept error, recv error, send error). After returning | |
106 * from the callback, the DCC session is automatically destroyed. | |
107 * - \a status is 0: new chat message received, \a data contains the message | |
108 * (null-terminated string), \a length contains the message length. | |
109 * | |
110 * For DCC SEND, while file is sending, callback called in next circumstances: | |
111 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error | |
112 * (connect error, accept error, recv error, send error). After returning | |
113 * from the callback, the DCC session is automatically destroyed. | |
114 * - \a status is 0: new data received, \a data contains the data received, | |
115 * \a length contains the amount of data received. | |
116 * | |
117 * For DCC RECV, while file is sending, callback called in next circumstances: | |
118 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error | |
119 * (connect error, accept error, recv error, send error). After returning | |
120 * from the callback, the DCC session is automatically destroyed. | |
121 * - \a status is 0, and \a data is 0: file has been received successfully. | |
122 * After returning from the callback, the DCC session is automatically | |
123 * destroyed. | |
124 * - \a status is 0, and \a data is not 0: new data received, \a data contains | |
125 * the data received, \a length contains the amount of data received. | |
126 * | |
127 * \ingroup dccstuff | |
128 */ | |
129 typedef void (*irc_dcc_callback_t) (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length); | |
130 | |
131 | |
132 #define IN_INCLUDE_LIBIRC_H | |
133 #include "libirc_errors.h" | |
134 #include "libirc_events.h" | |
135 #include "libirc_options.h" | |
136 #undef IN_INCLUDE_LIBIRC_H | |
137 | |
138 | |
139 /*! | |
140 * \fn irc_session_t * irc_create_session (irc_callbacks_t * callbacks) | |
141 * \brief Creates and initiates a new IRC session. | |
142 * | |
143 * \param callbacks A structure, which defines several callbacks, which will | |
144 * be called on appropriate events. Must not be NULL. | |
145 * | |
146 * \return An ::irc_session_t object, or 0 if creation failed. Usually, | |
147 * failure is caused by out of memory error. | |
148 * | |
149 * Every ::irc_session_t object describes a single IRC session - a connection | |
150 * to an IRC server, and possibly to some DCC clients. Almost every irc_* | |
151 * function requires this object to be passed to, and therefore this function | |
152 * should be called first. | |
153 * | |
154 * Every session created must be destroyed when it is not needed anymore | |
155 * by calling irc_destroy_session(). | |
156 * | |
157 * The most common function sequence is: | |
158 * \code | |
159 * ... prepare irc_callbacks_t structure ... | |
160 * irc_create_session(); | |
161 * irc_connect(); | |
162 * irc_run(); | |
163 * irc_destroy_session(); | |
164 * \endcode | |
165 * | |
166 * \sa irc_destroy_session | |
167 * \ingroup initclose | |
168 */ | |
169 irc_session_t * irc_create_session (irc_callbacks_t * callbacks); | |
170 | |
171 | |
172 /*! | |
173 * \fn void irc_destroy_session (irc_session_t * session) | |
174 * \brief Destroys previously created IRC session. | |
175 * | |
176 * \param session A session to destroy. Must not be NULL. | |
177 * | |
178 * This function should be used to destroy an IRC session, close the | |
179 * connection to the IRC server, and free all the used resources. After | |
180 * calling this function, you should not use this session object anymore. | |
181 * | |
182 * \ingroup initclose | |
183 */ | |
184 void irc_destroy_session (irc_session_t * session); | |
185 | |
186 | |
187 /*! | |
188 * \fn int irc_connect (irc_session_t * session, const char * server, unsigned short port, const char * server_password, const char * nick, const char * username, const char * realname); | |
189 * \brief Initiates a connection to IRC server. | |
190 * | |
191 * \param session A session to initiate connections on. Must not be NULL. | |
192 * \param server A domain name or an IP address of the IRC server to connect to. Cannot be NULL. | |
193 * If the library is built with SSL support and the first character is hash, tries to establish the SSL connection. | |
194 * For example, the connection to "irc.example.com" is assumed to be plaintext, and connection to "#irc.example.com" | |
195 * is assumed to be secured by SSL. Note that SSL will only work if the library is built with the SSL support. | |
196 * \param port An IRC server port, usually 6667. | |
197 * \param server_password An IRC server password, if the server requires it. | |
198 * May be NULL, in this case password will not be send to the | |
199 * IRC server. Vast majority of IRC servers do not require passwords. | |
200 * \param nick A nick, which libircclient will use to login to the IRC server. | |
201 * Must not be NULL. | |
202 * \param username A username of the account, which is used to connect to the | |
203 * IRC server. This is for information only, will be shown in | |
204 * "user properties" dialogs and returned by /whois request. | |
205 * May be NULL, in this case 'nobody' will be sent as username. | |
206 * \param realname A real name of the person, who connects to the IRC. Usually | |
207 * people put some wide-available information here (URL, small | |
208 * description or something else). This information also will | |
209 * be shown in "user properties" dialogs and returned by /whois | |
210 * request. May be NULL, in this case 'noname' will be sent as | |
211 * username. | |
212 * | |
213 * \return Return code 0 means success. Other value means error, the error | |
214 * code may be obtained through irc_errno(). Any error, generated by the | |
215 * IRC server, is available through irc_callbacks_t::event_numeric. | |
216 * | |
217 * This function prepares and initiates a connection to the IRC server. The | |
218 * connection is done asynchronously (see irc_callbacks_t::event_connect), so the success | |
219 * return value means that connection was initiated (but not completed!) | |
220 * successfully. | |
221 * | |
222 * \sa irc_run | |
223 * \ingroup conndisc | |
224 */ | |
225 int irc_connect (irc_session_t * session, | |
226 const char * server, | |
227 unsigned short port, | |
228 const char * server_password, | |
229 const char * nick, | |
230 const char * username, | |
231 const char * realname); | |
232 | |
233 | |
234 /*! | |
235 * \fn int irc_connect6 (irc_session_t * session, const char * server, unsigned short port, const char * server_password, const char * nick, const char * username, const char * realname); | |
236 * \brief Initiates a connection to IRC server using IPv6. | |
237 * | |
238 * \param session A session to initiate connections on. Must not be NULL. | |
239 * \param server A domain name or an IP address of the IRC server to connect to. Cannot be NULL. | |
240 * If the library is built with SSL support and the first character is hash, tries to establish the SSL connection. | |
241 * For example, the connection to "irc.example.com" is assumed to be plaintext, and connection to "#irc.example.com" | |
242 * is assumed to be secured by SSL. Note that SSL will only work if the library is built with the SSL support. | |
243 * \param port An IRC server port, usually 6667. | |
244 * \param server_password An IRC server password, if the server requires it. | |
245 * May be NULL, in this case password will not be send to the | |
246 * IRC server. Vast majority of IRC servers do not require passwords. | |
247 * \param nick A nick, which libircclient will use to login to the IRC server. | |
248 * Must not be NULL. | |
249 * \param username A username of the account, which is used to connect to the | |
250 * IRC server. This is for information only, will be shown in | |
251 * "user properties" dialogs and returned by /whois request. | |
252 * May be NULL, in this case 'nobody' will be sent as username. | |
253 * \param realname A real name of the person, who connects to the IRC. Usually | |
254 * people put some wide-available information here (URL, small | |
255 * description or something else). This information also will | |
256 * be shown in "user properties" dialogs and returned by /whois | |
257 * request. May be NULL, in this case 'noname' will be sent as | |
258 * username. | |
259 * | |
260 * \return Return code 0 means success. Other value means error, the error | |
261 * code may be obtained through irc_errno(). Any error, generated by the | |
262 * IRC server, is available through irc_callbacks_t::event_numeric. | |
263 * | |
264 * This function prepares and initiates a connection to the IRC server. The | |
265 * connection is done asynchronously (see irc_callbacks_t::event_connect), so the success | |
266 * return value means that connection was initiated (but not completed!) | |
267 * successfully. | |
268 * | |
269 * \sa irc_run | |
270 * \ingroup conndisc | |
271 */ | |
272 int irc_connect6 (irc_session_t * session, | |
273 const char * server, | |
274 unsigned short port, | |
275 const char * server_password, | |
276 const char * nick, | |
277 const char * username, | |
278 const char * realname); | |
279 | |
280 /*! | |
281 * \fn void irc_disconnect (irc_session_t * session) | |
282 * \brief Disconnects a connection to IRC server. | |
283 * | |
284 * \param session An IRC session. | |
285 * | |
286 * \return Return code 0 means success. Other value means error, the error | |
287 * code may be obtained through irc_errno(). | |
288 * | |
289 * This function closes the IRC connection. After that connection is closed, | |
290 * libircclient automatically leaves irc_run loop. | |
291 * | |
292 * \sa irc_connect irc_run | |
293 * \ingroup conndisc | |
294 */ | |
295 void irc_disconnect (irc_session_t * session); | |
296 | |
297 | |
298 /*! | |
299 * \fn int irc_is_connected (irc_session_t * session) | |
300 * \brief Checks whether the session is connecting/connected to the IRC server. | |
301 * | |
302 * \param session An initialized IRC session. | |
303 * | |
304 * \return Return code 1 means that session is connecting or connected to the | |
305 * IRC server, zero value means that the session has been disconnected. | |
306 * | |
307 * \sa irc_connect irc_run | |
308 * \ingroup conndisc | |
309 */ | |
310 int irc_is_connected (irc_session_t * session); | |
311 | |
312 | |
313 /*! | |
314 * \fn int irc_run (irc_session_t * session) | |
315 * \brief Goes into forever-loop, processing IRC events and generating | |
316 * callbacks. | |
317 * | |
318 * \param session An initiated and connected session. | |
319 * | |
320 * \return Return code 0 means success. Other value means error, the error | |
321 * code may be obtained through irc_errno(). | |
322 * | |
323 * This function goes into forever loop, processing the IRC events, and | |
324 * calling appropriate callbacks. This function will not return until the | |
325 * server connection is terminated - either by server, or by calling | |
326 * irc_cmd_quit. This function should be used, if you don't need asynchronous | |
327 * request processing (i.e. your bot just reacts on the events, and doesn't | |
328 * generate it asynchronously). Even in last case, you still can call irc_run, | |
329 * and start the asynchronous thread in event_connect handler. See examples. | |
330 * | |
331 * \ingroup running | |
332 */ | |
333 int irc_run (irc_session_t * session); | |
334 | |
335 | |
336 /*! | |
337 * \fn int irc_add_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set, int * maxfd) | |
338 * \brief Adds IRC socket(s) for the descriptor set to use in select(). | |
339 * | |
340 * \param session An initiated and connected session. | |
341 * \param in_set A FD_IN descriptor set for select() | |
342 * \param out_set A FD_OUT descriptor set for select() | |
343 * \param maxfd A max descriptor found. | |
344 * | |
345 * \return Return code 0 means success. Other value means error, the error | |
346 * code may be obtained through irc_errno(). | |
347 * | |
348 * This function should be used when you already have a program with select() | |
349 * based data processing. You prepare your descriptors, call this function | |
350 * to add session's descriptor(s) into set, and then call select(). When it | |
351 * returns, you should call irc_add_select_descriptors, which sends/recvs all | |
352 * available data, parses received data, calls your callbacks(!), and returns. | |
353 * Then you can process your sockets from set. See the example. | |
354 * | |
355 * \sa irc_process_select_descriptors | |
356 * \ingroup running | |
357 */ | |
358 int irc_add_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set, int * maxfd); | |
359 | |
360 | |
361 /*! | |
362 * \fn int irc_process_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set) | |
363 * \brief Processes the IRC socket(s), which descriptor(s) are set. | |
364 * | |
365 * \param session An initiated and connected session. | |
366 * \param in_set A FD_IN descriptor set for select() | |
367 * \param out_set A FD_OUT descriptor set for select() | |
368 * | |
369 * \return Return code 0 means success. Other value means error, the error | |
370 * code may be obtained through irc_errno(). | |
371 * | |
372 * This function should be used in pair with irc_add_select_descriptors | |
373 * function. See irc_add_select_descriptors description. | |
374 * | |
375 * \sa irc_add_select_descriptors | |
376 * \ingroup running | |
377 */ | |
378 int irc_process_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set); | |
379 | |
380 | |
381 /*! | |
382 * \fn int irc_send_raw (irc_session_t * session, const char * format, ...) | |
383 * \brief Sends raw data to the IRC server. | |
384 * | |
385 * \param session An initiated and connected session. | |
386 * \param format A printf-formatted string, followed by function args. | |
387 * | |
388 * \return Return code 0 means success. Other value means error, the error | |
389 * code may be obtained through irc_errno(). Any error, generated by the | |
390 * IRC server, is available through irc_callbacks_t::event_numeric. | |
391 * | |
392 * This function sends the raw data as-is to the IRC server. Use it to | |
393 * generate a server command, which is not (yet) provided by libircclient | |
394 * directly. | |
395 * | |
396 * \ingroup ircmd_oth | |
397 */ | |
398 int irc_send_raw (irc_session_t * session, const char * format, ...); | |
399 | |
400 | |
401 /*! | |
402 * \fn int irc_cmd_quit (irc_session_t * session, const char * reason) | |
403 * \brief Sends QUIT command to the IRC server. | |
404 * | |
405 * \param session An initiated and connected session. | |
406 * \param reason A reason to quit. May be NULL. | |
407 * | |
408 * \return Return code 0 means success. Other value means error, the error | |
409 * code may be obtained through irc_errno(). Any error, generated by the | |
410 * IRC server, is available through irc_callbacks_t::event_numeric. | |
411 * | |
412 * This function sends the QUIT command to the IRC server. This command | |
413 * forces the IRC server to close the IRC connection, and terminate the | |
414 * session. | |
415 * | |
416 * \ingroup ircmd_oth | |
417 */ | |
418 int irc_cmd_quit (irc_session_t * session, const char * reason); | |
419 | |
420 | |
421 /*! | |
422 * \fn int irc_cmd_join (irc_session_t * session, const char * channel, const char * key) | |
423 * \brief Joins the new IRC channel. | |
424 * | |
425 * \param session An initiated and connected session. | |
426 * \param channel A channel name to join to. Must not be NULL. | |
427 * \param key Channel password. May be NULL. | |
428 * | |
429 * \return Return code 0 means success. Other value means error, the error | |
430 * code may be obtained through irc_errno(). Any error, generated by the | |
431 * IRC server, is available through irc_callbacks_t::event_numeric. | |
432 * | |
433 * This function is used to JOIN the IRC channel. If the channel is not exist, | |
434 * it will be automatically created by the IRC server. Note that to JOIN the | |
435 * password-protected channel, you must know the password, and specify it in | |
436 * the \a key argument. | |
437 * | |
438 * If join is successful, the irc_callbacks_t::event_join is called (with \a origin == | |
439 * your nickname), then you are sent the channel's topic | |
440 * (using ::LIBIRC_RFC_RPL_TOPIC) and the list of users who are on the | |
441 * channel (using ::LIBIRC_RFC_RPL_NAMREPLY), which includes the user | |
442 * joining - namely you. | |
443 * | |
444 * Possible error responces for this command from the RFC1459: | |
445 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
446 * - ::LIBIRC_RFC_ERR_BANNEDFROMCHAN | |
447 * - ::LIBIRC_RFC_ERR_INVITEONLYCHAN | |
448 * - ::LIBIRC_RFC_ERR_BADCHANNELKEY | |
449 * - ::LIBIRC_RFC_ERR_CHANNELISFULL | |
450 * - ::LIBIRC_RFC_ERR_BADCHANMASK | |
451 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL | |
452 * - ::LIBIRC_RFC_ERR_TOOMANYCHANNELS | |
453 * | |
454 * And on success the following replies returned: | |
455 * - ::LIBIRC_RFC_RPL_TOPIC | |
456 * - ::LIBIRC_RFC_RPL_NAMREPLY | |
457 * | |
458 * \ingroup ircmd_ch | |
459 */ | |
460 int irc_cmd_join (irc_session_t * session, const char * channel, const char * key); | |
461 | |
462 | |
463 /*! | |
464 * \fn int irc_cmd_part (irc_session_t * session, const char * channel) | |
465 * \brief Leaves the IRC channel. | |
466 * | |
467 * \param session An initiated and connected session. | |
468 * \param channel A channel name to leave. Must not be NULL. | |
469 * | |
470 * \return Return code 0 means success. Other value means error, the error | |
471 * code may be obtained through irc_errno(). Any error, generated by the | |
472 * IRC server, is available through irc_callbacks_t::event_numeric. | |
473 * | |
474 * This function is used to leave the IRC channel you've already joined to. | |
475 * An attempt to leave the channel you aren't in results a ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
476 * server error. | |
477 * | |
478 * Possible error responces for this command from the RFC1459: | |
479 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
480 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL | |
481 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
482 * | |
483 * \ingroup ircmd_ch | |
484 */ | |
485 int irc_cmd_part (irc_session_t * session, const char * channel); | |
486 | |
487 | |
488 /*! | |
489 * \fn int irc_cmd_invite (irc_session_t * session, const char * nick, const char * channel) | |
490 * \brief Invites a user to invite-only channel. | |
491 * | |
492 * \param session An initiated and connected session. | |
493 * \param nick A nick to invite. Must not be NULL. | |
494 * \param channel A channel name to invite to. Must not be NULL. | |
495 * | |
496 * \return Return code 0 means success. Other value means error, the error | |
497 * code may be obtained through irc_errno(). Any error, generated by the | |
498 * IRC server, is available through irc_callbacks_t::event_numeric. | |
499 * | |
500 * This function is used to invite someone to invite-only channel. | |
501 * "Invite-only" is a channel mode, which restricts anyone, except invided, | |
502 * to join this channel. After invitation, the user could join this channel. | |
503 * The user, who is invited, will receive the irc_callbacks_t::event_invite event. | |
504 * Note that you must be a channel operator to INVITE the users. | |
505 * | |
506 * Possible error responces for this command from the RFC1459: | |
507 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
508 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
509 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
510 * - ::LIBIRC_RFC_ERR_ERR_USERONCHANNEL | |
511 * - ::LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED | |
512 * | |
513 * And on success one of the following replies returned: | |
514 * - ::LIBIRC_RFC_RPL_INVITING | |
515 * - ::LIBIRC_RFC_RPL_AWAY | |
516 * | |
517 * \sa irc_callbacks_t::event_invite irc_cmd_channel_mode | |
518 * \ingroup ircmd_ch | |
519 */ | |
520 int irc_cmd_invite (irc_session_t * session, const char * nick, const char * channel); | |
521 | |
522 | |
523 /*! | |
524 * \fn int irc_cmd_names (irc_session_t * session, const char * channel) | |
525 * \brief Obtains a list of users who're in channel. | |
526 * | |
527 * \param session An initiated and connected session. | |
528 * \param channel A channel name(s) to obtain user list. Must not be NULL. | |
529 * It is possible to specify more than a single channel, but | |
530 * several channel names should be separated by a comma. | |
531 * | |
532 * \return Return code 0 means success. Other value means error, the error | |
533 * code may be obtained through irc_errno(). Any error, generated by the | |
534 * IRC server, is available through irc_callbacks_t::event_numeric. | |
535 * | |
536 * This function is used to ask the IRC server for the list of the users | |
537 * who're in specified channel. You can list all nicknames that are visible | |
538 * to you on any channel that you can see. The list of users will be returned | |
539 * using ::RPL_NAMREPLY and ::RPL_ENDOFNAMES numeric codes. | |
540 * | |
541 * The channel names are returned by irc_callbacks_t::event_numeric | |
542 * using the following reply codes: | |
543 * - ::LIBIRC_RFC_RPL_NAMREPLY | |
544 * - ::LIBIRC_RFC_RPL_ENDOFNAMES | |
545 * | |
546 * \ingroup ircmd_ch | |
547 */ | |
548 int irc_cmd_names (irc_session_t * session, const char * channel); | |
549 | |
550 | |
551 /*! | |
552 * \fn int irc_cmd_list (irc_session_t * session, const char * channel) | |
553 * \brief Obtains a list of active server channels with their topics. | |
554 * | |
555 * \param session An initiated and connected session. | |
556 * \param channel A channel name(s) to list. May be NULL, in which case all the | |
557 * channels will be listed. It is possible to specify more than | |
558 * a single channel, but several channel names should be | |
559 * separated by a comma. | |
560 * | |
561 * \return Return code 0 means success. Other value means error, the error | |
562 * code may be obtained through irc_errno(). Any error, generated by the | |
563 * IRC server, is available through irc_callbacks_t::event_numeric. | |
564 * | |
565 * This function is used to ask the IRC server for the active (existing) | |
566 * channels list. The list will be returned using ::LIBIRC_RFC_RPL_LISTSTART - | |
567 * ::LIBIRC_RFC_RPL_LIST - ::LIBIRC_RFC_RPL_LISTEND sequence. | |
568 * Note that "private" channels are listed (without their topics) as channel | |
569 * "Prv" unless the client generating the LIST query is actually on that | |
570 * channel. Likewise, secret channels are | |
571 * not listed at all unless the client is a member of the channel in question. | |
572 * | |
573 * Possible error responces for this command from the RFC1459: | |
574 * - ::LIBIRC_RFC_ERR_NOSUCHSERVER | |
575 * | |
576 * And the channel list is returned using the following reply codes: | |
577 * - ::LIBIRC_RFC_RPL_LISTSTART | |
578 * - ::LIBIRC_RFC_RPL_LISTEND | |
579 * - ::LIBIRC_RFC_RPL_LIST | |
580 * | |
581 * \ingroup ircmd_ch | |
582 */ | |
583 int irc_cmd_list (irc_session_t * session, const char * channel); | |
584 | |
585 | |
586 /*! | |
587 * \fn int irc_cmd_topic (irc_session_t * session, const char * channel, const char * topic) | |
588 * \brief Views or changes the channel topic. | |
589 * | |
590 * \param session An initiated and connected session. | |
591 * \param channel A channel name to invite to. Must not be NULL. | |
592 * \param topic A new topic to change. If NULL, the old topic will be | |
593 * returned, and topic won't changed. | |
594 * | |
595 * \return Return code 0 means success. Other value means error, the error | |
596 * code may be obtained through irc_errno(). Any error, generated by the | |
597 * IRC server, is available through irc_callbacks_t::event_numeric. | |
598 * | |
599 * The irc_cmd_topic() is used to change or view the topic of a channel. | |
600 * The topic for \a channel is returned if \a topic is NULL. If the \a topic | |
601 * is not NULL, the topic for the \a channel will be changed. Note that, | |
602 * depending on \a +t channel mode, you may be required to be a channel | |
603 * operator to change the channel topic. | |
604 * | |
605 * If the command succeed, the IRC server will generate a ::RPL_NOTOPIC or | |
606 * ::RPL_TOPIC message, containing either old or changed topic. Also the IRC | |
607 * server can (but not have to) generate the non-RFC ::RPL_TOPIC_EXTRA message, | |
608 * containing the nick of person, who's changed the topic, and the time of | |
609 * latest topic change. | |
610 * | |
611 * Possible error responces for this command from the RFC1459: | |
612 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
613 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED | |
614 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
615 * | |
616 * And the topic information is returned using one of following reply codes: | |
617 * - ::LIBIRC_RFC_RPL_NOTOPIC | |
618 * - ::LIBIRC_RFC_RPL_TOPIC | |
619 * | |
620 * \sa irc_callbacks_t::event_topic irc_cmd_channel_mode | |
621 * \ingroup ircmd_ch | |
622 */ | |
623 int irc_cmd_topic (irc_session_t * session, const char * channel, const char * topic); | |
624 | |
625 | |
626 /*! | |
627 * \fn int irc_cmd_channel_mode (irc_session_t * session, const char * channel, const char * mode) | |
628 * \brief Views or changes the channel mode. | |
629 * | |
630 * \param session An initiated and connected session. | |
631 * \param channel A channel name to invite to. Must not be NULL. | |
632 * \param mode A channel mode, described below. If NULL, the channel mode is | |
633 * not changed, just the old mode is returned. | |
634 * | |
635 * \return Return code 0 means success. Other value means error, the error | |
636 * code may be obtained through irc_errno(). Any error, generated by the | |
637 * IRC server, is available through irc_callbacks_t::event_numeric. | |
638 * | |
639 * The irc_cmd_channel_mode() is used to change or view the channel modes. | |
640 * The \a channel mode is returned if the \a mode is NULL. If the \a mode | |
641 * is not NULL, the mode for the \a channel will be changed. Note that, | |
642 * only channel operators can change the channel modes. | |
643 * | |
644 * Channel mode is represended by the letters combination. Every letter has | |
645 * its own meaning in channel modes. Most channel mode letters are boolean | |
646 * (i.e. could only be set or reset), but a few channel mode letters accept a | |
647 * parameter. All channel options are set by adding a plus sign before the | |
648 * letter, and reset by adding a minus sign before the letter. | |
649 * | |
650 * Here is the list of 'standard' channel modes: | |
651 * | |
652 * - \a o \a nickname - gives (+o nick) or takes (-o nick) the channel | |
653 * operator privileges from a \a nickname. This mode affects the | |
654 * users in channel, not the channel itself. | |
655 * Examples: "+o tim", "-o watson". | |
656 * | |
657 * - \a p - sets (+p) or resets (-p) private channel flag. | |
658 * Private channels are shown in channel list as 'Prv', without the topic. | |
659 * | |
660 * - \a s - sets (+p) or resets (-p) secret channel flag. | |
661 * Secret channels aren't shown in channel list at all. | |
662 * | |
663 * - \a i - sets (+i) or resets (-i) invite-only channel flag. When the flag | |
664 * is set, only the people who are invited by irc_cmd_invite(), can | |
665 * join this channel. | |
666 * | |
667 * - \a t - sets (+t) or resets (-t) topic settable by channel operator only | |
668 * flag. When the flag is set, only the channel operators can change the | |
669 * channel topic. | |
670 * | |
671 * - \a n - sets (+n) or resets (-n) the protection from the clients outside | |
672 * the channel. When the \a +n mode is set, only the clients, who are in | |
673 * channel, can send the messages to the channel. | |
674 * | |
675 * - \a m - sets (+m) or resets (-m) the moderation of the channel. When the | |
676 * moderation mode is set, only channel operators and the users who have | |
677 * the \a +v user mode can speak in the channel. | |
678 * | |
679 * - \a v \a nickname - gives (+v nick) or takes (-v nick) from user the | |
680 * ability to speak on a moderated channel. | |
681 * Examples: "+v tim", "-v watson". | |
682 * | |
683 * - \a l \a number - sets (+l 20) or removes (-l) the restriction of maximum | |
684 * users in channel. When the restriction is set, and there is a number | |
685 * of users in the channel, no one can join the channel anymore. | |
686 * | |
687 * - \a k \a key - sets (+k secret) or removes (-k) the password from the | |
688 * channel. When the restriction is set, any user joining the channel | |
689 * required to provide a channel key. | |
690 * | |
691 * - \a b \a mask - sets (+b *!*@*.mil) or removes (-b *!*@*.mil) the ban mask | |
692 * on a user to keep him out of channel. Note that to remove the ban you | |
693 * must specify the ban mask to remove, not just "-b". | |
694 * | |
695 * Note that the actual list of channel modes depends on the IRC server, and | |
696 * can be bigger. If you know the popular channel modes, which aren't | |
697 * mentioned here - please contact me at tim@krasnogorsk.ru | |
698 * | |
699 * Possible error responces for this command from the RFC1459: | |
700 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
701 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED | |
702 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
703 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
704 * - ::LIBIRC_RFC_ERR_KEYSET | |
705 * - ::LIBIRC_RFC_ERR_UNKNOWNMODE | |
706 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL | |
707 * | |
708 * And the mode information is given using following reply codes: | |
709 * - ::LIBIRC_RFC_RPL_CHANNELMODEIS | |
710 * - ::LIBIRC_RFC_RPL_BANLIST | |
711 * - ::LIBIRC_RFC_RPL_ENDOFBANLIST | |
712 * | |
713 * \sa irc_cmd_topic irc_cmd_list | |
714 * \ingroup ircmd_ch | |
715 */ | |
716 int irc_cmd_channel_mode (irc_session_t * session, const char * channel, const char * mode); | |
717 | |
718 | |
719 /*! | |
720 * \fn int irc_cmd_user_mode (irc_session_t * session, const char * mode) | |
721 * \brief Views or changes your own user mode. | |
722 * | |
723 * \param session An initiated and connected session. | |
724 * \param mode A user mode, described below. If NULL, the user mode is | |
725 * not changed, just the old mode is returned. | |
726 * | |
727 * \return Return code 0 means success. Other value means error, the error | |
728 * code may be obtained through irc_errno(). Any error, generated by the | |
729 * IRC server, is available through irc_callbacks_t::event_numeric. | |
730 * | |
731 * The irc_cmd_user_mode() is used to change or view the user modes. | |
732 * Note that, unlike channel modes, not all user modes can be changed. | |
733 * The user mode is returned if the \a mode is NULL. If the \a mode | |
734 * is not NULL, the mode for you will be changed, and new mode will be | |
735 * returned. | |
736 * | |
737 * Like channel mode, user mode is also represended by the letters combination. | |
738 * All the user mode letters are boolean (i.e. could only be set or reset), | |
739 * they are set by adding a plus sign before the letter, and reset by adding | |
740 * a minus sign before the letter. | |
741 * | |
742 * Here is the list of 'standard' user modes: | |
743 * | |
744 * - \a o - represents an IRC operator status. Could not be set directly (but | |
745 * can be reset though), to set it use the IRC \a OPER command. | |
746 * | |
747 * - \a i - if set, marks a user as 'invisible' - that is, not seen by lookups | |
748 * if the user is not in a channel. | |
749 * | |
750 * - \a w - if set, marks a user as 'receiving wallops' - special messages | |
751 * generated by IRC operators using WALLOPS command. | |
752 * | |
753 * - \a s - if set, marks a user for receipt of server notices. | |
754 * | |
755 * - \a r - NON-STANDARD MODE. If set, user has been authenticated with | |
756 * NICKSERV IRC service. | |
757 * | |
758 * - \a x - NON-STANDARD MODE. If set, user's real IP is hidden by IRC | |
759 * servers, to prevent scriptkiddies to do nasty things to the user's | |
760 * computer. | |
761 * | |
762 * Note that the actual list of user modes depends on the IRC server, and | |
763 * can be bigger. If you know the popular user modes, which aren't | |
764 * mentioned here - please contact me at tim@krasnogorsk.ru | |
765 * | |
766 * Possible error responces for this command from the RFC1459: | |
767 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
768 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
769 * - ::LIBIRC_RFC_ERR_UNKNOWNMODE | |
770 * - ::LIBIRC_RFC_ERR_USERSDONTMATCH | |
771 * - ::LIBIRC_RFC_ERR_UMODEUNKNOWNFLAG | |
772 * | |
773 * And the mode information is given using reply code ::LIBIRC_RFC_RPL_UMODEIS | |
774 * | |
775 * \ingroup ircmd_oth | |
776 */ | |
777 int irc_cmd_user_mode (irc_session_t * session, const char * mode); | |
778 | |
779 | |
780 /*! | |
781 * \fn int irc_cmd_nick (irc_session_t * session, const char * newnick) | |
782 * \brief Changes your nick. | |
783 * | |
784 * \param session An initiated and connected session. | |
785 * \param newnick A new nick. Must not be NULL. | |
786 * | |
787 * \return Return code 0 means success. Other value means error, the error | |
788 * code may be obtained through irc_errno(). Any error, generated by the | |
789 * IRC server, is available through irc_callbacks_t::event_numeric. | |
790 * | |
791 * This function is used to change your current nick to another nick. Note | |
792 * that such a change is not always possible; for example you cannot change | |
793 * nick to the existing nick, or (on some servers) to the registered nick. | |
794 * | |
795 * Possible error responces for this command from the RFC1459: | |
796 * - ::LIBIRC_RFC_ERR_NONICKNAMEGIVEN | |
797 * - ::LIBIRC_RFC_ERR_ERRONEUSNICKNAME | |
798 * - ::LIBIRC_RFC_ERR_NICKNAMEINUSE | |
799 * - ::LIBIRC_RFC_ERR_NICKCOLLISION | |
800 * | |
801 * \ingroup ircmd_oth | |
802 */ | |
803 int irc_cmd_nick (irc_session_t * session, const char * newnick); | |
804 | |
805 | |
806 /*! | |
807 * \fn int irc_cmd_whois (irc_session_t * session, const char * nick) | |
808 * \brief Queries the information about the nick. | |
809 * | |
810 * \param session An initiated and connected session. | |
811 * \param nick A nick to query the information abour. Must not be NULL. | |
812 * A comma-separated list of several nicknames may be given. | |
813 * | |
814 * \return Return code 0 means success. Other value means error, the error | |
815 * code may be obtained through irc_errno(). Any error, generated by the | |
816 * IRC server, is available through irc_callbacks_t::event_numeric. | |
817 * | |
818 * This function queries various information about the nick: username, real | |
819 * name, the IRC server used, the channels user is in, idle time, away mode and so on. | |
820 * | |
821 * Possible error responces for this command from the RFC1459: | |
822 * - ::LIBIRC_RFC_ERR_NOSUCHSERVER | |
823 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
824 * - ::LIBIRC_RFC_ERR_NONICKNAMEGIVEN | |
825 * | |
826 * And the information is returned using the following reply codes. The whois | |
827 * query is completed when ::LIBIRC_RFC_RPL_ENDOFWHOIS message is received. | |
828 * - ::LIBIRC_RFC_RPL_WHOISUSER | |
829 * - ::LIBIRC_RFC_RPL_WHOISCHANNELS | |
830 * - ::LIBIRC_RFC_RPL_WHOISSERVER | |
831 * - ::LIBIRC_RFC_RPL_AWAY | |
832 * - ::LIBIRC_RFC_RPL_WHOISOPERATOR | |
833 * - ::LIBIRC_RFC_RPL_WHOISIDLE | |
834 * - ::LIBIRC_RFC_RPL_ENDOFWHOIS | |
835 * | |
836 * \ingroup ircmd_oth | |
837 */ | |
838 int irc_cmd_whois (irc_session_t * session, const char * nick); | |
839 | |
840 | |
841 /*! | |
842 * \fn irc_cmd_msg (irc_session_t * session, const char * nch, const char * text) | |
843 * \brief Sends the message to the nick or to the channel. | |
844 * | |
845 * \param session An initiated and connected session. | |
846 * \param nch A target nick or channel. Must not be NULL. | |
847 * \param text Message text. Must not be NULL. | |
848 * | |
849 * \return Return code 0 means success. Other value means error, the error | |
850 * code may be obtained through irc_errno(). Any error, generated by the | |
851 * IRC server, is available through irc_callbacks_t::event_numeric. | |
852 * | |
853 * This function is used to send the channel or private messages. The target | |
854 * is determined by \a nch argument: if it describes nick, this will be a | |
855 * private message, if a channel name - public (channel) message. Note that | |
856 * depending on channel modes, you may be required to join the channel to | |
857 * send the channel messages. | |
858 * | |
859 * Possible error responces for this command from the RFC1459: | |
860 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
861 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
862 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
863 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
864 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
865 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
866 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
867 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
868 * | |
869 * On success there is NOTHING generated. | |
870 * | |
871 * \ingroup ircmd_msg | |
872 */ | |
873 int irc_cmd_msg (irc_session_t * session, const char * nch, const char * text); | |
874 | |
875 | |
876 /*! | |
877 * \fn int irc_cmd_me (irc_session_t * session, const char * nch, const char * text) | |
878 * \brief Sends the /me (CTCP ACTION) message to the nick or to the channel. | |
879 * | |
880 * \param session An initiated and connected session. | |
881 * \param nch A target nick or channel. Must not be NULL. | |
882 * \param text Action message text. Must not be NULL. | |
883 * | |
884 * \return Return code 0 means success. Other value means error, the error | |
885 * code may be obtained through irc_errno(). Any error, generated by the | |
886 * IRC server, is available through irc_callbacks_t::event_numeric. | |
887 * | |
888 * This function is used to send the /me message to channel or private. | |
889 * As for irc_cmd_msg, the target is determined by \a nch argument. | |
890 * | |
891 * Possible error responces for this command from the RFC1459: | |
892 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
893 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
894 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
895 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
896 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
897 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
898 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
899 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
900 * | |
901 * On success there is NOTHING generated. | |
902 * However, a ::LIBIRC_RFC_RPL_AWAY reply can be also generated. | |
903 * | |
904 * \sa irc_cmd_msg | |
905 * \ingroup ircmd_msg | |
906 */ | |
907 int irc_cmd_me (irc_session_t * session, const char * nch, const char * text); | |
908 | |
909 | |
910 /*! | |
911 * \fn int irc_cmd_notice (irc_session_t * session, const char * nch, const char * text) | |
912 * \brief Sends the notice to the nick or to the channel. | |
913 * | |
914 * \param session An initiated and connected session. | |
915 * \param nch A target nick or channel. Must not be NULL. | |
916 * \param text Notice text. Must not be NULL. | |
917 * | |
918 * \return Return code 0 means success. Other value means error, the error | |
919 * code may be obtained through irc_errno(). Any error, generated by the | |
920 * IRC server, is available through irc_callbacks_t::event_numeric. | |
921 * | |
922 * This function is used to send the channel or private notices. The target | |
923 * is determined by \a nch argument: if it describes nick, this will be a | |
924 * private message, if a channel name - public (channel) message. Note that | |
925 * depending on channel modes, you may be required to join the channel to | |
926 * send the channel notices. | |
927 * | |
928 * The only difference between message and notice is that, according to RFC | |
929 * 1459, you must not automatically reply to NOTICE messages. | |
930 * | |
931 * Possible error responces for this command from the RFC1459: | |
932 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
933 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
934 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
935 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
936 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
937 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
938 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
939 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
940 * | |
941 * On success there is NOTHING generated. On notices sent to target nick, | |
942 * a ::LIBIRC_RFC_RPL_AWAY reply may be generated. | |
943 * | |
944 * \sa irc_cmd_msg | |
945 * \ingroup ircmd_msg | |
946 */ | |
947 int irc_cmd_notice (irc_session_t * session, const char * nch, const char * text); | |
948 | |
949 | |
950 /*! | |
951 * \fn int irc_cmd_kick (irc_session_t * session, const char * nick, const char * channel, const char * reason) | |
952 * \brief Kick some lazy ass out of channel. | |
953 * | |
954 * \param session An initiated and connected session. | |
955 * \param nick A nick to kick. Must not be NULL. | |
956 * \param channel A channel to kick this nick out of. Must not be NULL. | |
957 * \param reason A reason to kick. May be NULL. | |
958 * | |
959 * \return Return code 0 means success. Other value means error, the error | |
960 * code may be obtained through irc_errno(). Any error, generated by the | |
961 * IRC server, is available through irc_callbacks_t::event_numeric. | |
962 * | |
963 * This function is used to kick a person out of channel. Note that you must | |
964 * be a channel operator to kick anyone. | |
965 * | |
966 * Possible error responces for this command from the RFC1459: | |
967 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS | |
968 * - ::LIBIRC_RFC_ERR_BADCHANMASK | |
969 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL | |
970 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
971 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED | |
972 * | |
973 * On success the irc_callbacks_t::event_kick event will be generated. | |
974 * | |
975 * \sa irc_callbacks_t::event_numeric | |
976 * \ingroup ircmd_ch | |
977 */ | |
978 int irc_cmd_kick (irc_session_t * session, const char * nick, const char * channel, const char * reason); | |
979 | |
980 | |
981 /*! | |
982 * \fn int irc_cmd_ctcp_request (irc_session_t * session, const char * nick, const char * request) | |
983 * \brief Generates a CTCP request. | |
984 * | |
985 * \param session An initiated and connected session. | |
986 * \param nick A target nick to send request to. Must not be NULL. | |
987 * \param request A request string. Must not be NULL. | |
988 * | |
989 * \return Return code 0 means success. Other value means error, the error | |
990 * code may be obtained through irc_errno(). Any error, generated by the | |
991 * IRC server, is available through irc_callbacks_t::event_numeric. | |
992 * | |
993 * This function is used to send a CTCP request. There are four CTCP requests | |
994 * supported by Mirc: | |
995 * VERSION - get the client software name and version | |
996 * FINGER - get the client username, host and real name. | |
997 * PING - get the client delay. | |
998 * TIME - get the client local time. | |
999 * | |
1000 * A reply to the CTCP request will be sent by the irc_callbacks_t::event_ctcp_rep callback; | |
1001 * be sure to define it. | |
1002 * | |
1003 * Possible error responces for this command from the RFC1459: | |
1004 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
1005 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
1006 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
1007 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
1008 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
1009 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
1010 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
1011 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
1012 * | |
1013 * \sa irc_callbacks_t::event_ctcp_rep irc_callbacks_t::event_numeric | |
1014 * \ingroup ctcp | |
1015 */ | |
1016 int irc_cmd_ctcp_request (irc_session_t * session, const char * nick, const char * request); | |
1017 | |
1018 | |
1019 /*! | |
1020 * \fn int irc_cmd_ctcp_reply (irc_session_t * session, const char * nick, const char * reply) | |
1021 * \brief Generates a reply to the CTCP request. | |
1022 * | |
1023 * \param session An initiated and connected session. | |
1024 * \param nick A target nick to send request to. Must not be NULL. | |
1025 * \param reply A reply string. Must not be NULL. | |
1026 * | |
1027 * \return Return code 0 means success. Other value means error, the error | |
1028 * code may be obtained through irc_errno(). Any error, generated by the | |
1029 * IRC server, is available through irc_callbacks_t::event_numeric. | |
1030 * | |
1031 * This function is used to send a reply to the CTCP request, generated by | |
1032 * irc_callbacks_t::event_ctcp_req. Note that you will not receive this event | |
1033 * unless you specify your own handler as \c event_ctcp_req callback during | |
1034 * the IRC session initialization. | |
1035 * | |
1036 * Possible error responces for this command from the RFC1459: | |
1037 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
1038 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
1039 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
1040 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
1041 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
1042 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
1043 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
1044 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
1045 * | |
1046 * \ingroup ctcp | |
1047 */ | |
1048 int irc_cmd_ctcp_reply (irc_session_t * session, const char * nick, const char * reply); | |
1049 | |
1050 | |
1051 /*! | |
1052 * \fn void irc_target_get_nick (const char * target, char *nick, size_t size) | |
1053 * \brief Gets the nick part from the target | |
1054 * | |
1055 * \param target A nick in common IRC server form like tim!root\@mycomain.com | |
1056 * \param nick A buffer to hold the nickname. | |
1057 * \param size A buffer size. If nick is longer than buffer size, it will | |
1058 * be truncated. | |
1059 * | |
1060 * For most events IRC server returns 'origin' (i.e. the person, who | |
1061 * generated this event) in i.e. "common" form, like nick!host\@domain. | |
1062 * However, all the irc_cmd_* functions require just a nick/ | |
1063 * This function parses this origin, and gets the nick, storing it into | |
1064 * user-provided buffer. | |
1065 * A buffer of size 90 should be enough for most nicks :) | |
1066 * | |
1067 * \ingroup nnparse | |
1068 */ | |
1069 void irc_target_get_nick (const char * target, char *nick, size_t size); | |
1070 | |
1071 | |
1072 /*! | |
1073 * \fn void irc_target_get_host (const char * target, char *nick, size_t size) | |
1074 * \brief Gets the host part from the target | |
1075 * | |
1076 * \param target A nick in common IRC server form like tim!root\@mydomain.com | |
1077 * \param nick A buffer to hold the nickname. | |
1078 * \param size A buffer size. If nick is longer than buffer size, it will | |
1079 * be truncated. | |
1080 * | |
1081 * For most events IRC server returns 'origin' (i.e. the person, who | |
1082 * generated this event) in i.e. "common" form, like nick!host\@domain. | |
1083 * I don't know any command, which requires host, but it may be useful :) | |
1084 * This function parses this origin, and gets the host, storing it into | |
1085 * user-provided buffer. | |
1086 * | |
1087 * \ingroup nnparse | |
1088 */ | |
1089 void irc_target_get_host (const char * target, char *nick, size_t size); | |
1090 | |
1091 | |
1092 /*! | |
1093 * \fn int irc_dcc_chat(irc_session_t * session, void * ctx, const char * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid) | |
1094 * \brief Initiates a DCC CHAT. | |
1095 * | |
1096 * \param session An initiated and connected session. | |
1097 * \param ctx A user-supplied DCC session context, which will be passed to | |
1098 * the DCC callback function. May be NULL. | |
1099 * \param nick A nick to DCC CHAT with. | |
1100 * \param callback A DCC callback function, which will be called when | |
1101 * anything is said by other party. Must not be NULL. | |
1102 * \param dccid On success, DCC session ID will be stored in this var. | |
1103 * | |
1104 * \return Return code 0 means success. Other value means error, the error | |
1105 * code may be obtained through irc_errno(). Any error, generated by the | |
1106 * IRC server, is available through irc_callbacks_t::event_numeric. | |
1107 * | |
1108 * This function requests a DCC CHAT between you and other user. For | |
1109 * newbies, DCC chat is like private chat, but it goes directly between | |
1110 * two users, and bypasses IRC server. DCC CHAT request must be accepted | |
1111 * by other side before you can send anything. | |
1112 * | |
1113 * When the chat is accepted, terminated, or some data is received, the | |
1114 * callback function is called. See the details in irc_dcc_callback_t | |
1115 * declaration. | |
1116 * | |
1117 * Possible error responces for this command from the RFC1459: | |
1118 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
1119 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
1120 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
1121 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
1122 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
1123 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
1124 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
1125 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
1126 * | |
1127 * \sa irc_dcc_callback_t irc_dcc_msg | |
1128 * \ingroup dccstuff | |
1129 */ | |
1130 int irc_dcc_chat (irc_session_t * session, void * ctx, const char * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid); | |
1131 | |
1132 | |
1133 /*! | |
1134 * \fn int irc_dcc_msg (irc_session_t * session, irc_dcc_t dccid, const char * text) | |
1135 * \brief Sends the message to the specific DCC CHAT | |
1136 * | |
1137 * \param session An IRC session. | |
1138 * \param dccid A DCC session ID, which chat request must have been accepted. | |
1139 * \param text Message text. Must not be NULL. | |
1140 * | |
1141 * \return Return code 0 means success. Other value means error, the error | |
1142 * code may be obtained through irc_errno(). | |
1143 * | |
1144 * This function is used to send the DCC CHAT messages. DCC CHAT request | |
1145 * must be initiated and accepted first (or just accepted, if initiated by | |
1146 * other side). | |
1147 * | |
1148 * \sa irc_dcc_chat | |
1149 * \ingroup dccstuff | |
1150 */ | |
1151 int irc_dcc_msg (irc_session_t * session, irc_dcc_t dccid, const char * text); | |
1152 | |
1153 | |
1154 /*! | |
1155 * \fn int irc_dcc_accept (irc_session_t * session, irc_dcc_t dccid, void * ctx, irc_dcc_callback_t callback) | |
1156 * \brief Accepts a remote DCC CHAT or DCC RECVFILE request. | |
1157 * | |
1158 * \param session An initiated and connected session. | |
1159 * \param dccid A DCC session ID, returned by appropriate callback. | |
1160 * \param ctx A user-supplied DCC session context, which will be passed | |
1161 * to the DCC callback function. May be NULL. | |
1162 * \param callback A DCC callback function, which will be called when | |
1163 * anything is said by other party. Must not be NULL. | |
1164 * | |
1165 * \return Return code 0 means success. Other value means error, the error | |
1166 * code may be obtained through irc_errno(). | |
1167 * | |
1168 * This function accepts a remote DCC request - either DCC CHAT or DCC FILE. | |
1169 * After the request is accepted, the supplied callback will be called, | |
1170 * and you can start sending messages or receiving the file. | |
1171 * | |
1172 * This function should be called only after either event_dcc_chat_req or | |
1173 * event_dcc_send_req events are generated, and should react to them. It is | |
1174 * possible not to call irc_dcc_accept or irc_dcc_decline immediately in | |
1175 * callback function - you may just return, and call it later. However, to | |
1176 * prevent memory leaks, you must call either irc_dcc_decline or | |
1177 * irc_dcc_accept for any incoming DCC request. | |
1178 * | |
1179 * \sa irc_dcc_decline event_dcc_chat_req event_dcc_send_req | |
1180 * \ingroup dccstuff | |
1181 */ | |
1182 int irc_dcc_accept (irc_session_t * session, irc_dcc_t dccid, void * ctx, irc_dcc_callback_t callback); | |
1183 | |
1184 | |
1185 /*! | |
1186 * \fn int irc_dcc_decline (irc_session_t * session, irc_dcc_t dccid) | |
1187 * \brief Declines a remote DCC CHAT or DCC RECVFILE request. | |
1188 * | |
1189 * \param session An initiated and connected session. | |
1190 * \param dccid A DCC session ID, returned by appropriate callback. | |
1191 * | |
1192 * \return Return code 0 means success. Other value means error, the error | |
1193 * code may be obtained through irc_errno(). | |
1194 * | |
1195 * This function declines a remote DCC request - either DCC CHAT or DCC FILE. | |
1196 * | |
1197 * This function should be called only after either event_dcc_chat_req or | |
1198 * event_dcc_send_req events are generated, and should react to them. It is | |
1199 * possible not to call irc_dcc_accept or irc_dcc_decline immediately in | |
1200 * callback function - you may just return, and call it later. However, to | |
1201 * prevent memory leaks, you must call either irc_dcc_decline or | |
1202 * irc_dcc_accept for any incoming DCC request. | |
1203 * | |
1204 * Do not use this function to close the accepted or initiated DCC session. | |
1205 * Use irc_dcc_destroy instead. | |
1206 * | |
1207 * \sa irc_dcc_accept irc_callbacks_t::event_dcc_chat_req irc_callbacks_t::event_dcc_send_req irc_dcc_destroy | |
1208 * \ingroup dccstuff | |
1209 */ | |
1210 int irc_dcc_decline (irc_session_t * session, irc_dcc_t dccid); | |
1211 | |
1212 | |
1213 /*! | |
1214 * \fn int irc_dcc_sendfile (irc_session_t * session, void * ctx, const char * nick, const char * filename, irc_dcc_callback_t callback, irc_dcc_t * dccid) | |
1215 * \brief Sends a file via DCC. | |
1216 * | |
1217 * \param session An initiated and connected session. | |
1218 * \param ctx A user-supplied DCC session context, which will be passed to | |
1219 * the DCC callback function. May be NULL. | |
1220 * \param nick A nick to send file via DCC to. | |
1221 * \param filename A file name to sent. Must be an existing file. | |
1222 * \param callback A DCC callback function, which will be called when | |
1223 * file sent operation is failed, progressed or completed. | |
1224 * \param dccid On success, DCC session ID will be stored in this var. | |
1225 * | |
1226 * \return Return code 0 means success. Other value means error, the error | |
1227 * code may be obtained through irc_errno(). Any error, generated by the | |
1228 * IRC server, is available through irc_callbacks_t::event_numeric. | |
1229 * | |
1230 * This function generates a DCC SEND request to send the file. When it is | |
1231 * accepted, the file is sent to the remote party, and the DCC session is | |
1232 * closed. The send operation progress and result can be checked in | |
1233 * callback. See the details in irc_dcc_callback_t declaration. | |
1234 * | |
1235 * Possible error responces for this command from the RFC1459: | |
1236 * - ::LIBIRC_RFC_ERR_NORECIPIENT | |
1237 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND | |
1238 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN | |
1239 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL | |
1240 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL | |
1241 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL | |
1242 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS | |
1243 * - ::LIBIRC_RFC_ERR_NOSUCHNICK | |
1244 * | |
1245 * \sa irc_dcc_callback_t | |
1246 * \ingroup dccstuff | |
1247 */ | |
1248 int irc_dcc_sendfile (irc_session_t * session, void * ctx, const char * nick, const char * filename, irc_dcc_callback_t callback, irc_dcc_t * dccid); | |
1249 | |
1250 | |
1251 /*! | |
1252 * \fn int irc_dcc_destroy (irc_session_t * session, irc_dcc_t dccid) | |
1253 * \brief Destroys a DCC session. | |
1254 * | |
1255 * \param session An initiated and connected session. | |
1256 * \param dccid A DCC session ID. | |
1257 * | |
1258 * \return Return code 0 means success. Other value means error, the error | |
1259 * code may be obtained through irc_errno(). | |
1260 * | |
1261 * This function closes the DCC connection (if available), and destroys | |
1262 * the DCC session, freeing the used resources. It can be called in any | |
1263 * moment, even from callbacks or from different threads. | |
1264 * | |
1265 * Note that when DCC session is finished (either with success or failure), | |
1266 * you should not destroy it - it will be destroyed automatically. | |
1267 * | |
1268 * \ingroup dccstuff | |
1269 */ | |
1270 int irc_dcc_destroy (irc_session_t * session, irc_dcc_t dccid); | |
1271 | |
1272 | |
1273 /*! | |
1274 * \fn void irc_get_version (unsigned int * high, unsigned int * low) | |
1275 * \brief Obtains a libircclient version. | |
1276 * | |
1277 * \param high A pointer to receive the high version part. | |
1278 * \param low A pointer to receive the low version part. | |
1279 * | |
1280 * This function returns the libircclient version. You can use the version either | |
1281 * to check whether required options are available, or to output the version. | |
1282 * The preferred printf-like format string to output the version is: | |
1283 * | |
1284 * printf ("Version: %d.%02d", high, low); | |
1285 * | |
1286 * \ingroup common | |
1287 */ | |
1288 void irc_get_version (unsigned int * high, unsigned int * low); | |
1289 | |
1290 | |
1291 /*! | |
1292 * \fn void irc_set_ctx (irc_session_t * session, void * ctx) | |
1293 * \brief Sets the IRC session context. | |
1294 * | |
1295 * \param session An initiated session. | |
1296 * \param ctx A context. | |
1297 * | |
1298 * This function sets the user-defined context for this IRC session. This | |
1299 * context is not used by libircclient. Its purpose is to store session-specific | |
1300 * user data, which may be obtained later by calling irc_get_ctx(). | |
1301 * Note that libircclient just 'carries out' this pointer. If you allocate some | |
1302 * memory, and store its address in ctx (most common usage), it is your | |
1303 * responsibility to free it before calling irc_destroy_session(). | |
1304 * | |
1305 * \sa irc_get_ctx | |
1306 * \ingroup contexts | |
1307 */ | |
1308 void irc_set_ctx (irc_session_t * session, void * ctx); | |
1309 | |
1310 /*! | |
1311 * \fn void irc_set_ctcp_version (irc_session_t * session, const char *version) | |
1312 * \brief Sets the internal CTCP VERSION | |
1313 * | |
1314 * \param session an Initiated session. | |
1315 * \param version the version to reply | |
1316 * | |
1317 * This function sets an internal user-defined version to reply on CTCP | |
1318 * VERSION request. If none is given, a default one is provided. The parameter | |
1319 * version is copied and can be freed by the user. | |
1320 * | |
1321 * \ingroup contexts | |
1322 */ | |
1323 void irc_set_ctcp_version(irc_session_t * session, const char * version); | |
1324 | |
1325 /*! | |
1326 * \fn void * irc_get_ctx (irc_session_t * session) | |
1327 * \brief Returns the IRC session context. | |
1328 * | |
1329 * \param session An initiated session. | |
1330 * | |
1331 * This function returns the IRC session context, which was set by | |
1332 * irc_set_ctx(). If no context was set, this function returns NULL. | |
1333 * | |
1334 * \sa irc_set_ctx | |
1335 * \ingroup contexts | |
1336 */ | |
1337 void * irc_get_ctx (irc_session_t * session); | |
1338 | |
1339 | |
1340 /*! | |
1341 * \fn int irc_errno (irc_session_t * session) | |
1342 * \brief Returns the last error code. | |
1343 * | |
1344 * \param session An initiated session. | |
1345 * | |
1346 * This function returns the last error code associated with last operation | |
1347 * of this IRC session. Possible error codes are defined in libirc_errors.h | |
1348 * | |
1349 * As usual, next errno rules apply: | |
1350 * - irc_errno() should be called ONLY if the called function fails; | |
1351 * - irc_errno() doesn't return 0 if function succeed; actually, the return | |
1352 * value will be undefined. | |
1353 * - you should call irc_errno() IMMEDIATELY after function fails, before | |
1354 * calling any other libircclient function. | |
1355 * | |
1356 * \sa irc_strerror | |
1357 * \ingroup errors | |
1358 */ | |
1359 int irc_errno (irc_session_t * session); | |
1360 | |
1361 | |
1362 /*! | |
1363 * \fn const char * irc_strerror (int ircerrno) | |
1364 * \brief Returns the text error message associated with this error code. | |
1365 * | |
1366 * \param ircerrno A numeric error code returned by irc_errno() | |
1367 * | |
1368 * This function returns the text representation of the given error code. | |
1369 * | |
1370 * \sa irc_errno() | |
1371 * \ingroup errors | |
1372 */ | |
1373 const char * irc_strerror (int ircerrno); | |
1374 | |
1375 | |
1376 /*! | |
1377 * \fn void irc_option_set (irc_session_t * session, unsigned int option) | |
1378 * \brief Sets the libircclient option. | |
1379 * | |
1380 * \param session An initiated session. | |
1381 * \param option An option from libirc_options.h | |
1382 * | |
1383 * This function sets the libircclient option, changing libircclient behavior. See the | |
1384 * option list for the meaning for every option. | |
1385 * | |
1386 * \sa irc_option_reset | |
1387 * \ingroup options | |
1388 */ | |
1389 void irc_option_set (irc_session_t * session, unsigned int option); | |
1390 | |
1391 | |
1392 /*! | |
1393 * \fn void irc_option_reset (irc_session_t * session, unsigned int option) | |
1394 * \brief Resets the libircclient option. | |
1395 * | |
1396 * \param session An initiated session. | |
1397 * \param option An option from libirc_options.h | |
1398 * | |
1399 * This function removes the previously set libircclient option, changing libircclient | |
1400 * behavior. See the option list for the meaning for every option. | |
1401 * | |
1402 * \sa irc_option_set | |
1403 * \ingroup options | |
1404 */ | |
1405 void irc_option_reset (irc_session_t * session, unsigned int option); | |
1406 | |
1407 | |
1408 /*! | |
1409 * \fn char * irc_color_strip_from_mirc (const char * message) | |
1410 * \brief Removes all the color codes and format options. | |
1411 * | |
1412 * \param message A message from IRC | |
1413 * | |
1414 * \return Returns a new plain text message with stripped mIRC color codes. | |
1415 * Note that the memory for the new message is allocated using malloc(), so | |
1416 * you should free it using free() when it is not used anymore. If memory | |
1417 * allocation failed, returns 0. | |
1418 * | |
1419 * \sa irc_color_convert_from_mirc irc_color_convert_to_mirc | |
1420 * \ingroup colors | |
1421 */ | |
1422 char * irc_color_strip_from_mirc (const char * message); | |
1423 | |
1424 | |
1425 /*! | |
1426 * \fn char * irc_color_convert_from_mirc (const char * message) | |
1427 * \brief Converts all the color codes and format options to libircclient colors. | |
1428 * | |
1429 * \param message A message from IRC | |
1430 * | |
1431 * \return Returns a new message with converted mIRC color codes and format | |
1432 * options. See the irc_color_convert_to_mirc() help to see how the colors | |
1433 * are converted.\n | |
1434 * Note that the memory for the new message is allocated using malloc(), so | |
1435 * you should free it using free() when it is not used anymore. If memory | |
1436 * allocation failed, returns 0. | |
1437 * | |
1438 * \sa irc_color_strip_from_mirc irc_color_convert_to_mirc | |
1439 * \ingroup colors | |
1440 */ | |
1441 char * irc_color_convert_from_mirc (const char * message); | |
1442 | |
1443 | |
1444 /*! | |
1445 * \fn char * irc_color_convert_to_mirc (const char * message) | |
1446 * \brief Converts all the color codes from libircclient format to mIRC. | |
1447 * | |
1448 * \param message A message with color codes | |
1449 * | |
1450 * \return Returns a new message with converted color codes and format | |
1451 * options, or 0 if memory could not be allocated. Note that the memory for | |
1452 * the new message is allocated using malloc(), so you should free it using | |
1453 * free() when it is not used anymore. | |
1454 * | |
1455 * The color system of libircclient is designed to be easy to use, and | |
1456 * portable between different IRC clients. Every color or format option is | |
1457 * described using plain text commands written between square brackets. The | |
1458 * possible codes are: | |
1459 * - [B] ... [/B] - bold format mode. Everything between [B] and [/B] is written in \b bold. | |
1460 * - [I] ... [/I] - italic/reverse format mode. Everything between [I] and [/I] is written in \c italic, or reversed (however, because some clients are incapable of rendering italic text, most clients display this as normal text with the background and foreground colors swapped). | |
1461 * - [U] ... [/U] - underline format mode. Everything between [U] and [/U] is written underlined. | |
1462 * - [COLOR=RED] ... [/COLOR] - write the text using specified foreground color. The color is set by using the \c COLOR keyword, and equal sign followed by text color code (see below). | |
1463 * - [COLOR=RED/BLUE] ... [/COLOR] - write the text using specified foreground and background color. The color is set by using the \c COLOR keyword, an equal sign followed by text foreground color code, a dash and a text background color code. | |
1464 * | |
1465 * The supported text colors are: | |
1466 * - WHITE | |
1467 * - BLACK | |
1468 * - DARKBLUE | |
1469 * - DARKGREEN | |
1470 * - RED | |
1471 * - BROWN | |
1472 * - PURPLE | |
1473 * - OLIVE | |
1474 * - YELLOW | |
1475 * - GREEN | |
1476 * - TEAL | |
1477 * - CYAN | |
1478 * - BLUE | |
1479 * - MAGENTA | |
1480 * - DARKGRAY | |
1481 * - LIGHTGRAY | |
1482 * | |
1483 * Examples of color sequences: | |
1484 * \code | |
1485 * Hello, [B]Tim[/B]. | |
1486 * [U]Arsenal[/U] got a [COLOR=RED]red card[/COLOR] | |
1487 * The tree[U]s[/U] are [COLOR=GREEN/BLACK]green[/COLOR] | |
1488 * \endcode | |
1489 * | |
1490 * \sa irc_color_strip_from_mirc irc_color_convert_from_mirc | |
1491 * \ingroup colors | |
1492 */ | |
1493 char * irc_color_convert_to_mirc (const char * message); | |
1494 | |
1495 #ifdef __cplusplus | |
1496 } | |
1497 #endif | |
1498 | |
1499 #endif /* INCLUDE_LIBIRC_H */ |