Commit ef07d126 authored by David Byers's avatar David Byers

New documentation, doc changes

parent f5143ec6
# $Id: Makefile.am,v 1.6 1998/12/30 17:39:29 byers Exp $
# $Id: Makefile.am,v 1.7 1999/01/07 15:10:32 byers Exp $
# Copyright (C) 1998 Lysator Academic Computer Association.
#
# This file is part of the LysKOM server.
......@@ -24,7 +24,7 @@
SUBDIRS = man
info_TEXINFOS = Protocol-A.texi lyskomd.texi
info_TEXINFOS = Protocol-A.texi lyskomd.texi dbck.texi lyskomdb.texi hacking.texi
EXTRA_DIST = ADMINISTRATION misc_items prot-A.txt \
server-async.extend server.extend what-is-unread.swe \
......
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.47 1998/12/30 17:39:30 byers Exp $
@c
@c FIXME: Explain how the garb works with nice and keep-commented
@c
@c $Id: Protocol-A.texi,v 1.48 1999/01/07 15:10:33 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -188,6 +191,7 @@ Lars Aronsson documented the protocol that was in use at the time.
@item 101=get-members
@item 102=local-to-global
@item 103=map-created-texts
@item 105=set-keep-commented
@end itemize
@item Removed Server Calls
......@@ -1801,6 +1805,7 @@ conferences based on their names.
super-conf : Conf-No;
msg-of-day : Text-No;
nice : Garb-Nice;
keep-commented : Garb-Nice;
no-of-members : INT16;
first-local-no : Local-Text-No;
no-of-texts : INT32;
......@@ -1855,6 +1860,9 @@ The conference notice, if any.
@item nice
The number of days an article should be kept before being removed from
the conference.
@item keep-commented
A text that has comments no older than this number of days will not be
removed from the conference.
@item no-of-members
The number of members of this conference.
@item first-local-no
......@@ -2813,6 +2821,7 @@ in the example.
* set-membership-type:: Modify the type of conference (102)
* local-to-global:: Map local text numbers to global ones (103)
* map-created-texts:: Map texts created by a person to glogal (104)
* set-keep-commented:: Set how new comments protect old texts (105)
@end menu
@iftex
......@@ -7252,7 +7261,7 @@ Login required before issuing this call.
@end table
@node map-created-texts, , local-to-global, Protocol Requests
@node map-created-texts, set-keep-commented, local-to-global, Protocol Requests
@subsection map-created-texts (10) Recommended
@findex map-created-texts
......@@ -7277,6 +7286,34 @@ Login required before issuing this call.
@end table
@node set-keep-commented, , map-created-texts, Protocol Requests
@subsection set-keep-commented (10) Recommended
@findex set-keep-commented
@example
set-keep-commented [105] (( conf-no : Conf-No;
keep-commented : Garb-Nice; ))
-> ( );
@end example
Sets the @code{keep-commented} field of the conference @code{conf-no} to
@code{keep-commented}. This call can only be issued by a conference's
supervisor or a privileged user.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @code{conf-no} does not exist or is secret.
@item permission-denied
Not supervisor of conference @code{conf-no} and not privileged enough to
complete the call anyway.
@end table
@node Asynchronous Messages, , , Top
@chapter Asynchronous Messages
......
\input texinfo
@c $Id: hacking.texi,v 1.1 1999/01/07 15:10:38 byers Exp $
@c %**start of header
@setfilename hacking.info
@settitle "Hacking lyskomd"
@setchapternewpage odd
@c %**end of header
@ifinfo
This is a guide to hacking lyskomd.
Copyright @copyright{} 1999 Lysator ACS.
Permission is granted to make and distribute verbatim copies of this
specification provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo
@dircategory LysKOM
@direntry
* Hacking lyskomd: (hacking). How to hack lyskomd.
@end direntry
@titlepage
@sp 10
@title "Hacking lyskomd"
@sp 2
@subtitle "How to extend, modify and generally mess up lyskomd"
@sp 2
@author by the lyskomd developers
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995-1999 Lysator ACS
Permission is granted to make and distribute verbatim copies of this document
provided the copyright notice and this permission notice are preserved on all
copies.
Modified versions of this document may be redistributed with the added
condition that all modifications not cleared with the LysKOM development group
are clearly marked and that the entire modified work be redistributed under the
same conditions as the original.
Permission is granted to copy and distribute translations of this manual into
another language under the same conditions as for modified versions.
@end titlepage
@ifinfo
@node Top, Adding Asynchronous Message, (dir), (dir)
@comment node-name, next, previous, up
@top Hacking lyskomd
@menu
* Adding Asynchronous Message::
* Adding Configuration Parameters to the Server:: How to add config params.
* Adding a New Protocol Request:: How to extend protocol A.
* Adding Aux-Item Types::
* Modifying an Existing Type::
@end menu
@end ifinfo
@node Adding Asynchronous Message, Adding Configuration Parameters to the Server, Top, Top
@comment node-name, next, previous, up
@chapter Adding Asynchronous Messages
@table @code
@item async.h
Add the message in @code{typedef enum @{ @} Async}. Make sure that
@code{ay_dummy_last} is one more than any other message. If the message
is to be sent by default, which is @i{not} recommended, place its number
info @code{ASYNC_DEFAULT_MESSAGES}.
@item prot-a-send-async.c
@item prot-a-send-async.h
Write a function that sends the message. This function is responsible
for writing the message to a particular connection and for ensuring that
the message is not sent to clients who do not want it. Make sure that
the second argument to @code{async_header} really is the number of
elements being sent. Arrays count as two elements: the item count and
the elements.
@item send-async.c
@item send-async.h
Write a function that sends the message to appropriate clients. This
function is responsible for checking that async messages should be sent
at all, for each client check if it allowed to see the message and
ensure that the protocol specified by the connection is appropriate. The
send function should either take a @code{struct connection *} as an
argument and send the message to that connection, or loop over all
connections. Most send functions take a connection pointer; the looping
is dealt with elsewhere.
@item Make sure that the message is sent in appropriate places.
@item Document the message type in @code{Protocol-A.texi}.
@end table
@menu
* Function Templates for prot-a-send-async.c::
* Function Templates for send-async.c::
@end menu
@node Function Templates for prot-a-send-async.c, Function Templates for send-async.c, Adding Asynchronous Message, Adding Asynchronous Message
@comment node-name, next, previous, up
@section Function Templates for prot-a-send-async.c
This is what a typical function in @code{prot-a-send-async.c} should
look like. This function is responsible for checking that the client is
accepting the message and writing the message itself to the connection.
@example
void
prot_a_async_@i{something}(Connection *cptr,
@i{parameters})
@{
ASYNC_CHECK_ACCEPT(cptr, ay_@i{something});
async_header(cptr, @i{num_tokens}, ay_@i{something});
/* Output the body of the message */
async_trailer(cptr);
@}
@end example
@node Function Templates for send-async.c, , Function Templates for prot-a-send-async.c, Adding Asynchronous Message
@comment node-name, next, previous, up
@section Function Templates for send-async.h
This is what a typical function in @code{send-async.c} should look like.
This function is responsible for sending the message to all connections
that are appropriate, not sending it if the server is not supposed to
send messages at all, and for checking that the protocol specified by
the client is one the server knows.
@example
void async_@i{something}( @i{parameters} )
@{
Connection *cptr;
Session_no i = 0;
if (!param.send_async_messages)
return;
while ((i = traverse_connections(i)) != 0)
@{
cptr = get_conn_by_number(i);
switch(cptr->protocol)
@{
case 0:
/* No protocol specified yet */
break;
case 'A':
/* Check that connection is logged on. We might
want to check other things here too, such as
if the connection is allowed to see the message */
if (cptr->username_valid == TRUE)
prot_a_async_@i{something}(cptr, @i{parameters});
break;
default:
restart_kom("async_@i{something}(): bad protocol.\n");
break;
@}
@}
@}
@end example
Template for a function that sends to a single connection:
@example
void async_@i{something}(struct connection *cptr,
@i{parameters})
@{
if (!param.send_async_messages)
return;
switch(cptr->protocol)
@{
case 0:
/* No protocol specified yet */
break;
case 'A':
/* Check that connection is logged on. We might
want to check other things here too, such as
if the connection is allowed to see the message */
if (cptr->username_valid == TRUE)
prot_a_async_@i{something}(cptr, @i{parameters});
break;
default:
restart_kom("async_@i{something}(): bad protocol.\n");
break;
@}
@}
@end example
@node Adding Configuration Parameters to the Server, Adding a New Protocol Request, Adding Asynchronous Message, Top
@comment node-name, next, previous, up
@chapter
Make sure that you really understand what you want to configure. Think
it over again. Find a good, descriptive name for it.
Decide what values the parameter can be set to. Integers? Booleans?
Document the parameter in @code{lyskomd.texi}.
Add a field to @code{stuct kom_par} in @code{param.h}.
Add it to @code{parameters[]} in @code{server-config.c}. See
@code{conf-file.h} and maybe @code{conf-file.c} for information on this
structure.
Make sure that the parameter is used instead of any previous hard-coded
value. Make sure that @code{dbck} can cope with it.
@node Adding a New Protocol Request, Adding Aux-Item Types, Adding Configuration Parameters to the Server, Top
@comment node-name, next, previous, up
@chapter Adding a New Protocol Request
Before doing anything, think again. Make sure that the protocol request
is needed, is in line with the rest of the protocol, behaves the way
people want it to, and that everyone involved agrees that it is a good
idea.
@enumerate
@item Document the request in @code{Protocol-A.texi}
@item Declare the function in @code{include/services.h}
@item Declare the function @i{last} in @code{server/fncdef.txt}
@item If the function takes a pn input parameter of a new type, changes
need to be made in several places. @xref{Adding New Input Types}.
@item If the function takes too many parameters of type @code{num},
@code{string} or @code{c_string}, the definition of @code{Connection} in
@code{server/connection.h} has to be changed.
@item If the function has an output parameter of a new type, changes
need to be made in several plaves. @xref{Adding New Result Types}.
@item Write the function in a suitable place in the server directory.
@item Add the function to @code{prot_a_is_legal_fnc} in
@code{server/prot-a.c}
@item Write tests for the new function in
@code{server/testsuite/lyskomd.0}. Write one file for testing the
functionality. Write tests in @code{01.exp} (behavior when the client is
not logged on) and @code{03.exp} (normal behavior.)
@item Run the testsuite to make sure nothing old has been broken.
@end enumerate
@menu
* Adding New Input Types:: Procedure for adding input types.
* Adding New Result Types:: Procedure for adding output types.
@end menu
@node Adding New Input Types, Adding New Result Types, Adding a New Protocol Request, Adding a New Protocol Request
@comment node-name, next, previous, up
@section Adding New Input Types
Changes need to be made in the following files:
@table @code
@item Protocol-A.texi
Document the new type.
@item server/call-switch.awk
The new type has to be added to the cascaded ifs that translate the type
name to code that points to the appropriate field in a
@code{Connection} structure.
@item server/prot-a-parse-arg-c.awk
The new type has to be added to the cascaded ifs that create the
argument list parser.
@item server/connections.h
The definition of @code{Connection} must be extended with a field where
the parse value can be stored. Don't even think about trying to reuse an
existing field. It's more trouble than it's worth.
@item server/connection.c
Free the contents of the field in @code{free_parsed()}.
@item server/internal-connections.c
Initialize the contents of the field in @code{init_connection()}.
@end table
@node Adding New Result Types, , Adding New Input Types, Adding a New Protocol Request
@comment node-name, next, previous, up
@section Adding New Result Types
Changes need to be made in the following files:
@table @code
@item Protocol-A.texi
Document the new type.
@item server/prot-a.c
Add a line in the @code{prot_a_reply} switch that calls the correct
output function.
@item server/connections.h
Add the type in @code{Res_type}and @code{Result_holder}.
@item server/prot-a-output.c
@item server/prot-a-output.h
Write a function that outputs the new type
to a connection. Use the existing functions as templates.
@end table
@node Adding Aux-Item Types, Modifying an Existing Type, Adding a New Protocol Request, Top
@comment node-name, next, previous, up
@chapter Adding Aux-Item Types
@enumerate
@item Document the new type in Protocol-A.texi
@item Write a definition of the new type in
@code{run-support/aux-items.conf}.
@item Write test cases for the new type in
@code{server/testsuite/lyskomd.0/03.exp}.
@item If the new type requires add, delete or undelete triggers that do
not already exist, declare the trigger functions in @code{aux-items.c}
and add them to the @code{aux_item_triggers} array in the same file.
@item If the new type is so complex that is cannot be fully defined in
@code{aux-items.conf}, then add it to the @code{compiled_aux_items}
array in @code{aux-items.c}. Note that this functionality has not been
tested until someone actually adds one of these beasts, so watch your
step.
@end enumerate
@node Modifying an Existing Type, , Adding Aux-Item Types, Top
@comment node-name, next, previous, up
@chapter Modifying an Existing Type
If you want to modify an existing type that is stored in the database,
think again. Can the job be done with aux-items instead? Is it really
necessary?
Be very, very careful when doing this. You have to make sure that the
type as sent in old calls and async messages is not changed in any way.
You have to make sure that the type can be stored to and read from the
database.
@enumerate
@item Document the changes in Protocol-A.texi if the change is visible
in the protocol.
@item Bump the database version number by one for the next release of
the server.
@item Write a function in @code{ram-output.c} to output the new format.
Update all old functions in @code{ram-output.c} that are database
version dependent so that they can deal with the new database format.
@item Write a function in @code{ram-parse.c} to read the new format.
Update all old functions in @code{ram-parse.c} that are database version
dependent so that they can deal with the new database format.
@item Set the default database format in @code{ram-parse.c} and
@code{ram-output.c}. The variables to change are @code{input_format} and
@code{output_format}, respectively.
@end enumerate
@menu
* Template for ram-output.c::
* Template for ram-parse.c::
@end menu
@node Template for ram-output.c, Template for ram-parse.c, Modifying an Existing Type, Modifying an Existing Type
@comment node-name, next, previous, up
@section Template for ram-output.c
For types that can be output in several different formats, use the
following templates for them. You have to be able to output in all
formats, or @code{dbck} will be unable to convert between formats.
@example
static void
foutput_@i{something}_0(FILE *fp, @i{something} *o)
@{
/* Output version 0 of @i{something} */
@}
static void
foutput_@i{something}_1(FILE *fp, @i{something} *o)
@{
/* Output version 1 of @i{something} */
@}
static void
foutput_info_2(FILE *fp, @i{something} *o)
@{
/* Output version 2 of @i{something} */
@}
void foutput_@i{something}(FILE *fp, @i{something} *o)
@{
switch(output_format)
@{
case 0:
foutput_@i{something}_0(fp, info);
break;
case 1:
foutput_@i{something}_1(fp, info);
break;
case 2:
foutput_@i{something}_2(fp, info);
break;
default:
restart_kom("unknown database format: %d", output_format);
break;
@}
@}
@end example
Note that if two versions are the same, only write one functions. For
example, if version 0 and version 1 are the same, only write an
@code{foutput_@i{something}_0} function and call it from both case 0 and
case 1.
@node Template for ram-parse.c, , Template for ram-output.c, Modifying an Existing Type
@comment node-name, next, previous, up
@section Template for ram-parse.c
@example
static Success
fparse_@i{something}_0(FILE *fp, @i{something} *o)
@{
/* Parse version 0 */
return OK;
@}
static Success
fparse_@i{something}_1(FILE *fp, @i{something} *o)
@{
/* Parse verson 1 */
return OK;
@}
static Success
fparse_@i{something}_2(FILE *fp, @i{something} *o)
@{
/* Parse verson 2 */
return OK;
@}
extern Success
fparse_@i{something}(FILE *fp, @i{something} *o)
@{
if ( fparse_long_errors != 0 )
@{
log("fparse_info(): fparse_long_errors == %d on entry. Reset.\n",
fparse_long_errors);
fparse_long_errors = 0;
@}
switch (input_format)
@{
case 0:
return fparse_@i{something}_0(fp, o);
break;
case 1:
return fparse_@i{something}_1(fp, o);
break;
case 2:
return fparse_@i{something}_2(fp, o);
break;
default:
restart_kom("unknown input format: %d\n", input_format);
return FAILURE;
break;
@}
@}
@end example
Note that if two versions are the same, only write one functions. For
example, if version 0 and version 1 are the same, only write an
@code{fparse_@i{something}_0} function and call it from both case 0 and
case 1.
@bye
\input texinfo
@c $Id: lyskomd.texi,v 1.1 1998/12/30 12:50:47 byers Exp $
@c $Id: lyskomd.texi,v 1.2 1999/01/07 15:10:39 byers Exp $
@c %**start of header
@setfilename lyskomd.info
@settitle "lyskomd Reference Manual"
......@@ -442,6 +442,12 @@ counted in days, and can be set for each conference by the administrator
of the conference. This is the default value assigned to new
conferences. Default is 77 days.
@item Default keep commented nice: int
A text will not be removed if it has comments newer than a certain
number of days. This number can be set for each conference. This
parameter specifies the default value for that number of days. The
default is 77.
@item Max client transmit queue: int
Mux number of pending data blocks in the reply queue to a client. If
there is ever more than this many data blocks in the queue the client
......
\input texinfo
@c $Id: lyskomdb.texi,v 1.1 1999/01/07 15:10:40 byers Exp $
@c %**start of header
@setfilename lyskomdb.info
@settitle "lyskomd Database Format Specification"
@setchapternewpage odd
@c %**end of header
@iftex
@parindent 0pt
@begin tex
\global\def\BB#1{\b{#1}}
\global\def\II#1{\i{#1}}
@end tex
@end iftex
@ifinfo
@macro BB {text}
'\text\'
@end macro
@macro II {text}
/\text\/
@end macro
@end ifinfo
@ifinfo
This is the specification for the lyskomd database format.
Copyright @copyright{} 1999 Lysator ACS.