Mercurial > irccd
changeset 1057:049b8fe77535
man: add libirccd-server.3
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 21 Jun 2021 10:10:19 +0200 |
parents | 58df32d96d5d |
children | c42b2540f849 |
files | GNUmakefile man/libirccd-server.3 |
diffstat | 2 files changed, 413 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/GNUmakefile Sun Jun 20 15:14:12 2021 +0200 +++ b/GNUmakefile Mon Jun 21 10:10:19 2021 +0200 @@ -101,6 +101,7 @@ man/libirccd-hook.3 \ man/libirccd-log.3 \ man/libirccd-rule.3 \ + man/libirccd-server.3 \ man/libirccd-subst.3 \ man/libirccd-util.3 \ man/libirccd.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-server.3 Mon Jun 21 10:10:19 2021 +0200 @@ -0,0 +1,412 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr> +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-SERVER 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-server +.Nd IRC server functions +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/server.h +.Ft "struct irc_server *" +.Fo irc_server_new +.Fa "const char *id" +.Fa "const char *nickname" +.Fa "const char *username" +.Fa "const char *realname" +.Fa "const char *hostname" +.Fa "unsigned int port" +.Fc +.Ft void +.Fn irc_server_connect "struct irc_server *s" +.Ft void +.Fn irc_server_disconnect "struct irc_server *s" +.Ft void +.Fn irc_server_reconnect "struct irc_server *s" +.Ft void +.Fn irc_server_prepare "const struct irc_server *, struct pollfd *fd" +.Ft void +.Fn irc_server_flush "struct irc_server *s, const struct pollfd *fd" +.Ft int +.Fn irc_server_poll "struct irc_server *s, struct irc_event *ev" +.Ft struct irc_channel * +.Fn irc_server_find "struct irc_server *s, const char *channel" +.Ft int +.Fn irc_server_send "struct irc_server *s, const char *fmt, ..." +.Ft int +.Fn irc_server_invite "struct irc_server *s, const char *channel, const char *target" +.Ft int +.Fn irc_server_join "struct irc_server *s, const char *channel, const char *pass" +.Ft int +.Fn irc_server_kick "struct irc_server *s, const char *channel, const char *target, const char *reason" +.Ft int +.Fn irc_server_part "struct irc_server *s, const char *channel, const char *reason" +.Ft int +.Fn irc_server_topic "struct irc_server *s, const char *channel, const char *topic" +.Ft int +.Fn irc_server_message "struct irc_server *s, const char *channel, const char *message" +.Ft int +.Fn irc_server_me "struct irc_server *s, const char *channel, const char *message" +.Ft int +.Fn irc_server_mode "struct irc_server *s, const char *channel, const char *mode, const char *args" +.Ft int +.Fn irc_server_names "struct irc_server *s, const char *channel" +.Ft int +.Fn irc_server_nick "struct irc_server *s, const char *nick" +.Ft int +.Fn irc_server_notice "struct irc_server *s, const char *channel, const char *message" +.Ft int +.Fn irc_server_whois "struct irc_server *s, const char *nickname" +.Ft int +.Fn irc_server_strip "const struct irc_server *s, const char **string" +.Ft void +.Fn irc_server_split "const char *string, struct irc_server_user *ident" +.Ft void +.Fn irc_server_incref "struct irc_server *s" +.Ft void +.Fn irc_server_decref "struct irc_server *s" +.\" DESCRIPTION +.Sh DESCRIPTION +This API provides functions to operate with an IRC server. When servers are +managed through the irccd instance they are automatically connected, reconnected +and removed when needed. +.Pp +It also have a large set of functions to send messages, change channel topics, +join channels and such. +.Pp +A server by itself is asynchronous, any function in the API will never block +because it is queued into local buffers. To accomplish this feature the server +relies on the user to use +.Xr poll 2 +and indicate the server that a network event happened. This is normally never +needed from the user side as long as the server is managed through irccd. See +.Xr libirccd-irccd 3 +for more details. +.Pp +The header exposes the following structures: +.Bd -literal +struct irc_server_user { + char nickname[IRC_NICKNAME_LEN]; /* IRC nickname */ + char username[IRC_USERNAME_LEN]; /* IRC username */ + char host[IRC_HOST_LEN]; /* hostname part */ +}; +.Ed +.Pp +This structure describes an IRC user. +.Bd -literal +struct irc_server_ident { + char nickname[IRC_NICKNAME_LEN]; /* desired nickname */ + char password[IRC_PASSWORD_LEN]; /* server password */ + char ctcpversion[IRC_CTCPVERSION_LEN]; /* CTCP VERSION to reply */ +}; +.Ed +.Pp +This structure holds the informations about the credentials for connecting to +the IRC server. +.Bd -literal +struct irc_server_params { + char chantypes[IRC_CHANTYPES_LEN]; /* channel types prefixes */ + char charset[IRC_CHARSET_LEN]; /* charset recommended */ + char casemapping[IRC_CASEMAPPING_LEN]; /* case mapping */ + unsigned int chanlen; /* maximum channel length */ + unsigned int nicklen; /* maximum nickname length */ + unsigned int topiclen; /* maximum topic length */ + unsigned int awaylen; /* maximum away message length */ + unsigned int kicklen; /* maximum kick message length */ + struct { + char mode; /* mode (e.g. ov). */ + char symbol; /* symbol used (e.g. @+). */ + } prefixes[IRC_USERMODES_LEN]; +}; +.Ed +.Pp +This structure holds readonly information about the server. It is filled once a +server is connected and updated depending on IRC event. User modification on +this structure has no effects. +.Bd -literal +struct irc_server { + char name[IRC_ID_LEN]; /* server identifier */ + char prefix[IRC_PREFIX_LEN]; /* prefix for plugin commands */ + struct irc_server_ident ident; /* identity to use */ + struct irc_server_params params; /* server parameters */ + enum irc_server_flags flags; /* optional user flags */ + struct irc_channel_list channels; /* list of channels */ + LIST_ENTRY(irc_server) link; +}; +.Ed +.Pp +This structure is a connection to the IRC server. It is implemented as a state +machine and requires read/write steps from the main loop. They are usually +managed directly from the +.Xr irccd 1 +daemon and should not require user actions. +The +.Vt struct irc_server +is implemented as linked list through the +.Va link +field usable through +.Xr queue 3 +macros. +.Pp +Note: few other private fields are not listed as they must not be used by the +user. +.Pp +.\" irc_server_new +The +.Fn irc_server_new +function heap allocates a new server object in disconnected state. The argument +.Fa id +must be a valid unique identifier. Arguments +.Fa nickname , username , realname +refer to the IRC identity. The argument +.Fa hostname +and +.Fa port +specifies the IRC server address (or hostname) and its port. This function never +return NULL. +.Pp +.\" irc_server_connect +The +.Fn irc_server_connect +function starts connecting the server +.Fa s . +Connection does not happen immediately because the server is setup in +non-blocking mode, as such several steps are required and are performed with the +help of the +.Fn irc_server_prepare +and +.Fn irc_server_flush . +.Pp +.\" irc_server_disconnect +The +.Fn irc_server_disconnect +function immediately shuts down the connection to +.Ar s +server by closing the socket. It is possible to reconnect again using +.Fn irc_server_connect . +.Pp +.\" irc_server_reconnect +The +.Fn irc_server_reconnect +function closes the connection on the server +.Ar s +and reconnect immediately. +.Pp +.\" irc_server_prepare +.\" irc_server_flush +The +.Fn irc_server_prepare +function fills the +.Xr poll 2 +structure specified by +.Fa fd +about events that the server requires depending on read/write conditions from +the server +.Fa s . +Then, the +.Fn irc_server_flush +function performs any pending read/write operation depending on the result of the +.Fa fd +structure which should have been listened with +.Xr poll 2 +from user side. Both functions are usually never required to be called manually +as long as the servers are put into the irccd instance. See +.Xr libirccd-irccd 3 +for more details. +.Pp +.\" irc_server_poll +The +.Fn irc_server_poll +function seeks for any pending IRC event in server +.Fa s . +It should be called periodically in the main loop to remove pending events. This +function is usually never required to be called manually from the user. +.Pp +.\" irc_server_send +The function +.Fn irc_server_send +sends a raw unparsed message to the server +.Fa s +with a +.Xr printf 3 +format like. The CRLF delimiter is automatically appended. +.Pp +.\" irc_server_invite +The +.Fn irc_server_invite +function invites +.Fa target +to the +.Fa channel +on the server +.Fa s . +.Pp +.\" irc_server_join +The +.Fn irc_server_join +creates a request to join +.Fa channel +using an optional +.Fa pass +if not NULL on the server +.Fa s . +If the server is not yet connected, it is appended to the list of channels to +join and they will be joined once connected. +.Pp +.\" irc_server_kick +The +.Fn irc_server_kick +function kicks +.Fa target +from channel +.Fa channel +using a specified +.Fa reason +if not NULL from the server +.Fa s . +.Pp +.\" irc_server_part +The +.Fn irc_server_part +leaves +.Fa channel +using a specified +.Fa reason +if not NULL from the server +.Fa s . +.Pp +.\" irc_server_topic +The +.Fn irc_server_topic +sets +.Fa topic +into the specified +.Fa channel +from the server +.Fa s . +.\" irc_server_message +The +.Fn irc_server_message +sends a private +.Fa message +to +.Fa channel +into the server +.Fa s . +The argument +.Fa channel +can be a nickname as well. +.Pp +.\" irc_server_me +The +.Fn irc_server_me +sends an action emote +.Fa message +to +.Fa channel +into the server +.Fa s . +The argument +.Fa channel +can be a nickname as well. This is also known as /me in popular IRC clients. +.Pp +.\" irc_server_mode +The +.Fn irc_server_mode +function sets +.Fa mode +and its +.Fa args +into the specified +.Fa channel +on the server +.Fa s . +.Pp +.\" irc_server_names +The +.Fn irc_server_names +requests a name listing on the specified +.Fa channel +from the server +.Fa s . +Names are incoming asynchronously using a names event. See +.Xr libirccd-event 3 +for more details. +.Pp +.\" irc_server_nick +The +.Fn irc_server_nick +change the bots nickname to +.Fa nick +on the server +.Fa s . +If the server is not already connected this operation is immediate, otherwise a +request is sent and the nick change can fail (e.g. if already used). +.Pp +.\" irc_server_notice +The +.Fn irc_server_notice +sends a private +.Fa notice +to +.Fa channel +into the server +.Fa s . +The argument +.Fa channel +can be a nickname as well. +.Pp +.\" irc_server_whois +The +.Fn irc_server_whois +sends an asynchronous request to obtain whois information about +.Fa nickname +from the server +.Fa s . +.Pp +.\" irc_server_strip +The +.Fn irc_server_strip +function can be used to extract user modes from +.Fa string +and return modes that is has (e.g. voice, op, halfop). The +.Fa string +pointer will be incremented for each prefix found at the start of the string. +Example: if a string +.Dq @+francis +is passed, the function will increase the pointer to a result of +.Dq francis +and both voice and op will be returned as OR'ed flags. The server +.Fa s +has to be specified because some IRC server may use different symbol prefixes +and those are detected at connection time. +.Pp +.\" irc_server_incref +.\" irc_server_decref +Both +.Fn irc_server_incref +and +.Fn irc_server_decref +increment or decrement respectively the usage count of the server +.Fa s . +It allows the storage of servers inside plugins so they still refer to a valid +memory area even if user decide to disconnect some servers. +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 , +.Xr libirccd-irccd 3