
 General packet format:

ID no Data
%%%%% ...

Key:

  Certain abbreviation and symbols are used to mean certain things.

  {DGA} = Discussion, Group or Application
  {CUDGA} = Cloverid, User, Discussion, Group, or Application
  | denotes the beggining of the comment on a packet.
  
Numbers:

  All numbers that are sent are first converted into a "long" integer
(four bytes).  [If the value is a floating point, then it has to be
sent as text.]  The long is then converted to five base 85 digits
for trasmission purposes.  For example

0x0000 0000 would be converted to !!!!!
0x0000 0001 would be converted to "!!!!
0x00F0 F001 would be converted to nyU;!

  Routines for conversion are available in lts.c.  You don't need to 
understand the process, just to use it.

Packet Numbers:

  The packet numbering scheme is very devios, and each digit has a meaning.
The first four digits describe the command type of the packet.

Digit 1: This digit is 0 for user packets, 1 for server packets and so on
Digit 2: This digit is always 0, so far.
Digit 3: This digit has five possible values for client packets.
         1 - The packet is one that retrieves information
         2 - The packet deals with joining, creating and so on with {DGA}
         3 - The packet is for manipulating data on {CUDGA}'s
         4 - The packet is for sending information
         F - The packet deals with connection/disconnection
Digit 4: This digit is a counter, with little meaning except to tell one
         packet from another.

The last four digits describe the packets function within a given command
type.

Digit 1: If it's a 0, it is a packet being sent.  If it is an 8, it is
         a responce packet, and if it is 9-F, it is an error packet.
Digit 2: If it is a 0, it is a single standalone packet
         If it is a 1, it is the first through last packet of a sequence.
         if it is a 2, it signals the end of a group of packets.
Digit 3: This is a place counter to tell one packet from another.
Digit 4: This determines what the packet will function on.
         1 means it functions on Cloverids
         2 means it functions on Users
         3 means it functions on Discussions
         4 means it functions on Groups
         5 means it functions on Applications
         0 mens that none of the above are applicable.
         
Text:

  For ease of use and debugging (and because I like it) pascal style
strings are used.  This means that the length of the string is stored
as the first two digits of the strings, encoded base 85.  For example

!*Fredrick

 Is a valid string.  !* translates to 8, and "Fredrick" is eight 
characters long.  This way when the packet is recieved and decoded, you
can tell where each string starts and ends, and strings can have varying
lengths up to 7K (there are more restrictions in the transport layer however.)
For convention purposes, a null string is two characters, zero base 85:

!!

Responses: 

  Not all packets deserve (recieve) a responce.  If there is any possibility
of an error occuring then some responce is given.  If there was no error
the responce is usually the data requested, or confirmation that the data
sent was recieved.  The responce packets (that are not errors) can be
seen below, as they are the packets that have an eight in their fifth
hexidecimal digit.  For example the packet for announcements

0042 0002 flags time text | send mesage text with flags

has a responce packet

0042 8002 | announce ok

which is sent if the announcement was process correctly without error.

Errors:

  When a packet cannot be preformed upon as requested an error code is
generated and sent back to the client.  Most errors are of a fairly
common nature, and theese errors have been given their own hexidecimal
code.  The way it works is that the packet nuber's 5th hexidecimal digit
(which is always 0 to start out with) is replaced by the error code digit
and that packet number is sent back.  For example:

(0011 0001) !*Fredrick

would recieve in return

(0011 B001)

if there was no user with the word "Fredrick" in their name.  [() means
that the number has been converted to base 85.]  There are also errors
that are specific to packets, and they have an error code of 9, and 
have text that is sent with them to describe the particular error.

Error Codes
9 - Specific error with accompanying text. Listed seperatly.
A - Permission Denied
B - No such item available
C - Name Conflict
D - Text Too long for destination
E - User not logged in enough for command in question
F - Packet was malformed.  All packets can be malformed. Not listed


Format: The packet number is listed in hex, it must be converted into
        base 85.  Text for type 9 errors are listed in quotes, the
        quotes need to be removed, and the string length appended to the
        beginning.

0011: 
  Below are the commands for listing information from the server's database.
You send a name to be matched over a particular table, and it returns
several packets describing the people who matched that name.  If the name
sent is a null string, then the server returns everything in that table.

Error codes:
  A Means that the user has no permission to search that table.
  B Means no users match that name

0011 0001 name | name is a txt field to be matched over Clover Id's
0011 8101 CID name defname uname machine type flags    | first-last
0011 8201      | End of list packet
Errors: AB

0011 0011 name | name is txt field to be matched over Clover Id default name
0011 8111 CID name defname uname machine type flags    | first-last
0011 8211      | End of list packet
Errors: AB

:&&:
0012:
  These packets retrieve a list of reference number of people who belong
to a {DGA}.  It returns in one packet a list of user reference numbers.

Error codes:
  A Means that the user has no permission to search that {DGA}
  B Means no {DGA} with the reference number given exists.

Errors:
0012 0003 DID | refno of discussion to get membership list for
0012 8003 DID UID [UID ...] | Numbers of users in the discussion
Errors: AB

0012 0012 UID | refno of user to get user's status to
0012 8012 UID UID flags [UID flags....] | data returned
Errors: AB
a
0012 0013 DID | refno of disc to get user's perms to 
0012 8013 DID UID flags [UID flags....] | data returned
Errors: AB

:&&:
0013:
  This function retrieves data about a particular {CUDGA} by its
reference number.  The data sent depends on what the reference number
refers to.

Error codes:
  A Means that the user has no permission to get data on that {CUDGA}
  B Means no {CUDGA} with the reference number given exists.

0013 0001 CID | refno of sysid to get data on
0013 8001 CID name defname uname machine flags
Errors: AB

0013 0012 UID UID | refno of user to user's status to
0013 8012 UID UID flags
Errors: AB

0013 0013 DID UID | refno of discussion to user's perms to.
0013 8013 DID UID flags
Errors: AB

:&&:
0015:
  This function gets the info file for the given {CUDGA}.

Error codes:
  9 There is no info file associate with the given {CUDGA}.
  B Means no {CUDGA} with the reference number given exists.

0015 0000 refno | Get info on systemid refno
0015 8100 text  | first to last packet
0015 8200       | End of list packet
0015 9100 "No info file available"
Errors:  B

:&&:
0021:
  This type requests that a {DGA} be created/run with the data give.

Error codes:
  9 The person has too man {DGA}'s already.
  A Means that the user is not allowed to create discussions
  C Means that there is alread a {DG} with that name in existance.
  D Means that The name or title give for the {DG} was too long
  E Means that the user isn't logged into the system yet.

0021 0003 flags name title | Creates a discussion with data as listed
0021 8003                  | created
0021 9003 "Too many discusions owned already"
Errors: A  CDE

:&&:
0022:
  This packet type is for joining a particular {DGA}.

Error codes:
  9 Is for if the user already belongs to the particular {DGA}
  A Means that the user has no permission to join that {DGA}
  B Means no {DGA} with the reference number given exists.
  E Means that the user isn't logged into the system yet.

0022 0003 DID   | Join the discussion with given number
0022 8003       | Join ok
     9003 "Already a Member"
Errors: AB  E

:&&:
0023:
  These packets are for leaving a particular {DGA}

Error codes:
  9 Is used when the user is not a member of the {DGA}
  B Means no {DGA} with the reference number given exists.
  E Means that the user isn't logged into the system yet.

0023 0003 DID | Leave the discussion with given number
0023 8003     | Leave ok
     9003 "Not currently a member"
Errors: B  E

:&&:
0024:
  This set of packets is for destroying/stoping {DGA}'s

Error codes:
  A Means that the user has no permission to destroy that {DGA}
  B Means no {DGA} with the reference number given exists.

0024 0003 DID | Destroy the discussion with the given number
0024 8003     | dest ok
Errors: AB

:&&:
0025:
  This set of packets is for removing a user from a {DGA}

Error codes:
  9 is used when the given user doesn't exist.
  A Means that the user has no permission to remove people from that {DGA}
  B Means no {DGA} with the reference number given exists.

0025 0003 DID UID offflags | Remove user uref from disc refno
0025 8003 DID UID offflags | remove ok
     9003 "No such user" "Not a Member"
Errors: AB

:&&:
0026:
  This set of packets is used to claim a {DGA}'s ownership.

Error codes:
  9 Too many discussions are owned by this CID
  A Means that the user has no permission to claim that {DGA}
  B Means no {DGA} with the reference number given exists.
  E Means that the user isn't logged into the system yet.

0026 0003 DID | Claim discussion refno
0026 8003     | claim ok
0026 9003 "Too Many Discussions Owned"
Errors: AB  E

:&&:
0032:
  This function is for changing the blurb/title of a particular {UDGA}.

Error codes:
  A Means that the user has no permission to chang the title on that {DGA}
  B Means no {DGA} with the reference number given exists.
  D Means that The name or title give for the {UDGA} was too long
  E Means that the user isn't logged into the system yet.

0032 0002 blurb | text field containing blurb to be set
0032 8002 | Blurb fine  
Errors:    DE

0032 0003 DID title   | text field containing title to be set for disc
0032 8003             | Title fine  
Errors: AB DE

:&&:
0031:
  This function is for changing the name of a particular {UDGA}.

Error codes:
  A Means that the user has no permission to chang the title on that {DGA}
  B Means no {DGA} with the reference number given exists.
  D Means that The name or title give for the {UDGA} was too long
  E Means that the user isn't logged into the system yet.

0031 0002 name | text field containing name to be set
0031 8002 | Name fine  
Errors:    DE

0031 0003 DID name   | text field containing name to be set for disc
0031 8003            | name fine  
Errors: AB DE

:&&:
0035:
  This set of packets is for setting the permissions for one user relative
to a particular {DGA}.

Error codes:
  9 Is used when the user being permitted doesn't exist, or flags are wrong.
  A Means that the user has no permission to set permissions on that {DGA}
  B Means no {UDGA} with the reference number given exists.

0035 0002 UID flags | Flags to be set on relative to user UID
0035 8002 UID flags | perm ok
0035 9002 "Illegal flags" "Flags Unchanged"
Errors: B

0035 0003 DID UID flags | Perm for disc refno for user to be set on
0035 8003 DID UID flags | perm ok
0035 9003 "No such user" "Illegal flags" "Flags Unchanged"
Errors: AB

0035 0012 UID flags | Flags to be set off relative to user UID
0035 8012 UID flags | perm ok
0035 9012 "Illegal flags" "Flags Unchanged"
Errors: B

0035 0013 DID UID flags | Perm for disc refno for user to be set off
0035 8013 DID UID flags | perm ok
0035 9013 "No such user" "Illegal flags" "Flags Unchanged"
Errors: AB

0035 0022 UID flags | Flags to be reset relative to user UID
0035 8022 UID flags | perm ok
0035 9022 "Illegal flags" "Flags Unchanged"
Errors: B

0035 0023 DID UID flags | Perm for disc refno for user to be reset
0035 8023 DID UID flags | perm ok
0035 9023 "No such user" "Illegal flags" "Flags Unchanged"
Errors: AB

:&&:
0036:
  This set of packets is for setting the flags (including the permission
flags) for a {CUDGA}.

Error codes:
  A Means that the user has no permission to set flags on that {CUDGA}
  B Means no {CUDGA} with the reference number given exists.

0036 0002 UID flags   | Set flags to flags given.
0036 8002 UID flags   | set ok
0036 9002 "Illegal flags" "No info file available"
Errors: AB

0036 0003 DID flags | Set flags to flags given.
0036 8003 DID flags | set ok
0036 9003 "Illegal flags" "No info file available"
Errors: AB

:&&:
0037:
  These packets are used to set the info file for a particular {CDGA}.
The entire file must be sent one piece at a time to the server, which will
store it temporarily until the discussion is destroyed, or permenantly
for {CGA}.

Error codes:
  A Means that the user has no permission to set the info for that {DGA}
  B Means no {DGA} with the reference number given exists.
  D Means that the file is/would be too long
  E Means that the user isn't logged into the system yet.

0037 0100 text | Add text to building file on server
0037 8100      | text accepted
Errors:    DE

0037 0201 CID | End of list packet
0037 8201     | All text accepted and used as info file 
Errors: A  DE

0037 0203 DID | End of list packet
0037 8203     | All text accepted and used as discussion info file
Errors: AB DE

:&&:
0041:
  This function is for sending packets to a {UDGA} or a group of {UDGA}'s
in any combination.  There must be at least one refno for the destination.
There can be as many reference numbers for the destination as you would
wish.  You can mix destinations of different types.

Error codes:
  9 is used if the flags set are not valid for the server.
  A Means that the user has no permission to send to that {UDGA}
  B Means no {UDGA} with the reference number given exists.
  D Means the text of the message was too long.
  E Means that the user isn't logged into the system yet.

0041 0000 flags time text refno [refno...] | send mesage text with flags 
                                 sent at time to refno (can be any refno)
0041 8000 renfo status lastinp [refno status lastinp...] |  send response(s)
     9000 "Bad Flags"
Errors: AB DE

:&&:
0042:
  This packet is for sending announcements to all users on the system.

Error codes:
  9 is used if the flags set are not valid for the server.
  A Means that the user has no permission to send announcements.
  E Means that the user isn't logged into the system yet.

0042 0002 flags time text | send mesage text with flags
0042 8002                 | announce ok
     9002 "Bad Flags"
Errors: A   E

:&&:
00F0:
  Theese are the user connection request packets.  This us used when
a user is first logging onto the system.  They send a name and
password, and recieve in return either the information on their cloverid,
or the information on there clover id and a detached session that that
cloverid owns.  The user can then attach or not as he/she wishes.
The information on the detached session will be null if there is no detached
session.


Error codes:
  9 is used the the name and password are wrong.
  D Means that The name or title give for the Cloverid was too long

00F0 0001 name passwd  | name and password for connection attempt
     8001 defname uname machine flags CID currtime
     9001 "Invalid login attempt"
Errors:    D

:&&:
00F1:
  Once the user is connecte to the system, they use theese packets to
reattach to an old session, or to start a new session.

Error codes:
  A Means that the user has no permission to enter the system.
  C Means that there is alread a User with that name in existance.
  D Means that The name or title for the user is too long.

00F1 0002 name blurb flags                 | data on new user
00F1 8002 UID                              | Login accept
Errors: A CD
 
:&&:
00F8:
  These packets are for when the user wishes to leave the system.
They can either request detach, request to leave, or just say you are
leaving and wait till the system says go.  The middle route is more
polite. Users cannot be detached for more than 30 minutes.

Error codes:
  9 has a variety of meanings.
  E Means that the user isn't logged into the system yet.

00F8 0022 | user is going
00F8 8022 | user is gone.

:&&:
00F9:
  These packets are for when the user wishes to remove an old connection

Error codes:
  A Means that the user has no permission remove that session
  B Means no session with that uid exists

00F9 0022 uid | wipe out this user
00F9 8022     | user is gone
Errors: AB
