* Updated some of the docs. Bumped version number to 5.80 in anticipation

[citadel.git] / citadel / techdoc / session.txt

diff --git a/citadel/techdoc/session.txt b/citadel/techdoc/session.txt
index 8a5d1eb6aa5dc33fa94f64bec3f2531a6e13934c..4007dc176b4f0107a84b3bd84ba12838a41f9c3f 100644 (file)
--- a/citadel/techdoc/session.txt
+++ b/citadel/techdoc/session.txt
@@ -1,5 +1,5 @@
                   SESSION LAYER PROTOCOL FOR CITADEL/UX
-         (c) 1995-2000 by Art Cancro et. al.    All Rights Reserved
+         (c) 1995-2001 by Art Cancro et. al.    All Rights Reserved
    
   
  INTRODUCTION
@@ -24,7 +24,7 @@ developments ahead of time, please at least send in an e-mail documenting
 what you did, so that your new commands can be added to this document.
  
  The coordinator of the Citadel/UX project is Art Cancro
-<ajc@uncnsrd.mt-kisco.ny.us>.
+<ajc@uncensored.citadel.org>.
     
   
  CONNECTING TO A SERVER
@@ -548,7 +548,7 @@ proprietary features:
 your own.
  -> Clients other than your own should still be able to utilize your server,
 even if your proprietary extensions aren't supported.
- -> Please contact Art Cancro <ajc@uncnsrd.mt-kisco.ny.us> and obtain a unique
+ -> Please contact Art Cancro <ajc@uncensored.citadel.org> and obtain a unique
 server type code, which can be assigned to your server program.
  -> If you document what you did in detail, perhaps it can be added to a
 future release of the Citadel/UX program, so everyone can enjoy it.  Better
@@ -575,12 +575,13 @@ length of the file, and a description.
  
  The server message contained on the same line with LISTING_FOLLOWS will
 contain the name of the system and the name of the directory, such as:
-  uncnsrd.mt-kisco.ny.us|/usr/bbs/files/my_room_directory
+  uncensored.citadel.org|/usr/bbs/files/my_room_directory
  
  
  SLRP   (Set Last-message-Read Pointer)
  
- This command is used to mark messages as having been read.  Its sole parameter
+ This command marks all messages in the current room as read (seen) up to and
+including the specified number.  Its sole parameter
 is the number of the last message that has been read.  This allows the pointer
 to be set at any arbitrary point in the room.  Optionally, the parameter
 "highest" may be used instead of a message number, to set the pointer to the
@@ -1411,9 +1412,14 @@ ERROR codes if it fails.
  
  Receive from the server a named user's bio.  This command should be passed
 a single argument - the name of the user whose bio is requested.  RBIO returns
-LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file,
-ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND
-if the user exists but has no bio on file.
+LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file.
+The return has the following parameters:  the user name, user number, access
+level, date of last call, times called, and messages posted.  This command
+returns ERROR+NO_SUCH_USER if the named user does not exist.
+
+ RBIO no longer considers a user with no bio on file to be an error condition.
+It now returns a message saying the user has no bio on file as the text of the
+bio.  This allows newer servers to operate with older clients.
   
   
  STEL   (enter STEaLth mode)
@@ -1819,7 +1825,22 @@ issue a REQT command, then wait a little while (from 30 seconds up to a few
 minutes) for well-behaved clients to voluntarily terminate, and then issue a
 TERM command to forcibly disconnect the client (or perhaps a DOWN command, if
 you are logging off users for the purpose of shutting down the server).
-    
+ 
+ 
+ SEEN   (set or clear the SEEN flag for a message)
+ 
+ Beginning with version 5.80, Citadel supports the concept of setting or
+clearing the "seen" flag for each individual message, instead of only allowing
+a "last seen" pointer.  In fact, the old semantics are implemented in terms
+of the new semantics.  This command requires two arguments: the number of the
+message to be set, and a 1 or 0 to set or clear the "seen" bit.
+ 
+ This command returns OK, unless the user is not logged in or a usage error
+occurred, in which case it returns ERROR.  Please note that no checking is
+done on the supplied data; if the requested message does not exist, the SEEN
+command simply returns OK without doing anything.
+  
+   
   
  ASYN   (ASYNchronous message support)
  
@@ -1837,3 +1858,21 @@ server to output its current state without changing it.
  
  When asynchronous protocol mode is in effect, the client MUST handle any
 asynchronous messages as they arrive, before doing anything else.
+   
+ 
+ 
+   
+ ASYNCHRONOUS MESSAGES
+ ---------------------
+ 
+ When the client protocol is operating in asynchronous mode (please refer to
+the writeup of the ASYN command above), the following messages may arrive at
+any time:
+  
+ 
+ 901  (express message arriving)
+ 
+ There is an express message intended for this client.  When the client
+receives this message, it MUST act as if it just sent a GEXP command (the data
+following the 901 message WILL be a LISTING_FOLLOWS data transfer; in fact,
+the current implementation simply executes a GEXP command internally).