I still need to set up tests to make sure my examples are completely correct,
but I ran out of time tonight and felt that they at least would give an idea as
to how to use calendaring. I will try to test the examples and do some cleanup
on the docs tomorrow night.
Added: trunk/doc/tex/calendaring.tex
URL: http://svn.asterisk.org/svn-view/asterisk/trunk/doc/tex/calendaring.tex?view=auto&rev=197926
==============================================================================
--- trunk/doc/tex/calendaring.tex (added)
+++ trunk/doc/tex/calendaring.tex Fri May 29 00:15:40 2009
@@ -1,0 +1,206 @@
+\section{Introduction}
+
+The Asterisk Calendaring API aims to be a generic interface for integrating
+Asterisk with various calendaring technologies. The goal is to be able to
+support reading and writing of calendar events as well as allowing notification
+of pending events through the Asterisk dialplan.
+
+There are three calendaring modules that ship with Asterisk that provide support
+for iCalendar, CalDAV, and Microsoft Exchange Server calendars. All three
+modules support event notification. Both CalDAV and Exchange support reading
+and writing calendars, while iCalendar is a read-only format.
+
+\section{Configuring Asterisk Calendaring}
+
+All asterisk calendaring modules are configured through calender.conf. Each
+calendar module can define its own set of required parameters in addition to the
+parameters available to all calendar types. An effort has been made to keep all
+options the same in all calendaring modules, but some options will diverge over
+time as features are added to each module.
+
+An example calendar.conf might look like:
+\begin{astlisting}
+\begin{verbatim}
+[calendar_joe]
+type = ical
+url = https://example.com/home/jdoe/Calendar
+user = jdoe
+secret = mysecret
+refresh = 15
+timeframe = 600
+autoreminder = 10
+channel = SIP/joe
+context = calendar_event_notify
+extension = s
+waittime = 30
+\end{verbatim}
+\end{astlisting}
+
+\subsection{Module-independent settings}
+
+The settings related to calendar event notification are handled by the core
+calendaring API. These settings are:
+\begin{description}
+\item[autoreminder] This allows the overriding of any alarms that may or may not
+be set for a calendar event. It is specified in minutes.
+\item[refresh] How often to refresh the calendar data; specified in minutes.
+\item[timeframe] How far into the future each calendar refresh should look. This
+is the amount of data that will be visible to queries from the dialplan. This
+setting should always be greater than or equal to the refresh setting or events
+may be missed. It is specified in minutes.
+\item[channel] The channel that should be used for making the notification
+attempt.
+\item[waittime] How long to wait, in seconds, for the channel to answer a notification
+attempt.
+\end{description}
+
+There are two ways to specify how to handle a notification. One option is
+providing a context and extension, while the other is providing an application
+and the arguments to that application. One (and only one) of these options
+should be provided.
+
+\begin{description}
+\item[context] The context of the extension to connect to the notification
+channel
+\item[extension] The extension to connect to the notification. Note that the
+priority will always be 1.
+\end{description}
+
+or
+
+\begin{description}
+\item[app] The dialplan application to execute upon the answer of a notification
+\item[appdata] The data to pass to the notification dialplan application
+\end{description}
+
+\subsection{Module-dependent settings}
+
+Connection-related options are specific to each module. Currently, all modules
+take a url, user, and secret for configuration and no other module-specific
+settings have been implemented. At this time, no support for HTTP redirects has
+been implemented, so it is important to specify the correct URL--paying attention
+to any trailing slashes that may be necessary.
+
+\section{Dialplan functions}
+\subsection{Read functions}
+
+The simplest dialplan query is the CALENDAR\_BUSY query. It takes a single
+option, the name of the calendar defined, and returns "1" for busy (including
+tentatively busy) and "0" for not busy.
+
+For more information about a calendar event, a combination of CALENDAR\_QUERY
+and CALENDAR\_QUERY\_RESULT is used. CALENDAR\_QUERY takes the calendar name
+and optionally a start and end time in "unix time" (seconds from unix epoch). It
+returns an id that can be passed to CALENDAR\_QUERY\_RESULT along with a field
+name to return the data in that field. If multiple events are returned in the
+query, the number of the event in the list can be specified as well. The available
+fields to return are:
+\begin{description}
+\item[summary] A short summary of the event
+\item[description] The full description of the event
+\item[organizer] Who organized the event
+\item[location] Where the event is located
+\item[calendar] The name of the calendar from calendar.conf
+\item[uid] The unique identifier associated with the event
+\item[start] The start of the event in seconds since Unix epoch
+\item[end] The end of the event in seconds since Unix epoch
+\item[busystate] The busy state 0=Free, 1=Tentative, 2=Busy
+\item[attendees] A comma separated list of attendees as stored in the event and
+may include prefixes such as "mailto:".
+\end{description}
+
+When an event notification is sent to the dial plan, the CALENDAR\_EVENT
+function may be used to return the information about the event that is causing
+the notification. The fields that can be returned are the same as those from
+CALENDAR\_QUERY\_RESULT.
+\subsection{Write functions}
+
+To write an event to a calendar, the CALENDAR\_WRITE function is used. This
+function takes a calendar name and also uses the same fields as
+CALENDAR\_QUERY\_RESULT. As a write function, it takes a set of comma-separated
+values that are in the same order as the specified fields. For example:
+\begin{astlisting}
+\begin{verbatim}
+CALENDAR_WRITE(mycalendar,summary,organizer,start,end,busystate)=
+ "My event","mailto:jdoe@example.com",228383580,228383640,1)
+\end{verbatim}
+\end{astlisting}
+
+\section{Dialplan Examples}
+\subsection{Office hours}
+A common business PBX scenario is would be executing dialplan logic based on
+when the business is open and the phones staffed. If the business is closed for
+holidays, it is sometimes desirable to play a message to the caller stating why
+the business is closed.
+
+The standard way to do this in asterisk has been doing a series of GotoIfTime
+statements or time-based include statements. Either way can be tedious and
+requires someone with access to edit asterisk config files.
+
+With calendaring, the adminstrator only needs to set up a calendar that contains
+the various holidays or even recurring events specifying the office hours. A
+custom greeting filename could even be contained in the description field for
+playback. For example:
+\begin{astlisting}
+\begin{verbatim}
+[incoming]
+exten => 5555551212,1,Answer
+exten => 5555551212,n,GotoIf(${CALENDAR_BUSY(officehours)}?closed:attendant,s,1)
+exten => 5555551212,n(closed),Set(id=${CALENDAR_QUERY(office,${EPOCH},${EPOCH})})
+exten => 5555551212,n,Set(soundfile=${CALENDAR_QUERY_RESULT(${id},description)})
+exten => 5555551212,n,Playback($[${ISNULL(soundfile)} ? generic-closed :: ${soundfile}])
+exten => 5555551212,n,Hangup
+\end{verbatim}
+\end{astlisting}
+
+\subsection{Meeting reminders}
+One useful application of Asterisk Calendaring is the ability to execute
+dialplan logic based on an event notification. Most calendaring technologies
+allow a user to set an alarm for an event. If these alarms are set on a calendar
+that Asterisk is monitoring and the calendar is set up for event notification
+via calendar.conf, then Asterisk will execute notify the specified channel at
+the time of the alarm. If an overrided notification time is set with the
+autoreminder setting, then the notification would happen at that time instead.
+
+The following example demonstrates the set up for a simple event notification
+that plays back a generic message followed by the time of the upcoming meeting.
+calendar.conf.
+\begin{astlisting}
+\begin{verbatim}
+[calendar_joe]
+type = ical
+url = https://example.com/home/jdoe/Calendar
+user = jdoe
+secret = mysecret
+refresh = 15
+timeframe = 600
+autoreminder = 10
+channel = SIP/joe
+context = calendar_event_notify
+extension = s
+waittime = 30
+\end{verbatim}
+\end{astlisting}
+
+\begin{astlisting}
+\begin{verbatim}
+[calendar_event_notify]
+exten => s,1,Answer
+exten => s,n,Playback(you-have-a-meeting-at)
+exten => s,n,SayUnixTime(${CALENDAR_EVENT(start)})
+exten => s,n,Hangup
+\end{verbatim}
+\end{astlisting}
+
+\subsection{Writing an event}
+Both CalDAV and Exchange calendar servers support creating new events. The
+following example demonstrates writing a log of a call to a calendar.
+\begin{astlisting}
+\begin{verbatim}
+[incoming]
+exten => 6000,1,Set(start=${EPOCH})
+exten => 6000,n,Dial(SIP/joe)
+exten => h,1,Set(end=${EPOCH})
+exten => h,n,Set(CALENDAR_WRITE(calendar_joe,summary,start,end)=Call from ${CALLERID(all)},${start},${end})
+\end{verbatim}
+\end{astlisting}
Propchange: trunk/doc/tex/calendaring.tex
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum