PageRenderTime 68ms CodeModel.GetById 35ms RepoModel.GetById 0ms app.codeStats 0ms

/libs/libircclient/libircclient.h

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