PageRenderTime 92ms CodeModel.GetById 63ms 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

Large files files are truncated, but you can click here to view the full 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…

Large files files are truncated, but you can click here to view the full file