calendar.h File Reference

A general API for managing calendar events with Asterisk. More...

#include "asterisk.h"
#include "asterisk/stringfields.h"
#include "asterisk/config.h"
#include "asterisk/linkedlists.h"
#include "asterisk/lock.h"
#include "asterisk/dial.h"
#include "asterisk/module.h"

Include dependency graph for calendar.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_calendar
 Asterisk calendar structure. More...
struct  ast_calendar_attendee
struct  ast_calendar_event
struct  ast_calendar_event::attendees
struct  ast_calendar_tech
 Individual calendaring technology data. More...

Enumerations

enum  ast_calendar_busy_state { AST_CALENDAR_BS_FREE = 0, AST_CALENDAR_BS_BUSY_TENTATIVE, AST_CALENDAR_BS_BUSY }

Functions

void ast_calendar_clear_events (struct ast_calendar *cal)
 Remove all events from calendar.
struct ast_configast_calendar_config_acquire (void)
 Grab and lock pointer to the calendar config (read only).
void ast_calendar_config_release (void)
 Release the calendar config.
struct ast_calendar_eventast_calendar_event_alloc (struct ast_calendar *cal)
 Allocate an astobj2 ast_calendar_event object.
struct ao2_containerast_calendar_event_container_alloc (void)
 Allocate an astobj2 container for ast_calendar_event objects.
void ast_calendar_merge_events (struct ast_calendar *cal, struct ao2_container *new_events)
 Add an event to the list of events for a calendar.
int ast_calendar_register (struct ast_calendar_tech *tech)
 Register a new calendar technology.
struct ast_calendar_eventast_calendar_unref_event (struct ast_calendar_event *event)
 Unreference an ast_calendar_event.
void ast_calendar_unregister (struct ast_calendar_tech *tech)
 Unregister a new calendar technology.


Detailed Description

A general API for managing calendar events with Asterisk.

Author:
Terry Wilson <twilson@digium.com>
Note:
This API implements an abstraction for handling different calendaring technologies in Asterisk. The services provided by the API are a dialplan function to query whether or not a calendar is busy at the present time, a adialplan function to query specific information about events in a time range, a devicestate provider, and notification of calendar events through execution of dialplan apps or dialplan logic at a specific context and extension. The information available through the CALENDAR_EVENT() dialplan function are:
SUMMARY, DESCRIPTION, ORGANIZER, LOCATION CALENDAR, UID, START, END, and BUSYSTATE

BUSYSTATE can have the values 0 (free), 1 (tentatively busy), or 2 (busy)

Usage All calendaring configuration data is located in calendar.conf and is only read directly by the Calendaring API. Each calendar technology resource must register a load_calendar callback which will be passed an ast_calendar_load_data structure. The load_calendar callback function should then set the values it needs from this cfg, load the calendar data, and then loop updating the calendar data and events baesd on the refresh interval in the ast_calendar object. Each call to the load_calendar callback will be will run in its own thread.

Updating events involves creating an astobj2 container of new events and passing it to the API through ast_calendar_merge_events.

Calendar technology resource modules must also register an unref_calendar callback which will only be called when the resource module calls ast_calendar_unregister() to unregister that module's calendar type (usually done in module_unload())

Definition in file calendar.h.


Enumeration Type Documentation

Enumerator:
AST_CALENDAR_BS_FREE 
AST_CALENDAR_BS_BUSY_TENTATIVE 
AST_CALENDAR_BS_BUSY 

Definition at line 81 of file calendar.h.


Function Documentation

void ast_calendar_clear_events ( struct ast_calendar cal  ) 

Remove all events from calendar.

Parameters:
cal calendar whose events need to be cleared

Definition at line 648 of file res_calendar.c.

References ao2_callback, ast_debug, clear_events_cb(), ast_calendar::events, ast_calendar::name, NULL, OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

Referenced by calendar_destructor().

00649 {
00650    ast_debug(3, "Clearing all events for calendar %s\n", cal->name);
00651 
00652    ao2_callback(cal->events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, clear_events_cb, NULL);
00653 }

struct ast_config* ast_calendar_config_acquire ( void   )  [read]

Grab and lock pointer to the calendar config (read only).

Note:
ast_calendar_config_release must be called when finished with the pointer
Returns:
the parsed calendar config

Definition at line 260 of file res_calendar.c.

References ast_rwlock_rdlock, ast_rwlock_unlock, and NULL.

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

00261 {
00262    ast_rwlock_rdlock(&config_lock);
00263 
00264    if (!calendar_config) {
00265       ast_rwlock_unlock(&config_lock);
00266       return NULL;
00267    }
00268 
00269    return calendar_config;
00270 }

void ast_calendar_config_release ( void   ) 

Release the calendar config.

Definition at line 272 of file res_calendar.c.

References ast_rwlock_unlock, and config_lock.

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

00273 {
00274    ast_rwlock_unlock(&config_lock);
00275 }

struct ast_calendar_event* ast_calendar_event_alloc ( struct ast_calendar cal  )  [read]

Allocate an astobj2 ast_calendar_event object.

Parameters:
cal calendar to allocate an event for
Returns:
a new, initialized calendar event

Definition at line 655 of file res_calendar.c.

References ao2_alloc, ast_calendar_unref_event(), AST_LIST_HEAD_INIT_NOLOCK, ast_string_field_init, ast_calendar_event::attendees, calendar_event_destructor(), and NULL.

Referenced by caldav_add_event(), calendar_write_exec(), icalendar_add_event(), parse_tag(), and startelm().

00656 {
00657    struct ast_calendar_event *event;
00658    if (!(event = ao2_alloc(sizeof(*event), calendar_event_destructor))) {
00659       return NULL;
00660    }
00661 
00662    if (ast_string_field_init(event, 32)) {
00663       event = ast_calendar_unref_event(event);
00664       return NULL;
00665    }
00666 
00667    event->owner = cal;
00668    event->notify_sched = -1;
00669    event->bs_start_sched = -1;
00670    event->bs_end_sched = -1;
00671 
00672    AST_LIST_HEAD_INIT_NOLOCK(&event->attendees);
00673 
00674    return event;
00675 }

struct ao2_container* ast_calendar_event_container_alloc ( void   )  [read]

Allocate an astobj2 container for ast_calendar_event objects.

Returns:
a new event container

Definition at line 677 of file res_calendar.c.

References ao2_container_alloc, CALENDAR_BUCKETS, event_cmp_fn(), and event_hash_fn().

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

void ast_calendar_merge_events ( struct ast_calendar cal,
struct ao2_container new_events 
)

Add an event to the list of events for a calendar.

Parameters:
cal calendar containing the events to be merged
new_events an oa2 container of events to be merged into cal->events

Definition at line 1040 of file res_calendar.c.

References add_new_event_cb(), ao2_callback, ast_calendar::events, merge_events_cb(), OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

Referenced by endelm(), icalendar_update_events(), startelm(), update_caldav(), and update_exchangecal().

01041 {
01042    /* Loop through all events attached to the calendar.  If there is a matching new event
01043     * merge its data over and handle any schedule changes that need to be made.  Then remove
01044     * the new_event from new_events so that we are left with only new_events that we can add later. */
01045    ao2_callback(cal->events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, merge_events_cb, new_events);
01046 
01047    /* Now, we should only have completely new events in new_events.  Loop through and add them */
01048    ao2_callback(new_events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, add_new_event_cb, cal->events);
01049 }

int ast_calendar_register ( struct ast_calendar_tech tech  ) 

Register a new calendar technology.

Parameters:
tech calendar technology to register
Return values:
0 success
-1 failure

Definition at line 537 of file res_calendar.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_log, ast_module_user_add, ast_verb, calendar_config, ast_calendar_tech::description, evententry::list, load_tech_calendars(), LOG_WARNING, NULL, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_module().

00538 {
00539    struct ast_calendar_tech *iter;
00540 
00541    if (!calendar_config) {
00542       ast_log(LOG_WARNING, "Calendar support disabled, not loading %s calendar module\n", tech->type);
00543       return -1;
00544    }
00545 
00546    AST_LIST_LOCK(&techs);
00547    AST_LIST_TRAVERSE(&techs, iter, list) {
00548       if(!strcasecmp(tech->type, iter->type)) {
00549          ast_log(LOG_WARNING, "Already have a handler for calendar type '%s'\n", tech->type);
00550          AST_LIST_UNLOCK(&techs);
00551          return -1;
00552       }
00553    }
00554    AST_LIST_INSERT_HEAD(&techs, tech, list);
00555    tech->user = ast_module_user_add(NULL);
00556    AST_LIST_UNLOCK(&techs);
00557 
00558    ast_verb(2, "Registered calendar type '%s' (%s)\n", tech->type, tech->description);
00559 
00560    return load_tech_calendars(tech);
00561 }

struct ast_calendar_event* ast_calendar_unref_event ( struct ast_calendar_event event  )  [read]

void ast_calendar_unregister ( struct ast_calendar_tech tech  ) 

Unregister a new calendar technology.

Parameters:
tech calendar technology to unregister
Return values:
0 success
-1 failure

Definition at line 575 of file res_calendar.c.

References ao2_callback, AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_module_user_remove, ast_verb, evententry::list, match_caltech_cb(), OBJ_MULTIPLE, OBJ_NODATA, OBJ_UNLINK, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_tech_calendars(), and unload_module().

00576 {
00577    struct ast_calendar_tech *iter;
00578 
00579    AST_LIST_LOCK(&techs);
00580    AST_LIST_TRAVERSE_SAFE_BEGIN(&techs, iter, list) {
00581       if (iter != tech) {
00582          continue;
00583       }
00584 
00585       ao2_callback(calendars, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, match_caltech_cb, tech);
00586 
00587       AST_LIST_REMOVE_CURRENT(list);
00588       ast_module_user_remove(iter->user);
00589       ast_verb(2, "Unregistered calendar type '%s'\n", tech->type);
00590       break;
00591    }
00592    AST_LIST_TRAVERSE_SAFE_END;
00593    AST_LIST_UNLOCK(&techs);
00594 
00595 }


Generated on Thu Apr 16 06:29:17 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6