MCAL API Functions
- CALEVENT* calevent_new(void); /* allocate new event */
- allocates storage for an event.
- CALEVENT* calevent_free(CALEVENT *event); /* frees and returns NULL */
- free's an event structure that was previously created by calevent_new
- bool cal_valid(const char *address);
- returns a boolean response if the string is a valid calendar syntax, and if there
is a driver for it.
- CALSTREAM* cal_open(CALSTREAM *stream, const char *address, long options);
- Opens up a calendar. Takes in an optional current stream, or NULL for a new stream.
address is a calendar address string.
Calendar address strings are currently of the following form:
{servername/protocol}<username>calendar
This is the contents broken down:
- servername - the remote server to connect to
- protocol - The protocol to use (current driver is just icap. a local file driver is in the works.
- username - The users calendar to access. (i.e. john smith could be logged in and wants to view mary's calendar. If this is left blank, it means the current
user that is logged in.
- calendar - The calendar to access.
Most of these parts can also be left out. For example:
- {icap.chek.com}INBOX - Will open up an ICAP connection to icap.chek.com and open up the default calendar for that user.
- {icap.chek.com/icap}INBOX - Will open up an ICAP connection to icap.chek.com and open up the default calendar for that user.
- {icap.chek.com}<> - Will open up an ICAP connection to icap.chek.com and open up the default calendar for that user.
- {icap.chek.com}<MARY> - Will open up an ICAP connection to icap.chek.com and open up the default calendar for mary, regradless of the logged in user .
- CALSTREAM* cal_close(CALSTREAM *stream, long options);
- Closes the given calendar stream.
- bool cal_ping(CALSTREAM *stream);
- returns true if the calendarstream is open, false if not.
- bool cal_search_range( CALSTREAM *stream,
const datetime_t *start,
const datetime_t *end);
- returns the UID's of events for the given calendar stream that fall between
the given start and end dates. The individual UID's are returned in the cc_searched callback.
- bool cal_search_alarm(CALSTREAM *stream, const datetime_t *when);
- returns the UID's of events for the given calendar stream that has or should have an alarm going off
at the given datetime. The individual UID's are returned in the cc_searched callback. The functions itself
returns true on success, false on error.
- bool cal_fetch( CALSTREAM *stream,
unsigned long id,
CALEVENT **event);
- returns true on success. false on error.the event data is returned in the **event parameter that is passed in.
- bool cal_append( CALSTREAM *stream,
const char *folder,
unsigned long *id,
const CALEVENT *event);
- Adds an event to a given calendar. The auto generated ID for that event is returned in the id parameter.
- bool cal_remove( CALSTREAM *stream,unsigned long id);
- Deletes a given calendar entry.
- bool cal_snooze( CALSTREAM *stream,unsigned long id);
- Turns off an alarm for the given event.
Callbacks
These are functions that need to be provided by a client using libicap. These functions
are called by libmcal to pass databetween the internal library and the external interface.
- void cc_login(const char **username, const char **password)
- This is called when login information is requested from an ICAP server.
Simply assign *username and *password to the appropriate values.
- void cc_searched(unsigned long id)
- This is called whenever a search is done. for each event that matched in
the search, the corresponding UID for that event is passed to cc_searched.
Semi-Internal functions
- CALADDR* caladdr_parse(const char *address); /* NULL on error */
- CALADDR* caladdr_dup(const CALADDR *addr); /* NULL on error */
- char* caladdr_out(const CALADDR *addr); /* NULL on error */
- CALADDR* caladdr_free(CALADDR *addr); /* frees and returns NULL */
- CALSTREAM* cal_open_addr(CALSTREAM *stream, const CALADDR *addr, long options);
- bool cal_append_addr(CALSTREAM *stream,
const CALADDR *addr,
unsigned long *id,
const CALEVENT *event);
|
