diff --git a/functions/mcal.xml b/functions/mcal.xml index 078982c3e4..6c1e365cd6 100644 --- a/functions/mcal.xml +++ b/functions/mcal.xml @@ -4,34 +4,35 @@ - MCAL stands for Modular Calendar Access Library. - + MCAL stands for Modular Calendar Access Library. + Libmcal is a C library for accessing calendars. It's written to be very modular, with plugable drivers. MCAL is the calendar - equivalent of the IMAP module for mailboxes. - + 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. - + by the mcal library. + Calendar events can be pulled up, queried, and stored. There is - also support for calendar triggers (alarms) and reoccuring events. - + also support for calendar triggers (alarms) and reoccuring events. + With libmcal, central calendar servers can be accessed and used, removing the need for any specific database or local file - programming. - + programming. + To get these functions to work, you have to compile PHP with . That requires the - mcal library to be installed. Grab the latest version from &url.mcal; and - compile and install it. - + 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: @@ -67,8 +68,8 @@ 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. - + values. + @@ -84,21 +85,76 @@ string calendar string username string password - string options + int options - Returns an MCAL stream on success, false on error. + 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. - + internal event structure is also initialized upon connection. + + + + mcal_popen + Opens up a persistant MCAL connection + + + Description + + + int mcal_popen + string calendar + string username + string password + int options + + + + 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 + + + Description + + + int mcal_reopen + string calendar + int options + + + + 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. + + + @@ -115,7 +171,67 @@ - Closes the given mcal stream. + Closes the given mcal stream. + + + + + + + mcal_create_calendar + Create a new MCAL calendar + + + Description + + + int stream + string calendar + + + + Creates a new calendar named calendar. + + + + + + + mcal_rename_calendar + Rename an MCAL calendar + + + Description + + + int stream + string old_name + string new_name + + + + Renames the calendar old_name to + new_name. + + + + + + + mcal_delete_calendar + Delete an MCAL calendar + + + Description + + + int stream + string calendar + + + + Deletes the calendar named calendar. + @@ -138,7 +254,8 @@ mcal_fetch_event fetches an event from the - calendar stream specified by id. + calendar stream specified by id. + Returns an event object consisting of: @@ -196,7 +313,7 @@ mcal_list_events - Return a list of events between two given datetimes + Return a list of IDs for a date or a range of dates. @@ -205,35 +322,23 @@ array mcal_list_events int mcal_stream - int - begin_year - - int - begin_month - - int - begin_day - - int - end_year - - int - end_month - - int - end_day + objectbegin_date + object + end_date - Returns an array of event ID's that are between the start and end + 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. + in the global event structure. + mcal_list_events function takes in an - optional beginning date and an end date for a calendar stream. 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. + internal event dates are returned. + @@ -253,10 +358,11 @@ mcal_append_event Stores the global event - into an MCAL calendar for the given stream. + into an MCAL calendar for the given stream. + - Returns the uid of the newly inserted event. - + Returns the id of the newly inserted event. + @@ -276,10 +382,11 @@ mcal_store_event Stores the modifications - to the current global event for the given stream. + to the current global event for the given stream. + - Returns true on success and false on error. - + Returns true on success and false on error. + @@ -302,7 +409,8 @@ mcal_delete_event deletes the calendar event specified by the event_id. - Returns true. + Returns true. + @@ -316,14 +424,16 @@ int mcal_snooze - int uid + int id mcal_snooze turns off an alarm for a - calendar event specified by the uid. + calendar event specified by the id. + - Returns true. + Returns true. + @@ -364,12 +474,14 @@ 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. + 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. + internal event dates are returned. + @@ -391,9 +503,11 @@ mcal_event_init initializes a streams global event structure. this effectively sets all elements of the - structure to 0, or the default settings. + structure to 0, or the default settings. + - Returns true. + Returns true. + @@ -415,9 +529,11 @@ mcal_event_set_category sets the streams - global event structure's category to the given string. + global event structure's category to the given string. + - Returns true. + Returns true. + @@ -439,9 +555,11 @@ mcal_event_set_title sets the streams global - event structure's title to the given string. + event structure's title to the given string. + - Returns true. + Returns true. + @@ -465,9 +583,11 @@ mcal_event_set_description sets the streams - global event structure's description to the given string. + global event structure's description to the given string. + - Returns true. + Returns true. + @@ -510,9 +630,11 @@ mcal_event_set_start sets the streams global - event structure's start date and time to the given values. + event structure's start date and time to the given values. + - Returns true. + Returns true. + @@ -555,9 +677,11 @@ mcal_event_set_end sets the streams global - event structure's end date and time to the given values. + event structure's end date and time to the given values. + - Returns true. + Returns true. + @@ -579,9 +703,11 @@ mcal_event_set_alarm sets the streams global - event structure's alarm to the given minutes before the event. + event structure's alarm to the given minutes before the event. + - Returns true. + Returns true. + @@ -604,9 +730,11 @@ 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. + for public, or 0 for private. + - Returns true. + Returns true. + @@ -628,7 +756,8 @@ mcal_is_leap_year returns 1 if the given - year is a leap year, 0 if not. + year is a leap year, 0 if not. + @@ -651,7 +780,8 @@ 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. + a leap year or not. + @@ -674,7 +804,8 @@ mcal_date_valid Returns true if the given - year, month and day is a valid date, false if not. + year, month and day is a valid date, false if not. + @@ -697,7 +828,8 @@ mcal_time_valid Returns true if the given - hour, minutes and seconds is a valid time, false if not. + hour, minutes and seconds is a valid time, false if not. + @@ -720,7 +852,8 @@ mcal_day_of_week returns the day of the week - of the given date + of the given date. + @@ -743,7 +876,8 @@ mcal_day_of_year returns the day of the year - of the given date + of the given date. + @@ -767,7 +901,8 @@ mcal_date_compare Compares the two given - dates, returns <0, 0, >0 if a<b, a==b, a>b respectively + dates, returns <0, 0, >0 if a<b, a==b, a>b respectively. + @@ -791,7 +926,8 @@ 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. + considered the beginning of the week. + @@ -815,7 +951,8 @@ mcal_event_set_recur_none sets the streams global event structure to not recur (event->recur_type is set to - MCAL_RECUR_NONE). + MCAL_RECUR_NONE). + @@ -843,7 +980,8 @@ 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. + reoccuring on a daily basis, ending at the given date. + @@ -872,7 +1010,8 @@ 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. + reoccuring on a weekly basis, ending at the given date. + @@ -901,7 +1040,8 @@ 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. + given date. + @@ -930,7 +1070,8 @@ 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. + date. + @@ -958,7 +1099,8 @@ 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 . + reoccuring on a yearly basis,ending at the given date. + @@ -1030,7 +1172,8 @@ int sec - seconds int alarm - minutes before event to send an alarm - + + @@ -1056,7 +1199,32 @@ mcal_event_add_attribute adds an attribute to the stream's global event structure with the value given by - "value" . + "value". + + + + + + + mcal_expunge + + Deletes all events marked for being expunged. + + + + Description + + + int + mcal_expunge + + int stream + + + + mcal_expunge Deletes all events which have + been previously marked for deletion. +