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: : 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 . 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, The client issues this command to initiate communication with the server. 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, The client issues this command following the LOGIN command (2.1.) in order to complete the two-part login procedure. 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, , The client issues this command to receive their calendar information. indicates that either a day, week, or month of appointment information is to be obtained at once. is used to help the server determine what should be sent to the client. Meetings that are between and 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, , 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, 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, , 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, , = 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 form. Responses 116, Ok, Reason has been changed 117, Ok, Room changed to 118, Ok, Meeting time changed, 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, , , 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, , , 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, , 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, , , , , , , , .. , The client issues this command to set up a new meeting. and 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 and exactly the same. is a number which represents the length of the meeting in minutes. 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. is a string signifying why the client would like to have the meeting. is a numeric value which represents the number of users (besides himself) the client is inviting to the meeting. are strings referring to the users the client is inviting to the meeting. Responses 131, Meeting pending, meetingId, , 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, [, reason] The client issues this command to cancel a meeting. 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, [, reason] The client issues this command to say that he will not be attending a meeting. 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. 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, , , , ... , 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. is a short description of the message that follows in . 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, = [, ... , =] This command is issued when a user would like to change his personal information. is a string representing which field of the user's personal information he would like changed. The possible values for are: FIRSTNAME, LASTNAME, OFFICE_NUMBER, EMAIL_ADDRESS, OFFICE_PHONE, DEPARTMENT and EXTRAINFO. 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, , This command will respond to a message with identification number . The has to be either "yes" or "no". Responses 198, A "" response was sent to message 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 . If is "yes", the message is asking a question. You will need to keep the to respond to this message. If is "no", the message is an informative one. The user who sent you the message is . is in format. If there are no messages on the queue, the command returns 161, No new messages. Responses 161, No new messages 162, , , , , , 742, Error retrieving user messages 911, ERR, Fatal error 2.19. The ADDROOM Command ADDROOM, , This command is used to add a room named with capacity of . 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, , , , , , , , , The administrator issues this command to add another user to the system. will refer to the new user's login id. is the new user's initial password. and are the first and last names of the user. is the new user's office location. , and are self explanitory. can be anything else about the user. The user can change everything except for with the SETPERSONALINFO and CHANGEPASSWORD commands. Responses 200, User added successfully 800, ERR, username already exists 3.2. The REMOVEUSER Command REMOVEUSER, 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 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.