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