[asterisk-dev] Calendaring API

[John Todd]

On Oct 20, 2008, at 4:01 PM, Terry Wilson wrote:

>> I was thinking a bit about the caching issue.  Perhaps there is a way
>> to temporarily cache and refresh unnamed calendars automatically?  In
>> the [general] section of calendars.conf, there might be something
>> like this:
>> [general]
>> ;
>> ; Do we cache un-named calendars that are referenced in the dialplan?
>> ;  This makes subsequent responses faster, which is important during
>> ;  call processing, and also lowers network lag for full calendar
>> ;  imports.
>> ;
>> cacheunnamed=yes
>> ;
>> ; How long do we maintain state for an un-named calendar?  (seconds)
>> ;  If the calendar is unused, and this timer expires, the calendar
>> ;  is "forgotten" until next requested.  However, if the calendar is
>> ;  queried, the counter is reset to zero and starts again.
>> ;
>> cacheduration=86400
>> ;
>> ; Un-named calendars are refreshed this often (seconds) for the
>> duration
>> ;  that they live in the cache.  This keeps them "useful" to
>> subsequent
>> ;  queries without having to pause to re-load the entire calendar.
>> ;  If the calendar is unreachable on a refresh, the data is  
>> maintained
>> ;  until the cacheduration timer expires.
>> ;
>> refresh=3600
>>
>
> I agree that we need something like the above for the "please don't
> thrash the calendar server" issue.  In addition I've been thinking
> about CALENDAR_STATUS some more and I've decided that I don't think
> our proposal quite works, yet.  If we call CALENDAR_STATUS() and it
> has more than one result, and we cache the calendar data, pull back
> the number of results, and decide in the dialplan we want the second
> one...there is no guarantee that the next call to CALENDAR_STATUS()
> will have the same number of results.  Lets say you are doing a query
> based on the ${EPOCH}: the epoch changes between first and second
> query.  All of the sudden you may have 1 result instead of 2 and the
> query requesting the data from result 2 is no longer there.  Or you
> only have one result when you do the initial call, and EPOCH changes
> farther down the dialplan and all of the sudden you have no results
> anymore. You can work around this by setting variables for start/end
> that don't change, I suppose, but the function itself doesn't really
> encourage it and the bug in the dialplan logic that allowed it to
> happen could lead to people missing info, etc.  And it would still be
> confusing in the case if a cache timeout occurs in the middle of
> dialplan execution.  So to make a long story short, I think queries
> should be atomic.
>
> My current thinking is maybe we have a function
> CALENDAR_QUERY(calendar, start, end) which queries all fields of the
> calendar between start and end (ala SELECT * FROM ...) and it returns
> a result ID.  Then we can have CALENDAR_INFO(resultid, field,
> eventnum).  I think we can just store the calendar event info in a
> datastore on the channel so it exists as long as the channel does.  So
> you end up with something like:
>
> exten => 123,1,Set(id=${CALENDAR_QUERY(mycalendar, ${EPOCH}, $[{$
> {EPOCH} + 1800])})
> exten => 123,n,NoOp(${CALENDAR_INFO(${id}, eventnum)} events returned)
> exten => 123,n,NoOp(First summary is ${CALENDAR_INFO(${id}, summary,
> 1)})
>
> etc.  You can thrown in loops, etc. to your hearts content and the
> data is guaranteed to be consistent for the life of the channel.  If
> you want to do a query on another timeframe, store it right along side
> the last query, reference by the correct id, etc.  Maybe throw in a
> CALENDAR_QUERY_FREE() function for people who for some reason want to
> free the results before the end of the call?  This format at least
> makes it explicit that the result set is over a specific time frame
> and that we are dealing with cached information, as opposed to hiding
> it from the user.  Anyway, those are my current thoughts.  Let me know
> what you think.
>
> Terry



I think this is a reasonable approach, though it does add some  
complexity burden for the dialplan creator.  This would solve the  
trivial problem of time passing between sequential queries in the same  
dialplan path, even though not using ${EPOCH} in query criteria would  
remove that issue, as you note.  It also solves the more difficult but  
probably more rare problem of calendar events being added/deleted/ 
changed over the course of a "call", which I think is the more  
fundamental problem.  I'd be in favor of the design you suggest.

Perhaps I am wildly behind the times with some of the more esoteric  
features of Asterisk, but I don't believe that nesting variables  
inside of string values (aka: string macros) is possible - that would  
make coding this a bit easier in the dialplan, though it would  
circumvent the very reason you're proposing to make this atomic.  :-)

I suspect that a "FREE" command is unnecessary.  Calendar lookup  
elements should automatically be freed at Hangup; I don't think so  
many would be created in a single call that they would consume enough  
resources to worry about having to Free them inside the call.

What would you suggest as the ID number as the base of a CALENDAR_QUERY?

My comments on ordering multiple results still I hope hold water (not  
forwarded above for sake of brevity.)

JT


John Todd
jtodd at digium.com        +1-256-428-6083
Asterisk Open Source Community Director



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-dev/attachments/20081020/cbf85d50/attachment.htm