MCAL MCAL stands for Modular Calendar Access Library. Libmcal is a C library for accessing calendars. It's written to be very modular, with pluggable drivers. MCAL is the calendar equivalent of the IMAP module for mailboxes. With mcal support, a calendar stream can be opened much like the mailbox stream with the IMAP support. Calendars can be local file stores, remote ICAP servers, or other formats that are supported by the mcal library. Calendar events can be pulled up, queried, and stored. There is also support for calendar triggers (alarms) and recurring events. With libmcal, central calendar servers can be accessed, removing the need for any specific database or local file programming. To get these functions to work, you have to compile PHP with --with-mcal. That requires the mcal library to be installed. Grab the latest version from &url.mcal; and compile and install it. The following constants are defined when using the MCAL module. For weekdays : MCAL_SUNDAY MCAL_MONDAY MCAL_TUESDAY MCAL_WEDNESDAY MCAL_THURSDAY MCAL_FRIDAY MCAL_SATURDAY For recurrence : MCAL_RECUR_NONE MCAL_RECUR_DAILY MCAL_RECUR_WEEKLY MCAL_RECUR_MONTHLY_MDAY MCAL_RECUR_MONTHLY_WDAY MCAL_RECUR_YEARLY For months : MCAL_JANUARY MCAL_FEBRUARY MCAL_MARCH MCAL_APRIL MCAL_MAY MCAL_JUNE MCAL_JULY MCAL_AUGUST MCAL_SEPTEMBER MCAL_OCTOBER MCAL_NOVEMBER MCAL_DECEMBER Most of the functions use an internal event structure that is unique for each stream. This alleviates the need to pass around large objects between functions. There are convenience functions for setting, initializing, and retrieving the event structure values. mcal_open Opens up an MCAL connection intmcal_open stringcalendar stringusername stringpassword intoptions Returns an MCAL stream on success, &false; on error. mcal_open opens up an MCAL connection to the specified calendar store. If the optional options is specified, passes the options to that mailbox also. The streams internal event structure is also initialized upon connection. mcal_popen Opens up a persistent MCAL connection intmcal_popen stringcalendar stringusername stringpassword intoptions Returns an MCAL stream on success, &false; on error. mcal_popen opens up an MCAL connection to the specified calendar store. If the optional options is specified, passes the options to that mailbox also. The streams internal event structure is also initialized upon connection. mcal_reopen Reopens an MCAL connection intmcal_reopen stringcalendar intoptions Reopens an MCAL stream to a new calendar. mcal_reopen reopens an MCAL connection to the specified calendar store. If the optional options is specified, passes the options to that mailbox also. mcal_close Close an MCAL stream intmcal_close intmcal_stream intflags Closes the given mcal stream. mcal_create_calendar Create a new MCAL calendar stringmcal_create_calendar intstream stringcalendar Creates a new calendar named calendar. mcal_rename_calendar Rename an MCAL calendar stringmcal_rename_calendar intstream stringold_name stringnew_name Renames the calendar old_name to new_name. mcal_delete_calendar Delete an MCAL calendar stringmcal_delete_calendar intstream stringcalendar Deletes the calendar named calendar. mcal_fetch_event Fetches an event from the calendar stream objectmcal_fetch_event intmcal_stream intevent_id intoptions mcal_fetch_event fetches an event from the calendar stream specified by id. Returns an event object consisting of: int id - ID of that event. int public - &true; if the event if public, &false; if it is private. string category - Category string of the event. string title - Title string of the event. string description - Description string of the event. int alarm - number of minutes before the event to send an alarm/reminder. object start - Object containing a datetime entry. object end - Object containing a datetime entry. int recur_type - recurrence type int recur_interval - recurrence interval datetime recur_enddate - recurrence end date int recur_data - recurrence data All datetime entries consist of an object that contains: int year - year int month - month int mday - day of month int hour - hour int min - minutes int sec - seconds int alarm - minutes before event to send an alarm The possible values for recur_type are: 0 - Indicates that this event does not recur 1 - This event recurs daily 2 - This event recurs on a weekly basis 3 - This event recurs monthly on a specific day of the month (e.g. the 10th of the month) 4 - This event recurs monthly on a sequenced day of the week (e.g. the 3rd Saturday) 5 - This event recurs on an annual basis mcal_list_events Return a list of IDs for a date or a range of dates. arraymcal_list_events intmcal_stream objectbegin_date objectend_date Returns an array of ID's that are between the start and end dates, or if just a stream is given, uses the start and end dates in the global event structure. mcal_list_events function takes in an beginning date and an optional end date for a calendar stream. An array of event id's that are between the given dates or the internal event dates are returned. mcal_append_event Store a new event into an MCAL calendar intmcal_append_event intmcal_stream mcal_append_event Stores the global event into an MCAL calendar for the given stream. Returns the id of the newly inserted event. mcal_store_event Modify an existing event in an MCAL calendar intmcal_store_event intmcal_stream mcal_store_event Stores the modifications to the current global event for the given stream. Returns the event id of the modified event on success and &false; on error. mcal_delete_event Delete an event from an MCAL calendar intmcal_delete_event intmcal_stream intevent_id mcal_delete_event deletes the calendar event specified by the event_id. Returns &true;. mcal_snooze Turn off an alarm for an event intmcal_snooze intid mcal_snooze turns off an alarm for a calendar event specified by the id. Returns &true;. mcal_list_alarms Return a list of events that has an alarm triggered at the given datetime arraymcal_list_alarms intmcal_stream intbegin_year intbegin_month intbegin_day intend_year intend_month intend_day Returns an array of event ID's that has an alarm going off between the start and end dates, or if just a stream is given, uses the start and end dates in the global event structure. mcal_list_events function takes in an optional beginning date and an end date for a calendar stream. An array of event id's that are between the given dates or the internal event dates are returned. mcal_event_init Initializes a streams global event structure intmcal_event_init intstream mcal_event_init initializes a streams global event structure. this effectively sets all elements of the structure to 0, or the default settings. Returns &true;. mcal_event_set_category Sets the category of the streams global event structure intmcal_event_set_category intstream stringcategory mcal_event_set_category sets the streams global event structure's category to the given string. Returns &true;. mcal_event_set_title Sets the title of the streams global event structure intmcal_event_set_title intstream stringtitle mcal_event_set_title sets the streams global event structure's title to the given string. Returns &true;. mcal_event_set_description Sets the description of the streams global event structure intmcal_event_set_description intstream stringdescription mcal_event_set_description sets the streams global event structure's description to the given string. Returns &true;. mcal_event_set_start Sets the start date and time of the streams global event structure intmcal_event_set_start intstream intyear intmonth int day int hour int min int sec mcal_event_set_start sets the streams global event structure's start date and time to the given values. Returns &true;. mcal_event_set_end Sets the end date and time of the streams global event structure intmcal_event_set_end intstream intyear intmonth int day int hour int min int sec mcal_event_set_end sets the streams global event structure's end date and time to the given values. Returns &true;. mcal_event_set_alarm Sets the alarm of the streams global event structure intmcal_event_set_alarm intstream intalarm mcal_event_set_alarm sets the streams global event structure's alarm to the given minutes before the event. Returns &true;. mcal_event_set_class Sets the class of the streams global event structure intmcal_event_set_class intstream intclass mcal_event_set_class sets the streams global event structure's class to the given value. The class is either 1 for public, or 0 for private. Returns &true;. mcal_is_leap_year Returns if the given year is a leap year or not intmcal_is_leap_year intyear mcal_is_leap_year returns 1 if the given year is a leap year, 0 if not. mcal_days_in_month Returns the number of days in the given month intmcal_days_in_month intmonth intleap year mcal_days_in_month Returns the number of days in the given month, taking into account if the given year is a leap year or not. mcal_date_valid Returns &true; if the given year, month, day is a valid date intmcal_date_valid intyear intmonth intday mcal_date_valid Returns &true; if the given year, month and day is a valid date, &false; if not. mcal_time_valid Returns &true; if the given year, month, day is a valid time intmcal_time_valid inthour intminutes intseconds mcal_time_valid Returns &true; if the given hour, minutes and seconds is a valid time, &false; if not. mcal_day_of_week Returns the day of the week of the given date intmcal_day_of_week intyear intmonth intday mcal_day_of_week returns the day of the week of the given date. Possible return values range from 0 for Sunday through 6 for Saturday. mcal_day_of_year Returns the day of the year of the given date intmcal_ intyear intmonth intday mcal_day_of_year returns the day of the year of the given date. mcal_date_compare Compares two dates intmcal_date_compare inta_year inta_month inta_day intb_year intb_month intb_day mcal_date_compare Compares the two given dates, returns <0, 0, >0 if a<b, a==b, a>b respectively. mcal_next_recurrence Returns the next recurrence of the event intmcal_next_recurrence intstream intweekstart arraynext mcal_next_recurrence returns an object filled with the next date the event occurs, on or after the supplied date. Returns empty date field if event does not occur or something is invalid. Uses weekstart to determine what day is considered the beginning of the week. mcal_event_set_recur_none Sets the recurrence of the streams global event structure intmcal_event_set_recur_none intstream mcal_event_set_recur_none sets the streams global event structure to not recur (event->recur_type is set to MCAL_RECUR_NONE). mcal_event_set_recur_daily Sets the recurrence of the streams global event structure intmcal_event_set_recur_daily intstream intyear intmonth intday intinterval mcal_event_set_recur_daily sets the streams global event structure's recurrence to the given value to be reoccuring on a daily basis, ending at the given date. mcal_event_set_recur_weekly Sets the recurrence of the streams global event structure intmcal_event_set_recur_weekly intstream intyear intmonth intday intinterval intweekdays mcal_event_set_recur_weekly sets the streams global event structure's recurrence to the given value to be reoccuring on a weekly basis, ending at the given date. mcal_event_set_recur_monthly_mday Sets the recurrence of the streams global event structure intmcal_event_set_recur_monthly_mday intstream intyear intmonth intday intinterval mcal_event_set_recur_monthly_mday sets the streams global event structure's recurrence to the given value to be reoccuring on a monthly by month day basis, ending at the given date. mcal_event_set_recur_monthly_wday Sets the recurrence of the streams global event structure intmcal_event_set_recur_monthly_wday intstream intyear intmonth intday intinterval mcal_event_set_recur_monthly_wday sets the streams global event structure's recurrence to the given value to be reoccuring on a monthly by week basis, ending at the given date. mcal_event_set_recur_yearly Sets the recurrence of the streams global event structure intmcal_event_set_recur_yearly intstream intyear intmonth intday intinterval mcal_event_set_recur_yearly sets the streams global event structure's recurrence to the given value to be reoccuring on a yearly basis,ending at the given date. mcal_fetch_current_stream_event Returns an object containing the current streams event structure objectmcal_fetch_current_stream_event intstream mcal_fetch_current_stream_event returns the current stream's event structure as an object containing: int id - ID of that event. int public - &true; if the event if public, &false; if it is private. string category - Category string of the event. string title - Title string of the event. string description - Description string of the event. int alarm - number of minutes before the event to send an alarm/reminder. object start - Object containing a datetime entry. object end - Object containing a datetime entry. int recur_type - recurrence type int recur_interval - recurrence interval datetime recur_enddate - recurrence end date int recur_data - recurrence data All datetime entries consist of an object that contains: int year - year int month - month int mday - day of month int hour - hour int min - minutes int sec - seconds int alarm - minutes before event to send an alarm mcal_event_add_attribute Adds an attribute and a value to the streams global event structure voidmcal_event_add_attribute intstream stringattribute stringvalue mcal_event_add_attribute adds an attribute to the stream's global event structure with the value given by "value". mcal_expunge Deletes all events marked for being expunged. intmcal_expunge intstream mcal_expunge Deletes all events which have been previously marked for deletion. mcal_week_of_year Returns the week number of the given date intmcal_week_of_year intday intmonth intyear &warn.undocumented.func;