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
	Calendar events. More...
struct	ast_calendar_tech
	Individual calendaring technology data. More...
struct	ast_calendar_event::attendees

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. More...
const struct ast_config *	ast_calendar_config_acquire (void)
	Grab and lock pointer to the calendar config (read only) More...
void	ast_calendar_config_release (void)
	Release the calendar config. More...
struct ast_calendar_event *	ast_calendar_event_alloc (struct ast_calendar *cal)
	Allocate an astobj2 ast_calendar_event object. More...
struct ao2_container *	ast_calendar_event_container_alloc (void)
	Allocate an astobj2 container for ast_calendar_event objects. More...
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. More...
int	ast_calendar_register (struct ast_calendar_tech *tech)
	Register a new calendar technology. More...
struct ast_calendar_event *	ast_calendar_unref_event (struct ast_calendar_event *event)
	Unreference an ast_calendar_event. More...
void	ast_calendar_unregister (struct ast_calendar_tech *tech)
	Unregister a new calendar technology. More...

Detailed Description

A general API for managing calendar events with Asterisk.

Author

Terry Wilson twils.nosp@m.on@d.nosp@m.igium.nosp@m..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 based 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

ast_calendar_busy_state

enum ast_calendar_busy_state

Enumerator
AST_CALENDAR_BS_FREE
AST_CALENDAR_BS_BUSY_TENTATIVE
AST_CALENDAR_BS_BUSY

Definition at line 83 of file calendar.h.

                             {
    AST_CALENDAR_BS_FREE = 0,
    AST_CALENDAR_BS_BUSY_TENTATIVE,
    AST_CALENDAR_BS_BUSY,
};

Function Documentation

ast_calendar_clear_events()

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 677 of file res_calendar.c.

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

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().

ast_calendar_config_acquire()

const struct ast_config * ast_calendar_config_acquire

(

void

)

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 275 of file res_calendar.c.

{
    ast_rwlock_rdlock(&config_lock);
 
    if (!calendar_config) {
        ast_rwlock_unlock(&config_lock);
        return NULL;
    }
 
    return calendar_config;
}

References ast_rwlock_rdlock, ast_rwlock_unlock, calendar_config, config_lock, and NULL.

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

ast_calendar_config_release()

void ast_calendar_config_release

(

void

)

Release the calendar config.

Definition at line 287 of file res_calendar.c.

{
    ast_rwlock_unlock(&config_lock);
}

References ast_rwlock_unlock, and config_lock.

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

ast_calendar_event_alloc()

struct ast_calendar_event * ast_calendar_event_alloc

(

struct ast_calendar *

cal

)

Allocate an astobj2 ast_calendar_event object.

Parameters

cal	calendar to allocate an event for

Returns

a new, initialized calendar event

Definition at line 684 of file res_calendar.c.

{
    struct ast_calendar_event *event;
    if (!(event = ao2_alloc(sizeof(*event), calendar_event_destructor))) {
        return NULL;
    }
 
    if (ast_string_field_init(event, 32)) {
        event = ast_calendar_unref_event(event);
        return NULL;
    }
 
    event->owner = cal;
    event->notify_sched = -1;
    event->bs_start_sched = -1;
    event->bs_end_sched = -1;
 
    AST_LIST_HEAD_INIT_NOLOCK(&event->attendees);
 
    return event;
}

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

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

ast_calendar_event_container_alloc()

struct ao2_container * ast_calendar_event_container_alloc

(

void

)

Allocate an astobj2 container for ast_calendar_event objects.

Returns

a new event container

Definition at line 706 of file res_calendar.c.

{
    return ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, CALENDAR_BUCKETS,
        event_hash_fn, NULL, event_cmp_fn);
}

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, CALENDAR_BUCKETS, event_cmp_fn(), event_hash_fn(), and NULL.

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

ast_calendar_merge_events()

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 1075 of file res_calendar.c.

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

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().

ast_calendar_register()

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 566 of file res_calendar.c.

{
    struct ast_calendar_tech *iter;
 
    if (!calendar_config) {
        ast_log(LOG_WARNING, "Calendar support disabled, not loading %s calendar module\n", tech->type);
        return -1;
    }
 
    AST_LIST_LOCK(&techs);
    AST_LIST_TRAVERSE(&techs, iter, list) {
        if(!strcasecmp(tech->type, iter->type)) {
            ast_log(LOG_WARNING, "Already have a handler for calendar type '%s'\n", tech->type);
            AST_LIST_UNLOCK(&techs);
            return -1;
        }
    }
    AST_LIST_INSERT_HEAD(&techs, tech, list);
    tech->user = ast_module_user_add(NULL);
    AST_LIST_UNLOCK(&techs);
 
    ast_verb(2, "Registered calendar type '%s' (%s)\n", tech->type, tech->description);
 
    return load_tech_calendars(tech);
}

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, ast_calendar_tech::list, load_tech_calendars(), LOG_WARNING, NULL, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_module().

ast_calendar_unref_event()

struct ast_calendar_event * ast_calendar_unref_event

(

struct ast_calendar_event *

event

)

Unreference an ast_calendar_event.

Parameters

event

event to unref

Returns

NULL

Definition at line 338 of file res_calendar.c.

{
    ao2_ref(event, -1);
    return NULL;
}

References ao2_ref, and NULL.

Referenced by ast_calendar_event_alloc(), caldav_add_event(), calendar_devstate_change(), calendar_query_exec(), calendar_write_exec(), do_notify(), endelm(), event_notification_destroy(), handle_show_calendar(), icalendar_add_event(), merge_events_cb(), and parse_tag().

ast_calendar_unregister()

void ast_calendar_unregister

(

struct ast_calendar_tech *

tech

)

Unregister a new calendar technology.

Parameters

tech	calendar technology to unregister

Definition at line 604 of file res_calendar.c.

{
    struct ast_calendar_tech *iter;
 
    AST_LIST_LOCK(&techs);
    AST_LIST_TRAVERSE_SAFE_BEGIN(&techs, iter, list) {
        if (iter != tech) {
            continue;
        }
 
        ao2_callback(calendars, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, match_caltech_cb, tech);
 
        AST_LIST_REMOVE_CURRENT(list);
        ast_module_user_remove(iter->user);
        ast_verb(2, "Unregistered calendar type '%s'\n", tech->type);
        break;
    }
    AST_LIST_TRAVERSE_SAFE_END;
    AST_LIST_UNLOCK(&techs);
 
}

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, calendars, ast_calendar_tech::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().