                  Web Calendar Communication Level Protocol


Submitted by:  Group 18
               Liam Finnie
               Timothy Price
               Jason Primeau


0.0 Table of Contents

   1.0. Communications Overview
    1.1. Client-Server Initiated Transfers
    1.2. Administration Commands
    1.3. Message Passing Protocol
    1.4. Responses
    1.5. Standard Error Responses
    1.6. Date and Time Format
     1.6.1 Valid Dates for Meetings
    1.7. Saving User Preferences
     1.7.1. How to Implement User Preferences
    1.8. Upon Starting the Server...
    1.9. Examples
   2.0. Standard User Commands
    2.1. The LOGIN Command
    2.2. The PASSWORD Command
    2.3. The GETCALENDAR Command
    2.4. The DETAILS Command
    2.5. The USERINFO Command
    2.6. The CHANGEMEETING Command
    2.7. The CHANGEPASSWORD Command
    2.8. The GETUSERSCHEDULE Command
    2.9. The NEWMEETING Command
    2.10. The CANCELMEETING Command
    2.11. The REMOVESELFFROMMEETING Command 
    2.12. The SENDMESSAGE Command
    2.13. The LISTALLUSERS Command
    2.14. The USERSONLINE Command
    2.15. The SETPERSONALINFO Command
    2.16. The RESPONDTOMESSAGE Command
    2.17. The LISTALLROOMS Command
    2.18. The GETNEWMESSAGES Command
    2.19. The ADDROOM Command
    2.20. The LOGOFF Command
    2.21. The DEBUG Command
   3.0. Administrator Commands
    3.1. The ADDUSER Command
    3.2. The REMOVEUSER Command
    3.3. The SAVEDB Command
    3.4. The RESTOREDB Command
    3.5. The KILL Command


1.0. Communications Overview

   The calendar uses one socket for client-server initiated transfers.
   The port number which the server operates over is specified as a
   run-time argument for the server.


1.1. Client-Server Initiated Transfers

   These transfers are the typical request-response transfers, initiated
   by the client.  The client will issue one of the commands listed in
   sections 2 and 3, and the server will either perform the requested
   action, or send the client an error message.


1.2. Administration Commands

   The system administrator (logon admin) has special privileges.  The
   admin is allowed to create or remove users, lock all users out, 
   save or restore databases, etc.  Before a user can log on, the admin
   must create an account for that user.  See section 3 for an overview
   of administrator commands available.


1.3. Message Passing Protocol

   All client communications start with a command.  Following this
   command are zero or more parameters, with a comma delimiter (",") after
   every keyword or parameter.  Do not added spaces before or after the
   comma delimiter.  Keywords are not case sensitive. For those
   commands where the user enters a string of text to be part of a
   command, the case will be preserved.  In the case where a comma is
   desired to be part of a message string and not to separate parameters,
   the client should replace that comma with the following string: "^^".
   Whenever data is received from the server, the client will have to
   perform the reverse operation as needed.  Every command, whether
   initiated by the client or the server, requires a response.  A list of
   the possible responses follows each command (in sections 2 and 3).


1.4. Responses

   These are status reports from the server and indicate the response to
   the last command received from the client.

   The first digit of the response broadly indicates the success or
   failure of the previous command.

      1xx - Server confirmation from general user commands
      2xx - Server confirmation from administration commands
      3xx - Client responses to server message commands
      4xx - reserved for future use
      5xx - reserved for future use
      6xx - reserved for future use
      7xx - Error messages to user commands 
      8xx - Error messages to admin commands
      9xx - System malfunction errors


1.5. Standard Error Responses

   The following is a list of standard error response codes that may be
   sent by the web calendar server after any command issued by the client.

     700, ERR, Syntax error
     701, ERR, Too many parameters
     702, ERR, Too few parameters
     703, ERR, Incorrect parameter type
     709, ERR, Invalid command
     714, ERR, System in use (administrator at work)
     715, ERR, User not logged in


1.6. Date and Time Format

   Unless otherwise stated the date and time formats are as follows:
      <date-time> : YYYY/MM/DD/HH/MM 
   where:  YYYY is the 4 digit year (i.e. 1998), MM is the 2 digit 
           month (i.e. 12 is December),  DD is the 2 digit day (i.e. 25),
           HH is the two digit hour in army time (i.e. 14 is 2 o'clock pm)
           and MM is the two digit minutes (i.e. 15). 


1.6.1 Valid Dates for Meetings

   Valid dates for meetings have to be in 1998 or any year following.
   If you try to make a meeting with a year before 1998 you will get
   an invalid date error.


1.7. Saving User Preferences

   Our server supports saving user preferences.  User preferences are
   optional and entirely up to the client to implement.  Possible uses
   of user preferences could be to save whether a user likes to start
   his session with a weekly calendar and a blue screen or with a daily 
   calendar and a green screen.  

1.7.1. How to Implement User Preferences

   Each user that is created has a field of type String called extraInfo.
   This can contain any information that you wish. To change this field,
   use the SETPERSONALINFO command (2.15.).  This field can be read using
   the USERINFO command (2.5.).


1.8. Upon Starting the Server...

   The server will be started by running ./reset (which removes any
   old databases) and then ./server <port-number>.  The first time
   the server is run, all of the databases are initialized.  In 
   particular, a user named "admin" with password "admin" is created.
   You will have to LOGIN (2.1.) as the administrator to create new
   users.  


1.9. Examples

   You can find a list of examples in our DISTRIBUTION directory
   (see our README file) and our web page
   (www.ecf.toronto.edu/~price). 



2.0. Standard User Commands

   In commands and responses, spaces are added after the delimitting
   comma to increase readability.  When issuing commands do not use
   spaces after the delimiting comma.  

   Also, do not user commas in any field (except as the necessary
   delimiters).  Our server treats the information before and after commas
   specially and is only works if no commas are used in field values.
   For example, when sending a message (2.12.) to another user, do not
   include in your message body any commas.
      good:  sendmessage,Hi,How are you? I'm fine.,bob
      bad:  sendmessage,Hi,How are you, I'm fine.,bob
                                      ^
                              do not include commas in any field!!


2.1. The LOGIN Command

   LOGIN, <username>

   The client issues this command to initiate communication with
   the server.  <username> refers to the name that the user is given by
   the system administrator.  A PASSWORD command (2.2.) must be the next
   command issued to the server in order to complete the login procedure. 

   Responses

   100, Ok, Please send password


2.2. The PASSWORD Command

   PASSWORD, <password>

   The client issues this command following the LOGIN command (2.1.) in
   order to complete the two-part login procedure.  <password> refers to
   the password of the user attempting to login to the server.  If the
   password is correct the server will respond with an acknowledgement
   code and the current date and time.  Password encryption is currently
   not supported. 

   Responses

   101, date, time
   711, ERR, User already logged in
   712,ERR,Invalid logon


2.3. The GETCALENDAR Command

   GETCALENDAR, <D|W|M>, <date-time>

   The client issues this command to receive their calendar information. 
   <d|w|m> indicates that either a day, week, or month of appointment
   information is to be obtained at once.  <date-time> is used to help
   the server determine what should be sent to the client.  Meetings
   that are between <date-time> and <date-time> plus D|W|M will be
   returned.  It should be noted that the "who" portion sent by the
   server is a list of users invited to the meeting separated by commas.

   Responses

   102, CONFIRMED|PENDING OTHERS, meetingId, <date-time>, duration(in
        minutes), ownerOfMeeting, meetingPlace, reasonForMeeting, who,
        ENDMEETING,
        ...  other meetings ...
        END
   720, ERR, Invalid date - date does not exist or incorrect syntax

	
2.4. The DETAILS Command

   DETAILS, <meetingId>

   The client issues this command to obtain all information about
   a particular meeting.  However please note that GETCALENDAR (2.3.)
   returns the same information.  This command would be most useful
   as a debugging tool and it is not necessary if you use the
   GETCALENDAR command.

   Responses

   105, meetingId, <date-time>, duration(in minutes), ownerOfMeeting,
        meetingPlace, reasonForMeeting, who, END
   747, ERR, No such meeting exists


2.5. The USERINFO Command

   USERINFO [, username]

   The client issues this command to obtain information about a
   particular person with the login name of [username].  The default
   value of [username] is the login name of the user accessing the
   server.

   Responses
   110, userName, firstName, lastName, officeLocation, emailAddress,
        office_phone, department, extraInfo, END


2.6. The CHANGEMEETING Command

   CHANGEMEETING, <meetingId>, <field>=<new_information> 

   This command is issued to change information about the meeting with
   identification meetingId.  Only one field at a time can be changed.
   The following fields can be changed:
      ROOM, REASON, DURATION, STARTDATE
   The new value for ROOM can be "none", "any" or a valid room name.
   REASON is text explaining why the meeting is happening.
   The new length (in minutes) of the meeting is DURATION.
   DATE is the new desired start date for the meeting in <date-time> form.

   Responses

   116, Ok, Reason has been changed
   117, Ok, Room changed to <newRoom>
   118, Ok, Meeting time changed, <date-time>
   119, Ok, Meeting length changed
   720, ERR, Invalid date - date does not exist or incorrect syntax
   731, ERR, Permission denied - user did not call meeting
   736, ERR, Conflict with scheduled appointment
   737, ERR, Invalid room specification
   738, ERR, Room not available
   739, ERR, Insufficient room capacity
   740, ERR, Appointment ID does not exist
   744, ERR, Invalid room name
   748, ERR, Room not changed
   749, ERR, Invalid meeting length
   750, ERR, Meeting duration not changed
   751, ERR, Meeting date not changed


2.7. The CHANGEPASSWORD Command

   CHANGEPASSWORD, <username>, <old_pass|admin_pass>, <new password>

   The client issues this command to change their login password.  
   If the user forgets their password, the system administrator can 
   issue this command and can use the administration password to 
   change the user's password.

   Responses

   120, Ok, Password changed
   710, ERR, Permission denied
   712, ERR, Invalid logon


2.8. The GETUSERSCHEDULE Command

   GETUSERSCHEDULE, <username>, <d|w|m>, <date>

   The client issues this command to obtain schedule information
   of other users.  This command is different from the GETCALENDAR
   command (2.3.) as it returns less information to promote
   confidentiality of the other users.  It does not return the 
   following information: 
      CONFIRMED|PENDING OTHER USERS,ownerOfMeeting, meetingPlace,
      reasonForMeeting and who

   Responses

   125, <date-time>, duration(in minutes), ENDMEETING,
        ...  other meetings ...
        END
   720, ERR, Invalid date - date does not exist or incorrect syntax
   721, ERR, Incorrect date - date not applicable


2.9. The NEWMEETING Command

   NEWMEETING, <date-time1>, <date-time2>, <duration>, <meetingPlace>, 
      <meetingReason>, <numberOfUsers>, <userName1>, .. , <userNameN>

   The client issues this command to set up a new meeting.  <date-time1>
   and <date-time2> set up a range of times when the client would like
   the meeting to start.  If you would like the meeting to start at a
   specific time, make <date-time1> and <date-time2> exactly the same.
   <duration> is a number which represents the length of the meeting 
   in minutes.  <meetingPlace> is an alphanumeric string which
   refers to the room where the meeting would be held.
   You can enter "none" to not book a room, "any" to book any room
   that is available or you can enter a specific room name.
   <meetingReason> is a string signifying why the client would like to
   have the meeting.  <numberOfUsers> is a numeric value which
   represents the number of users (besides himself) the client is inviting
   to the meeting.  <usernameX> are strings referring to the users the
   client is inviting to the meeting.

   Responses 
   
   131, Meeting pending, meetingId, <date-time>, meetingPlace
   720, ERR, Invalid date - date does not exist or incorrect syntax
   721, ERR, Incorrect date - date not applicable
   722, ERR, Invalid time - time does not exist or incorrect syntax
   723, ERR, Incorrect time - time not applicable
   730, ERR, Meeting not possible at that time
   737, ERR, Invalid room specification
   738, ERR, Room not available
   739, ERR, Insufficient room capacity
   911, ERR, Fatal error


2.10. The CANCELMEETING Command

   CANCELMEETING, <appointment_id> [, reason]

   The client issues this command to cancel a meeting.  <appointment_id>
   is a numeric value representing the identification number of the
   meeting to be cancelled.  [reason] is a string stating why the client
   would like to cancel this meeting. This string will be sent to the
   users invited to the meeting.  [reason] can be left blank.  Only the
   client who called the meeting can cancel it.

   Responses 
   
   135, Meeting cancelled
   731, ERR, Permission denied - user did not call meeting
   732, ERR, User not part of meeting
   740, ERR, Appointment ID does not exist
   911, ERR, Fatal error


2.11. The REMOVESELFFROMMEETING Command

   REMOVESELFFROMMEETING, <appointment_id> [, reason]

   The client issues this command to say that he will not be attending a
   meeting. <appointment_id> is a numeric value representing the
   identification number of the meeting the client would be removed from. 
   [reason] is a string stating why the client will not be attending the
   meeting.  This string will be sent to the remaining users invited to
   the meeting.  <reason> can be left blank.  If there is only one user
   left attending the meeting, the meeting will be cancelled. 
   
   Responses 

   135, Meeting cancelled   
   140, User removed from meeting
   732, ERR, User not part of meeting
   740, ERR, Appointment ID does not exist
   911, ERR, Fatal error


2.12. The SENDMESSAGE Command

   SENDMESSAGE, <subjectLine>, <messageBody>, <recipientName1>, ... ,
      <recipientNameN>

   The client issues this command to send a chat message to
   another user or users.  Remember that no commas can be used in
   any field.  <subjectLine> is a short description of the message
   that follows in <messageBody>.  Examples follow.
      good:  sendmessage,Hi,How are you? I'm fine.,bob
      bad:   sendmessage,Hi,How are you, I'm fine.,bob
                                       ^
                              do not include commas in any field!!

   Responses 
   
   172, Message sent
   

2.13. The LISTALLUSERS Command

   LISTALLUSERS

   The client issues this command to find out who is currently 
   defined as a user in the server.

   Responses 
   
   190, userName1, userName2, ... , END


2.14. The USERSONLINE Command

   USERSONLINE

   The client issues this command to find out who is currently logged on
   to the server.

   Responses 
   
   155, userName, firstName, lastName,
        ... other logged in users ...
        END


2.15. The SETPERSONALINFO Command

   SETPERSONALINFO, <field1>=<new_information> 
      [, ... , <field7>=<new_information>]

   This command is issued when a user would like to change his personal
   information.  <fieldX> is a string representing which field of the
   user's personal information he would like changed.  The possible values
   for <fieldX> are: 
      FIRSTNAME, LASTNAME, OFFICE_NUMBER, EMAIL_ADDRESS, OFFICE_PHONE,
      DEPARTMENT and EXTRAINFO. 
   <new_information> is an alphanumeric value to be assigned to the
   field.  The user can change up to seven fields at a time with this
   command.  There are only seven fields available to change. 

   Responses
   
   160, firstname, lastname, office_number, email, office_phone,
        department, extraInfo, END


2.16. The RESPONDTOMESSAGE Command

   RESPONDTOMESSAGE, <messageId>, <responseToMessage>

   This command will respond to a message with identification
   number <messageId>.  The <responseToMessage> has to be either
   "yes" or "no".

   Responses

   198, A "<responseToMessage>" response was sent to message
        <messageId>
   743, ERR, Message response was not sent
   911, ERR, Fatal error


2.17. The LISTALLROOMS Command

   LISTALLROOMS

   The client issues this command to find out what rooms are currently 
   defined in the server.  This returns the name and capacity of the
   rooms.

   Responses 
   
   192, roomName1, capacity1, roomName2, capacity2,
        ... more rooms ... , 
        END


2.18. The GETNEWMESSAGES Command

   GETNEWMESSAGES

   This command returns the first unread message in the users
   unread message queue.  The first thing it will return is an
   integer identification of the message <messageId>.  If
   <responseRequired> is "yes", the message is asking a question.
   You will need to keep the <messageId> to respond to this 
   message.  If <responseRequired> is "no", the message is an
   informative one.  The user who sent you the message is
   <whoItsFrom>.  <whenSent> is in <date-time> format.
   If there are no messages on the queue, the command returns
   161, No new messages.

   Responses

   161, No new messages
   162, <messageId>, <responseRequired>, <whoItsFrom>, <whenSent>,
      <subjectLine>, <messageBody>
   742, Error retrieving user messages
   911, ERR, Fatal error


2.19. The ADDROOM Command

   ADDROOM, <roomName>, <capacity>

   This command is used to add a room named <roomName> with
   capacity of <capacity>.  <capacity> must be a non-negative,
   non-zero integer.

   Responses
   170, Ok, Room added
   744, ERR, Invalid room name
   745, Room already exists
   746, Invalid room capacity


2.20. The LOGOFF Command

   LOGOFF

   This command disconnects the client from the server.
   
   Responses

   100, User logged off


2.21. The DEBUG Command

   DEBUG [, userName]

   This is a useful debugging tool.  In order to see the results
   of this command you should have the server running in a window
   on your PC.  When DEBUG is typed without userName, it displays
   a list of information about all meetings and rooms that have
   been created to this point.  When DEBUG is typed with userName,
   addition information is printed regarding that user.  This
   information is a list of the user's confirmed, pending and 
   pending other users' acceptance meetings.

   Responses

   OK - see server for list of meetings



3.0. Administrator Commands

   The user must be logged in as "admin" (password is "admin") to execute
   these commands.  Otherwise, you will get the following error:
      710, ERR, Permission denied
   The administrator can also call any Standard User Commands.


3.1. The ADDUSER Command

   ADDUSER, <userName>, <password>, <firstName>, <lastName>, <office>,
            <emailAddress>, <phoneNumber>, <department>, <extraInfo>

   The administrator issues this command to add another user to the
   system.  <username> will refer to the new user's login id.
   <password> is the new user's initial password.
   <firstName> and <lastName> are the first and last names of the user.
   <office> is the new user's office location.  <emailAddress>, 
   <phoneNumber> and <department> are self explanitory.
   <extraInfo> can be anything else about the user.
   The user can change everything except for <userName> with the
   SETPERSONALINFO and CHANGEPASSWORD commands.

   Responses
   
   200, User added successfully
   800, ERR, username already exists


3.2. The REMOVEUSER Command

   REMOVEUSER, <username>

   The administrator issues this command to delete a user from the system
   permanently.

   Responses

   201, User removed successfully
   802, ERR, cannot remove admin
   803, ERR, user is currently on-line


3.3. The SAVEDB Command

   SAVEDB

   The administrator issues this command to save the current system database.
   Before this command can be issued, the system must be locked using the
   <LOCKUSERS, ON> command.

   Responses

   225, Database saved successfully
   912, ERR, disk error
   913, ERR, I/O exception error
   804, ERR, system not locked


3.4. The RESTOREDB Command

   RESTOREDB

   The administrator issues this command to load an existing system database.
   Note that any transactions that may have occurred after the specified
   database had been saved will be lost.

   Responses

   226, Datebase restored
   914, ERR, corrupted database
   912, ERR, disk error
   913, ERR, I/O exception error
   813, ERR, Database not found   
   804, ERR, system not locked


3.5. The KILL Command

   This command will stop the server from running.  It will not save any
   databases since the last time SAVEDB (3.3.) was called.  Any users
   that are still logged in will be disconnected from the server.

   Responses

   250, Server shutting down.
 
