From 97aee1be2fda9c6639d47384908f8806365b4e39 Mon Sep 17 00:00:00 2001 From: "Kevin L. Mitchell" Date: Fri, 15 Jun 2001 23:45:06 +0000 Subject: [PATCH] Author: Kev Log message: This is the last of the API documentation that I set out to write. Enjoy! git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@505 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- doc/api/joinbuf.txt | 92 +++++++++++++++ doc/api/jupe.txt | 161 +++++++++++++++++++++++++ doc/api/modebuf.txt | 282 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 535 insertions(+) create mode 100644 doc/api/joinbuf.txt create mode 100644 doc/api/jupe.txt create mode 100644 doc/api/modebuf.txt diff --git a/doc/api/joinbuf.txt b/doc/api/joinbuf.txt new file mode 100644 index 0000000..6eb7680 --- /dev/null +++ b/doc/api/joinbuf.txt @@ -0,0 +1,92 @@ +IRC wouldn't be of much interest without the ability for users to join +channels. Of course, they must also be able to leave those channels +when they get bored of the conversation there. Users can join or +leave multiple channels at once. Sometimes these JOIN and PART +messages can be ganged together into a single message. This is +facilitated by the JoinBuf system. + + +struct JoinBuf; + +This structure is used to accumulate and describe several channel +joins or parts. None of its fields are directly or indirectly +accessible to the application; a struct JoinBuf is only suitable for +passing to the joinbuf_*() suite of functions. JoinBuf structures +must be allocated by the caller. + + + +#define JOINBUF_TYPE_JOIN 0 /* send JOINs */ + +This macro tells joinbuf_init() that the JoinBuf is being used to +generate several channel joins. + + + +#define JOINBUF_TYPE_CREATE 1 /* send CREATEs */ + +This macro tells joinbuf_init() that the JoinBuf is being used to +generate several channel creations. + + + +#define JOINBUF_TYPE_PART 2 /* send PARTs */ + +This macro tells joinbuf_init() that the JoinBuf is being used to +generate several channel parts. + + + +#define JOINBUF_TYPE_PARTALL 3 /* send local PARTs, but not remote */ + +This macro tells joinbuf_init() that the JoinBuf is being used to +record PARTs for all the user's channels. That fact is communicated +to servers through a more efficient means than sending several PARTs, +but local clients can only be made aware of it with standard PART +messages. + + + +void joinbuf_init(struct JoinBuf *jbuf, struct Client *source, + struct Client *connect, unsigned int type, char *comment, + time_t create); + +This function is used to initialize a caller allocated JoinBuf, +specified by _jbuf_. The originating user is specified by _source_; +the connection on which the message was received is specified by +_connect_; the type (one of the JOINBUF_TYPE_* macros described above) +is specified by _type_. PART messages may have an optional comment, +which is passed through the _comment_ parameter. JOIN and CREATE +messages require a timestamp, passed through the _create_ parameter. + + + +void joinbuf_join(struct JoinBuf *jbuf, struct Channel *chan, + unsigned int flags); + +This function adds a channel to the JoinBuf. The _chan_ parameter +specifies the channel, and may only be NULL if the JoinBuf type is +JOINBUF_TYPE_JOIN--this will cause a "JOIN 0" message to be sent to +all servers. The _flags_ parameter is used to specify the user's +current channel flags. For JOINBUF_TYPE_PART and JOINBUF_TYPE_PARTALL +JoinBufs, passing CHFL_ZOMBIE will inhibit sending the PART to all +channel users, and CHFL_BANNED will inhibit sending the user's +specified PART comment. For JOINBUF_TYPE_JOIN or JOINBUF_TYPE_CREATE +JoinBufs, the _flags_ parameter is used to set the initial channel +modes for the user. + + + +int joinbuf_flush(struct JoinBuf *jbuf); + +This function simply flushes the contents of the struct JoinBuf to the +appropriate destinations. + + + +Kev + + + +[2001-6-15 Kev] Initial documentation of the JoinBuf subsystem. + diff --git a/doc/api/jupe.txt b/doc/api/jupe.txt new file mode 100644 index 0000000..c776a17 --- /dev/null +++ b/doc/api/jupe.txt @@ -0,0 +1,161 @@ +Occasionally, a server will become incorrectly configured or will +start behaving incorrectly. Even more rarely, a server will be +compromised, and a modified version of the server put in place to +cause problems. These cases are the reason for the _jupe_, a +temporary server ban. This is similar to the G-line, which is a +temporary user ban, and indeed, the jupe API is very similar to the +G-line API. + + +#define JUPE_MAX_EXPIRE 604800 /* max expire: 7 days */ + +This macro lists the maximum expire time a jupe is permitted to have. +This value is limited to 7 days to prevent abuse of the system. + + + +#define JUPE_ACTIVE 0x0001 + +This flag is used to indicate that a given jupe is globally active. + + + +#define JUPE_LOCAL 0x0002 + +This flag is used to indicate that a given jupe is a local one. Local +jupes do not affect users on other servers. + + + +#define JUPE_LDEACT 0x0004 /* locally deactivated */ + +This flag is set on global jupes that have been locally deactivated. +This flag is maintained internally by the jupe subsystem. + + + +struct Jupe; + +The struct Jupe describes everything about a given jupe. None of its +fields may be directly accessed by the application; use the functions +and macros described below instead. + + + +int JupeIsActive(struct Jupe* j); + +This macro returns a non-zero value if the jupe is active, or 0 +otherwise. If a jupe is locally deactivated, this macro will always +return 0. + + + +int JupeIsRemActive(struct Jupe* j); + +This macro returns a non-zero value if the jupe is active, ignoring +whether or not it is locally deactivated. + + + +int JupeIsLocal(struct Jupe* j); + +This macro returns a non-zero value if the jupe is local only. + + + +char* JupeServer(struct Jupe* j); + +This macro returns the server name associated with the jupe. + + + +char* JupeReason(struct Jupe* j); + +This macro returns the reason that was given when the jupe was set. + + + +time_t JupeLastMod(struct Jupe* j); + +Jupes have a modification time that must be monotonically increasing. +This macro simply returns that modification time. + + + +int jupe_add(struct Client *cptr, struct Client *sptr, char *server, + char *reason, time_t expire, time_t lastmod, unsigned int flags); + +This function simply adds a jupe, set by _sptr_ and with a _server_, +_reason_, _expire_, and _lastmod_ as specified. The _flags_ parameter +is a bit mask consisting of the binary OR of JUPE_LOCAL and +JUPE_ACTIVE, as appropriate. The jupe_add() function will propagate +the jupe to all servers (assuming JUPE_LOCAL was not passed), and will +break its link to the server specified by _server_ (assuming that the +JUPE_ACTIVE flag _was_ passed). + + + +int jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe, + time_t lastmod, unsigned int flags); + +This function activates the jupe specified by _jupe_, setting its +_lastmod_ time as specified. If _flags_ is JUPE_LOCAL and if the jupe +is locally deactivated, this function will turn off the local +deactivation flag, but will not modify _lastmod_. If the jupe is +globally deactivated, passing this function the JUPE_LOCAL flag will +have no effect. + + + +int jupe_deactivate(struct Client *cptr, struct Client *sptr, + struct Jupe *jupe, time_t lastmod, unsigned int flags); + +This function is similar to jupe_activate() except that it deactivates +the jupe. If the given jupe is local, then the jupe is deleted from +memory. In all other cases, the jupe is simply deactivated, either +locally (if JUPE_LOCAL was passed via _flags_) or globally. Global +deactivation will update the _lastmod_ time. + + + +struct Jupe* jupe_find(char *server); + +This function searches for a jupe matching the given _server_. + + + +void jupe_free(struct Jupe *jupe); + +This function releases all storage associated with a given jupe. + + + +void jupe_burst(struct Client *cptr); + +This function generates a burst of all existing global jupes and sends +them to the server specified by _cptr_. + + + +int jupe_resend(struct Client *cptr, struct Jupe *jupe); + +This function resends the _jupe_ to a server specified by _cptr_. +This may be used if, for instance, it is discovered that a server is +not synchronized with respect to a particular jupe. + + + +int jupe_list(struct Client *sptr, char *server); + +This function sends the information about a jupe matching _server_ to +the client specified by _sptr_. If _server_ is a NULL pointer, a list +of all jupes is sent. + + + +Kev + + + +[2001-6-15 Kev] Initial documentation of the jupe API. + diff --git a/doc/api/modebuf.txt b/doc/api/modebuf.txt new file mode 100644 index 0000000..6655426 --- /dev/null +++ b/doc/api/modebuf.txt @@ -0,0 +1,282 @@ +Generating and parsing channel mode strings is often a very +complicated process. The ModeBuf interface, along with the associated +mode parsing functions, attempt to make this much more programmatic. +The interface to the functions in this suite is itself very +complicated, unfortunately, though most of the complication is in the +effects of various flags on the operation of the functions. + + +struct ModeBuf; + +This structure is used to accumulate and describe several mode +changes. None of its fields are directly or indirectly accessible to +the application; a struct ModeBuf is only suitable for passing to the +modebuf_*() suite of functions. ModeBuf structures must be allocated +by the caller. + + + +void modebuf_init(struct ModeBuf *mbuf, struct Client *source, + struct Client *connect, struct Channel *chan, + unsigned int dest); + +This function initializes a caller-allocated ModeBuf, _mbuf_, with the +given parameters. If the mode should not be sent to a particular +server, perhaps because it was received from that server, that server +should be specified by the _connect_ parameter. The channel the mode +change will take place on is given by the _chan_ parameter, and the +disposition of the mode is given by the _dest_ parameter, which is the +binary OR of the MODEBUF_DEST_* flags described below. + + + +#define MODEBUF_DEST_CHANNEL 0x0001 /* Mode is flushed to channel */ + +This flag, when set in a call to modebuf_init(), causes the accumulated +mode change to be sent to the channel (in client<->server protocol, of +course). + + + +#define MODEBUF_DEST_SERVER 0x0002 /* Mode is flushed to server */ + +If other servers should be made aware of the mode change, this flag +should be passed to modebuf_init(). One time when the mode change may +not be passed is when processing the mode in a BURST message. + + + +#define MODEBUF_DEST_OPMODE 0x0100 /* Send server mode as OPMODE */ + +This flag is used to tell the modebuf_*() suite to send an OPMODE +message to other servers, rather than an ordinary MODE message. + + + +#define MODEBUF_DEST_DEOP 0x0200 /* Deop the offender */ + +When bouncing a mode change, giving this flag to modebuf_init() causes +the originating user to be deopped on the channel as part of the mode +bounce. + + + +#define MODEBUF_DEST_BOUNCE 0x0400 /* Bounce the modes */ + +When a mode change is illegitimate, that is, when it originates from a +user that is not (as far as this server knows) a channel operator, the +mode change should be bounced. This involves reversing the sense of +the mode and sending it back to the originating server. This flag is +used to tell the modebuf_*() suite to do just that. + + + +#define MODEBUF_DEST_LOG 0x0800 /* Log the mode changes to OPATH */ + +The OPMODE command is reserved for IRC operators. When it is used, +the server should log the command for accountability purposes. This +flag, given to modebuf_init(), will cause the ModeBuf system to log +the exact mode change to a log file. + + + +#define MODEBUF_DEST_HACK2 0x2000 /* Send a HACK(2) notice, reverse */ + +When a remote user that this server does not think is a channel +operator proceeds to change a channel mode, that mode must be +bounced. In addition, in order to provide some debugging capability, +a server notice may be sent, called a "HACK(2)" notice. Passing +modebuf_init() this flag causes that notice to be sent. + + + +#define MODEBUF_DEST_HACK3 0x4000 /* Send a HACK(3) notice, TS == 0 */ + +When the origin of a mode change is a server, we should always accept +the mode change. To provide accountability, however, a server notice +should be sent. This flag will cause the server to generate a +"HACK(3)" notice. + + + +#define MODEBUF_DEST_HACK4 0x8000 /* Send a HACK(4) notice, TS == 0 */ + +Some servers are special. When a server that has a U-line issues a +mode change, we send a "HACK(4)" message to differentiate it from an +ordinary server changing a channel mode. This is the flag that must +be passed to modebuf_init() to cause that behavior. + + + +void modebuf_mode(struct ModeBuf *mbuf, unsigned int mode); + +Certain channel modes take no arguments. Those mode changes can be +fed to the ModeBuf system using modebuf_mode(). The _mode_ parameter +is a bit mask of the mode changes, and must have one of MODE_ADD or +MODE_DEL set. + + + +void modebuf_mode_uint(struct ModeBuf *mbuf, unsigned int mode, + unsigned int uint); + +One channel mode, the "limit" mode ("+l"), takes a single integer +argument. This limit can be fed to the ModeBuf system with the +modebuf_mode_uint() function. The _mode_ parameter must be the binary +OR of one of MODE_ADD or MODE_DEL with the MODE_LIMIT flag. The +_uint_ parameter specifies the limit. + + + +void modebuf_mode_string(struct ModeBuf *mbuf, unsigned int mode, + char *string, int free); + +Some channel modes take a string parameter. These can be fed to +ModeBuf with modebuf_mode_string(). The _mode_ parameter should be +the binary OR of one of MODE_ADD or MODE_DEL with the flag for the +mode. The _string_ parameter specifies the string, and the _free_ +parameter indicates whether the ModeBuf system should call MyFree() on +the string once it is done with it. + + + +void modebuf_mode_client(struct ModeBuf *mbuf, unsigned int mode, + struct Client *client); + +The remaining channel modes take a parameter specifying a client. +These can be fed to ModeBuf with modebuf_mode_client(). The _mode_ +parameter should be the binary OR of one of MODE_ADD or MODE_DEL with +the flag for the mode. The _client_ parameter should be a pointer to +a struct Client specifying which client the mode is supposed to act +upon. + + + +int modebuf_flush(struct ModeBuf *mbuf); + +This function simply flushes the contents of the struct ModeBuf +specified by _mbuf_ to the appropriate destinations, as was specified +by the _dest_ parameter in the call to modebuf_init(). This function +returns 0 for the convenience of callers that must return an integer. + + + +void modebuf_extract(struct ModeBuf *mbuf, char *buf); + +One use of the ModeBuf within ircd requires the ability to pull a +simple mode string out of the struct ModeBuf for use elsewhere. This +can be accomplished with this function. The _buf_ parameter should be +large enough to accommodate the simple mode string. + + + +void mode_ban_invalidate(struct Channel *chan); + +Looking up bans affecting a particular user can be a fairly expensive +operation, so the server caches the result of the lookup. Should the +ban list for a channel change, all the cached results must be +invalidated to force rechecking. This may be done with the +mode_ban_invalidate() function, which acts upon the channel given by +_chan_. + + + +void mode_invite_clear(struct Channel *chan); + +When a channel that was invite-only has the "+i" channel mode removed, +the invite list that the server keeps is no longer necessary. The +mode_invite_clear() function flushes that invite list for the channel +given by _chan_, reclaiming the memory used by the invite list. + + + +int mode_parse(struct ModeBuf *mbuf, struct Client *cptr, struct Client *sptr, + struct Channel *chptr, int parc, char *parv[], + unsigned int flags); + +This function parses a mode change command, given by the contents of +_parv[]_, and under the control of _flags_. The channel being modified +is given by _chptr_, the source of the change is given by _sptr_, and +the connection the change was received from is given by _cptr_. The +_parc_ parameter gives the count of the number of elements in the +_parv[]_ array. The ModeBuf must have already been initialized by a +call to modebuf_init(), described above. For more information on +_flags_, see the MODE_PARSE_* macros described below. This function +returns an integer indicating the number of elements of _parv[]_ it +used. The modebuf_flush() function must be called upon return from +mode_parse() to flush the mode changes to the channel. + + + +#define MODE_PARSE_SET 0x01 /* actually set channel modes */ + +When this flag is passed to mode_parse(), the channel mode being +parsed will actually be effected on the channel. + + + +#define MODE_PARSE_STRICT 0x02 /* +m +n +t style not supported */ + +Users are permitted to send complicated mode commands like "MODE #foo ++m +n +t +k foo +i"; servers are not. Passing this flag to +mode_parse() causes it to strictly enforce this restriction. + + + +#define MODE_PARSE_FORCE 0x04 /* force the mode to be applied */ + +Some mode changes are not permitted under normal circumstances. When +this flag is passed to mode_parse(), these mode changes will be +accepted. + + + +#define MODE_PARSE_BOUNCE 0x08 /* we will be bouncing the modes */ + +This flag warns mode_parse() that the mode is to be bounced. This +will cause it to systematically feed each mode into ModeBuf in order +for that interface to generate the proper bounce messages. + + + +#define MODE_PARSE_NOTOPER 0x10 /* send "not chanop" to user */ + +This flag is used to warn mode_parse() that the user generating the +mode change is not a channel operator. If the user attempts to change +a mode, an appropriate error message will be sent to the user (once). + + + +#define MODE_PARSE_NOTMEMBER 0x20 /* send "not member" to user */ + +This flag is used to warn mode_parse() that the user generating the +mode change is not even on the channel. If the user attempts to +change a mode, an appropriate error message will be sent to the user +(once). + + + +#define MODE_PARSE_WIPEOUT 0x40 /* wipe out +k and +l during burst */ + +When this flag is passed to mode_parse(), the channel key and limit +will be reversed if the mode string doesn't update them. This is used +for processing BURST messages. + + + +#define MODE_PARSE_BURST 0x80 /* be even more strict w/extra args */ + +The BURST message is even more strict than a standard MODE message. +Processing *must* stop after reading the mode string itself, or +mode_parse() could gobble up arguments not intended for it. This flag +tells mode_parse() about this restriction. + + + +Kev + + + +[2001-6-15 Kev] Initial documentation of the ModeBuf and mode parsing +subsystems. + -- 2.20.1