Merge branch 'u2_10_12_branch' of git://git.code.sf.net/p/undernet-ircu/ircu2

[ircu2.10.12-pk.git] / doc / api / motd.txt

diff --git a/doc/api/motd.txt b/doc/api/motd.txt
new file mode 100644 (file)
index 0000000..d491162
--- /dev/null
+++ b/doc/api/motd.txt
@@ -0,0 +1,73 @@
+The server has a Message of the Day (MOTD) which is often used for
+describing the Acceptable Usage Policy, where to get help if you have
+problems, and so on.  Older versions of ircd had a lot of duplicated
+code, as well as some inefficiencies, all related to sending the
+MOTD.  As of u2.10.11, there is an API specifically for MOTDs.  This
+API caches the MOTDs in memory for efficiency.  Sending a MOTD to a
+client is as simple as calling a single function.
+
+<function>
+void motd_init(void);
+
+This function initializes the MOTD subsystem.  It will also read in
+the default MOTD (usually ircd.motd) and the remote MOTD (usually
+remote.motd) files.
+</function>
+
+<function>
+int motd_send(struct Client* cptr);
+
+This function sends an appropriate MOTD to the client specified by
+_cptr_.  If _cptr_ is not a local client, the remote MOTD will be
+sent; otherwise, an attempt will be made to find a Motd entry in the
+configuration file that matches the client.  If no Motd entry can be
+found, the default MOTD will be sent to the client.  This function
+returns 0 for the convenience of other functions that must have an
+integer return value.  </function>
+
+<function>
+void motd_signon(struct Client* cptr);
+
+This function is similar to motd_send(), described above, except that
+it will only send a message to the client indicating when the MOTD was
+last modified if the FEAT_NODEFAULTMOTD feature is set to TRUE.
+</function>
+
+<function>
+void motd_recache(void);
+
+The MOTD system will not automatically detect when MOTD files have
+been modified.  This function causes the MOTD system to clear the MOTD
+cache and re-read the files.
+</function>
+
+<function>
+void motd_add(const char *hostmask, const char *path);
+
+This function is used to add a MOTD to be sent to clients possessing a
+given _hostmask_.  If _hostmask_ is a numerical string, it is
+interpreted as a connection class.
+</function>
+
+<function>
+void motd_clear(void);
+
+This function clears the list of special MOTDs.  Only the default MOTD
+and remote MOTD are not affected by this function.
+</function>
+
+<function>
+void motd_report(struct Client *to);
+
+The motd_report() function sends a list of the Motd entries stored in
+memory to the client specified by _to_.  Access control should be
+handled by the caller.
+</function>
+
+<authors>
+Kev <klmitch@mit.edu>
+</authors>
+
+<changelog>
+[2001-6-15 Kev] Initial documentation of the MOTD interface.
+</changelog>