Developer Reference / AOS API Document / calendar
Date: 4 April 2001
Last Revision: 9 April 2001
Available: 9 April 2001
Status: Draft
Revision: 1
Compliant to AOS API Version: AOS 2.0b1
Web: http://www.afteroffice.com/dev/api/calendar.html
By fui@afteroffice.com
Description
Retrieve calendar raw data and performing editing tasks. Use dir.cal.mms is find out the list of calendar available, use view.cal.mms to download the calendar data and ed.cal.mms to peform update.
Index
1. dir.cal.mms: Obtain calendar files list
2. view.cal.mms: Obtain calendar raw data
3. ed.cal.mms: Edit calendar item
4. crnew.cal.mms: Create new calendar
5. delcfn.cal.mms: Delete calendar
Revision 1 (9 April 2001)
Add “showBusy” flag in the Event record structure.
Command: [SID].dir.cal.mms
Use: Obtain calendar files list
Access: HTTP
Method: POST and GET
Parameters case sensitive: NO
Where: [SID] = the user login session ID
Result:
Multiple-lines records, each line is the calendar file name
Parameters:
API = only 1 argument accepted: “LC”
Command: [SID].view.cal.mms
Use: Obtain calendar raw data
Access: HTTP
Method: POST and GET
Parameters case sensitive: NO
Where: [SID] = the user login session ID
Parameters:
| Key | Mandatory | Description | Sample |
|---|---|---|---|
| api | Yes | Indicate the http query is for API, only 1 argument accepted: “LC” | lc |
| y | No | The year of the calendar | 2001 |
| m | No | The month of the calendar, integer. “Next” and “Prev” can be used. | 12 |
| d | No | The day of the calendar, not effective here since the result returned will be always in chunk of month. | 1 |
| f | No | The calendar file to view | Main |
Result:
Multiple-lines records, with DEL (ASCII 8) as fields separator.
First field of each of the line (record) is a dataKey.
DataKey
DataKey describe the record. Each record (line) starts with a dataKey which is typically looks like: 1,1,1 or 1,email
Predefined (Permanent) dataKeys:
| dataKey | Description |
|---|---|
| 0 | total of calendar loaded |
| 0,dir | calendar file list |
| 0,file | current calendar file |
| 0,day | current day |
| 0,month | current month |
| 0,year | current year |
Event record dataKey
AVO calendar are sharable, and therefore calendar data return by the API are multidimensional (aka complex). Event record dataKey has 3 column: x,y,z
All columns are always integer. Each column seperated by a comma. The first column of an event record dataKey is the calendar number. Calendar 1 is always the first calendar specified by the “f” key. Calendar 2 and so on are usually the shared calendar or the cascading calendar (“View also” calendar in AVO).
2nd column of the event record dataKey represent the day in a calendar, and 3rd column represent the event number in the day.
E.g.: 1,7,1 = 1st event record in day 7 of calendar 1
Event record structure:
| Field No. | Type | Format | Description | Sample |
|---|---|---|---|---|
| 1 | DataKey | String | Calendar raw data are returned as array, this is the key locate the data | 1,1,1 |
| 2 | Rsrvd | - | Reserved | - |
| 3 | Rsrvd | - | Reserved | - |
| 4 | longRef | Real | The event item unique reference | 986269618.53469 |
| 5 | ts | Long | Date and time of the event item, in seconds | Main |
| 6 | dura | Long | Duration of the event, in seconds | 3600 |
| 7 | title | String | Title of the event | Weekly meeting |
| 8 | desc | String | Description of the event. If description has more than one line, line break escape as “\r”. | Agenda required |
| 9 | rmdTs | Long | Reminder data and time, in seconds | 986356200 |
| 10 | rmdRef | Long | Reference number for the Reminder | 59177477046 |
| 11 | rmdMethod | String | Reminding method, “mail”, “SMS”,“mailsms” and “othermail” | |
| 12 | rmdVal | int | Reminding value, use this value to multiply with rmdUnit, and get result in seconds (Number of seconds before the event) | 10 |
| 13 | rmdUnit | int | Reminding value unit | 60 |
| 14 | rmdMail | String | Send reminding event to this email | support@afteroffice.com |
| 15 | repeat | - | Repeat the reminder (not supported) | N/A |
| 16 | showBusy | - | Show as busy | checked |
Special dataKey
For each calendar, there are special dataKey that describe the calendar in more detail:
Eg: 1,email or 1,0
| dataKey | Description |
|---|---|
| x,email | The calendar (x) name and email (HTML escaped) of the shared calendar owner. If this calendar is belong to the user, it will be the name of the calendar. |
| x,0 | Up bound (day) of the calendar (x). E.g.: User has events until day 8 of the month, this value will be 8. |
| x,y,0 | Up bound (event) of the day (y) in calendar (x). E.g.: User has 2 events in the day, this value will be 2, and therefore x,y,1 and x,y,2 contains valid event record. |
URL Sample:
http://afteroffice.com/SIDxxx.view.cal.mms?api=lc
Command: [SID].ed.cal.mms
Use: Update, create or delete event.
Access: HTTP
Method: POST and GET
Parameters case sensitive: NO
Where: [SID] = the user login session ID
Result: <boolean><tab><description>
Parameters:
| Key | Mandatory | Description | Sample |
|---|---|---|---|
| api | Yes | Indicate the http query is for API, only 1 argument accepted: “LC” | lc |
| f | Yes | Calendar file name | Main |
| y | No | Event original Year. Required if you try to update or delete an event. | 2001 |
| m | No | Event original Month. Required if you try to update or delete an event. | 1 |
| d | No | Event original Day. Required if you try to update or delete an event. | 1 |
| r | No | Event longRef (reference) number. Required if you try to update or delete an event. If this key is not specify, new event record will be created. | 986269618.53469 |
| title | No | Event title | Meeting |
| desc | No | Event description | Weekly |
| dhour | No | Event duration in hour | 1 |
| dmin | No | Event duration in minute. To specify an event which is 3:30 hour, set dhour to 3 and dmin to 30. | 20 |
| rmd | No | Turn on reminder. “Checked” to turn on, empty to turn off | Checked |
| rmdVal | No | Reminding value before the event invoke, use this value to multiply with rmdUnit, and get result in seconds (Number of seconds before the event) | 10 |
| rmdUnit | No | Reminding value unit, in second. To specify 10 minutes, set rmdVal to 10 and rmdUnit to 60. To specify 1 hours, set rmdVal to 1 and rmdUnit to 3600 (or rmdVal to 60 and rmdUnit to 60) | 60 |
| rmdMail | No | Send reminding event to this email | name@abc.com |
| rmdMethod | No | Reminding method, “mail”, “SMS”,“mailsms” and “othermail” | |
| th | Yes | Event time (hour) | 12 |
| tm | Yes | Event time (minute) | 30 |
| tap | Yes | Event time (AM or PM) | AM |
| year | Yes | Event year | 2001 |
| month | Yes | Event month | 1 |
| day | Yes | Event day | 1 |
| del | No | Delete the event. Specify a non-empty value to indicate delete the event instead of update. | del |
Command: [SID].crnew.cal.mms
Use: Create new calendar.
Access: HTTP
Method: POST and GET
Parameters case sensitive: NO
Where: [SID] = the user login session ID
Result: <boolean><tab><description>
Parameters:
| Key | Mandatory | Description | Sample |
|---|---|---|---|
| api | Yes | Indicate the http query is for API, only 1 argument accepted: “LC” | lc |
| n | Yes | The new calendar name. 27 chars max. | my calendar |
Command: [SID].crnew.cal.mms
Use: Delete calendar file.
Access: HTTP
Method: POST and GET
Parameters case sensitive: NO
Where: [SID] = the user login session ID
Result: <boolean><tab><description>
Parameters:
| Key | Mandatory | Description | Sample |
|---|---|---|---|
| api | Yes | Indicate the http query is for API, only 1 argument accepted: “LC” | lc |
| c | Yes | The calendar file to delete | my calendar |