1500 lines
60 KiB
C
1500 lines
60 KiB
C
/*
|
|
* 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 */
|