[asterisk-dev] Calendaring API
John Todd
jtodd at digium.com
Tue Oct 7 18:46:11 CDT 2008
I'll break out of the thread a bit and post my ideas for what I've
been thinking
about with this calendar idea. I think the features as Terry has written them
are great - but I'm always looking to figure out how to make things
more complex
than they _need_ to be (since typically, they end up needing to be that complex
eventually, anyway.)
I enclose my thoughts on a slightly modified version of the Calendar function,
at least as far as it goes for reading calendars. Ignore or comment upon at
your leisure.
JT
John Todd
jtodd at digium.com +1-256-428-6083
Asterisk Open Source Community Director
[note to future archive surfers: this syntax does not exist; it is currently
a figment of my imagination - please keep searching for what you want, or
feel free to bring this thread back from the depths.]
core1*CLI> core show function CALENDAR_STATUS
-= Info about function 'CALENDAR_STATUS' =-
[Syntax]
CALENDAR_STATUS(<calendar_name>,<value>[,<time range>][,<event-number>])
[Synopsis]
Query a calendar server and return basic or detailed status about
one or more events occurring now or during described time periods.
[Description]
Options:
<calendar name> = A named calendar entry in the calendar.conf file,
or a calendar URL format like this:
caltype/[username][:password][@][calURI]
caltype = "ical" or "exchange" (required)
username = the calendar username (optional)
password = the calendar password (optional)
calURI = calendar URL (required) (port number optional)
examples:
mycalendar
Uses calendar.conf entry named "mycalendar"
ical/http://example.com/calendars/holidays
Looks up an ical calendar on a remote host
ical/jdoe:sEKret at https://example.com:443/home/jdoe/mycal/
Looks up an ical calendar type using authentication
data on specific port of remote host example.com
<value> = Specific information about a particular event.
getnum : This returns the number of events occurring
during the query period.
summary : The EVENT SUMMARY property or Exchange
event 'subject'
description : The text description of the event
organizer : The organizer of the event
location : The location of the event
calendar : The name of the calendar associated with the event
uid : The unique identifier for this event
start : The start time of the event
end : The end time of the event
busystate : The busy state of the event 0=FREE,
1=TENTATIVE, 2=BUSY
time range = a time range for the query, in the format of:
YYYYMMDDHHMM["-<tzone-name>","-HH:MM"][&[YYYYMMDDHHMM["-<tzone-name>","-HH:MM"]]
Special name "now" can replace time and timezone.
Special indicators "+" and "-" can be used to add or
subtract minutes from a given time. If no timezone is
specified, Asterisk uses the timezone of the system as
set locally. Any references in timezone-names to numeric
hour/minute offsets are assumed to be from GMT, and any
use of "-" and "+" characters in the timezone names are
considered part of the timezone name and not as modifiers.
If time range is omitted, assumption is that the time
is "now".
examples:
now+5
Looks up any events 5 minutes from this moment.
200810061440
Looks up any events (using system timezone) that are
occuring on Oct 6, 2008 at 14:40.
now&now+30
Looks up any events from this moment until one half
hour in the future.
now-30&now+30
Looks up any events from half an hour ago to half
an hour in the future.
200810061450&200810061550
Looks up any events for 2:50 PM until 3:50 PM, and uses the
timezone of the local machine as the timezone modifier.
200810061450-PDT&200810061550-PDT
Looks up any events for 2:50 PM Pacific Daylight Time
until 3:50 PM Pacific.
200810061450-08:00&200810061550-08:00
Looks up any events for October 6, 2008 2:50 PM Pacific
until October 6, 2008 3:50 PM Pacific, but doesn't consider
daylight savings time - just uses 8 hour offset.
now-30&200810061450-08:00-120
Looks up any events from half an hour in the past until
two hours before October 6, 2008 2:50 Pacific
(otherwise known as 12:50 PM Pacific)
Examples:
These examples use a calendar which has two (poorly scheduled) events:
Oct 6, 2008 1:00 - 1:30 PM Pacific: "Get Lunch with Penny Preddy"
Oct 6, 2008 1:15 - 1:45 PM Pacific: "Mrs. Johnson conference call"
The calendar exists in calendar.conf as "calendar1".
The realtime clock at the moment of this example is 1:20 PM
Pacific, October 6 2008.
${CALENDAR_STATUS(calendar1,busystate)}
Returns "2", since there is at least one event at this moment.
${CALENDAR_STATUS(calendar1,getnum)}
Returns "2", since there are two events active at this moment.
${CALENDAR_STATUS(calendar1,summary)}
Returns "Get Lunch with Penny Preddy" as the first ordered result.
(see "Sorting Order..." in calendar.README)
${CALENDAR_STATUS(calendar1,summary,,2)}
Returns "Mrs. Johnson conference call"
(see "Sorting Order..." in calendar.README)
${CALENDAR_STATUS(calendar1,summary,now+20)}
Returns "Mrs. Johnson conference call" since at 1:40 we only have that one
active event.
${CALENDAR_STATUS(calendar1,summary,now+60&now+120)}
Returns a null string, since there are no entries on the calendar
that match that time span.
${CALENDAR_STATUS(calendar1,busystate,now+60&now+120)}
Returns a null string, since there are no entries on the calendar
that match that time span. Note that this is different than
replying with "0", which means there is an event but it is not
a "busy" event.
core1*CLI>
From a snippet of a hypothetical calendar.README file:
SORTING ORDER MULTIPLE EVENTS
If there are multiple events resulting from a query that is not a
time range and is a specific moment im time, the system will create
an ordered list, with the events being stacked by the nearest start
time to the given query time, nearest times to the query moment
ordered lowest in the list. If one or more events have the same
start time, then those events will be sub-ordered by nearest end
time, nearest times to the query moment ordered lowest in the list.
If one or more of those events have the same end time, then they will
be further sub-ordered by their UIDs, alphabetically/numerically,
with the highest ranking members appearing lowest in the resulting
list.
If there are multiple events resulting from a query that consists of
a time start/end range, the system will create an ordered list.
Events that span or are equal to the starting edge of the query range
will be ordered by their start time, earliest start times lowest on
the list. If one or more are equal, then sort by duration, with
longer durations being lower on the list. If one or more of those
are equal, then sort alphabetically/numerically by UID, with highest
ranking members appearing lowest in the resulting list. The
remaining events are sorted by earliest start time, with earlier
start times being lower on the list. If one or more of these are the
same, then sort by duration, with longer durations being lower on the
list. If one or more of those are equal, then sort
alphabetically/numerically by UID, with highest ranking members
appearing lowest in the resulting list.
For example, if a calendar event ("Management Retreat Meeting") spans
from 8:00A to 8:00P, and then another event ("Lunch") spans from
12:00P to 1:00P, and yet another event ("Get a Soda") spans from
12:00P to 12:05P, then a query about 12:03P would give an ordered
list of:
1: Get a Soda
2: Lunch
3: Management Retreat Meeting
and a query about 12:00P-1:00P time span would give an ordered list of:
1: Management Retreat Meeting
2: Lunch
3: Get a Soda
Maximum number of stacked events is 255.
If the query is a "busystate" query without a specific event-number
provided, and there is more than 1 concurrent event, then the highest
busystate of all of the events will be returned.
--
More information about the asterisk-dev
mailing list