<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.mcal">
  <title>MCAL functions</title>
  <titleabbrev>MCAL</titleabbrev>

  <partintro>
   <para>
    MCAL stands for Modular Calendar Access Library.
   </para>
   <para>
    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.
   </para>
   <para>
    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.
   </para>
   <para>
    Calendar events can be pulled up, queried, and stored. There is
    also support for calendar triggers (alarms) and reoccuring events.
   </para>
   <para>
    With libmcal, central calendar servers can be accessed and used,
    removing the need for any specific database or local file
    programming.
   </para>
   <para>
    To get these functions to work, you have to compile PHP with
    <option role="configure">--with-mcal</option>. That requires the
    mcal library to be installed. Grab the latest version from
    <ulink url="&url.mcal;">&url.mcal;</ulink> and compile and install
    it.
   </para>
   <para>
    The following constants are defined when using the MCAL module:

    MCAL_SUNDAY,
    MCAL_MONDAY,
    MCAL_TUESDAY,
    MCAL_WEDNESDAY,
    MCAL_THURSDAY,
    MCAL_FRIDAY,
    MCAL_SATURDAY,

    MCAL_RECUR_NONE,
    MCAL_RECUR_DAILY,
    MCAL_RECUR_WEEKLY,
    MCAL_RECUR_MONTHLY_MDAY,
    MCAL_RECUR_MONTHLY_WDAY,
    MCAL_RECUR_YEARLY,

    MCAL_JANUARY,
    MCAL_FEBRUARY,
    MCAL_MARCH,
    MCAL_APRIL,
    MCAL_MAY,
    MCAL_JUNE,
    MCAL_JULY,
    MCAL_AUGUGT,
    MCAL_SEPTEMBER,
    MCAL_OCTOBER,
    MCAL_NOVEMBER, and
    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.
   </para>
  </partintro>

  <refentry id="function.mcal-open">
   <refnamediv>
    <refname>mcal_open</refname>
    <refpurpose>Opens up an MCAL connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_open</methodname>
      <methodparam><type>string</type><parameter>calendar</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an MCAL stream on success, &false; on error.
    </para>  
    <para>
     <function>mcal_open</function> opens up an MCAL connection to the
     specified <parameter>calendar</parameter> store. If the optional
     <parameter>options</parameter> is specified, passes the
     <parameter>options</parameter> to that mailbox also. The streams
     internal event structure is also initialized upon connection.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-popen">
   <refnamediv>
    <refname>mcal_popen</refname>
    <refpurpose>Opens up a persistant MCAL connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_popen</methodname>
      <methodparam><type>string</type><parameter>calendar</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an MCAL stream on success, &false; on error.
    </para>  
    <para>
     <function>mcal_popen</function> opens up an MCAL connection to the
     specified <parameter>calendar</parameter> store. If the optional
     <parameter>options</parameter> is specified, passes the
     <parameter>options</parameter> to that mailbox also. The streams
     internal event structure is also initialized upon connection.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-reopen">
   <refnamediv>
    <refname>mcal_reopen</refname>
    <refpurpose>Reopens an MCAL connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_reopen</methodname>
      <methodparam><type>string</type><parameter>calendar</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>
     Reopens an MCAL stream to a new calendar.
    </para>  
    <para>
     <function>mcal_reopen</function> reopens  an MCAL connection to the
     specified <parameter>calendar</parameter> store. If the optional
     <parameter>options</parameter> is specified, passes the
     <parameter>options</parameter> to that mailbox also.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-close">
   <refnamediv>
    <refname>mcal_close</refname>
    <refpurpose>Close an MCAL stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_close</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Closes the given mcal stream.
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.mcal-create-calendar">
   <refnamediv>
    <refname>mcal_create_calendar</refname>
    <refpurpose>Create a new MCAL calendar </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mcal_create_calendar</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>calendar</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Creates a new calendar named <parameter>calendar</parameter>.
    </para> 
   </refsect1>
  </refentry>
  
  <refentry id="function.mcal-rename-calendar">
   <refnamediv>
    <refname>mcal_rename_calendar</refname>
    <refpurpose>Rename an MCAL calendar </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mcal_rename_calendar</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>old_name</parameter></methodparam>
      <methodparam><type>string</type><parameter>new_name</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Renames the calendar <parameter>old_name</parameter> to
     <parameter>new_name</parameter>.
    </para> 
   </refsect1>
  </refentry>
  
  <refentry id="function.mcal-delete-calendar">
   <refnamediv>
    <refname>mcal_delete_calendar</refname>
    <refpurpose>Delete an MCAL calendar </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mcal_delete_calendar</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>calendar</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Deletes the calendar named <parameter>calendar</parameter>.
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.mcal-fetch-event">
   <refnamediv>
    <refname>mcal_fetch_event</refname>
    <refpurpose>
     Fetches an event from the calendar stream
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>mcal_fetch_event</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>event_id</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_fetch_event</function> fetches an event from the 
     calendar stream specified by <parameter>id</parameter>.
    </para>
    <para>
     Returns an event object consisting of:
     <itemizedlist>
      <listitem><simpara>
	int id - ID of that event.</simpara></listitem>
      <listitem><simpara>
	int public - &true; if the event if public, &false; if it is
	private.</simpara></listitem>
      <listitem><simpara>
	string category - Category string of the event.</simpara></listitem> 
      <listitem><simpara>
	string title - Title string of the event.</simpara></listitem>
      <listitem><simpara>
	string description - Description string of the event.</simpara></listitem>
      <listitem><simpara>
	int alarm - number of minutes before the event to send an
	alarm/reminder.</simpara></listitem>
      <listitem><simpara>
	object start - Object containing a datetime entry.</simpara></listitem>
      <listitem><simpara>
	object end - Object containing a datetime entry.</simpara></listitem>
      <listitem><simpara>
	int recur_type   - recurrence type</simpara></listitem>
      <listitem><simpara>
	int recur_interval   - recurrence interval</simpara></listitem>
      <listitem><simpara>
	datetime recur_enddate   - recurrence end date</simpara></listitem>
      <listitem><simpara>
	int recur_data   - recurrence data</simpara></listitem>
     </itemizedlist>

     All datetime entries consist of an object that contains:

     <itemizedlist>
      <listitem><simpara>
	int year - year</simpara></listitem>
      <listitem><simpara>
	int month - month</simpara></listitem>
      <listitem><simpara>
	int mday  - day of month</simpara></listitem>
      <listitem><simpara>
	int hour  - hour</simpara></listitem>
      <listitem><simpara>
	int min   - minutes</simpara></listitem>
      <listitem><simpara>
	int sec   - seconds</simpara></listitem>         
      <listitem><simpara>
	int alarm   - minutes before event to send an alarm</simpara></listitem>         
     </itemizedlist>

     The possible values for recur_type are:

     <itemizedlist>
      <listitem><simpara>
	0 - Indicates that this event does not recur</simpara></listitem>
      <listitem><simpara>
	1 - This event recurs daily</simpara></listitem>
      <listitem><simpara>
	2 - This event recurs on a weekly basis</simpara></listitem>
      <listitem><simpara>
	3 - This event recurs monthly on a specific day of the month (e.g. the 10th of the month)</simpara></listitem>
      <listitem><simpara>
	4 - This event recurs monthly on a sequenced day of the week (e.g. the 3rd Saturday) </simpara></listitem>
      <listitem><simpara>
	5 - This event recurs on an annual basis</simpara></listitem>         
     </itemizedlist></para>
   </refsect1>
  </refentry>


  <refentry id="function.mcal-list-events">
   <refnamediv>
    <refname>mcal_list_events</refname>
    <refpurpose>
     Return a list of IDs for a date or a range of dates.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>mcal_list_events</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
      <methodparam><type>object</type><parameter>begin_date</parameter></methodparam>
      <methodparam choice="opt"><type>object</type><parameter>end_date</parameter></methodparam>
     </methodsynopsis>
    <para>
     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.
    </para>
    <para> 
     <function>mcal_list_events</function> 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.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.mcal-append-event">
   <refnamediv>
    <refname>mcal_append_event</refname>
    <refpurpose>Store a new event into an MCAL calendar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_append_event</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
     </methodsynopsis>
    <para> 
     <function>mcal_append_event</function> Stores the global event
     into an MCAL calendar for the given stream.
    </para>
    <para>
     Returns the id of the newly inserted event.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.mcal-store-event">
   <refnamediv>
    <refname>mcal_store_event</refname>
    <refpurpose>Modify an existing event in an MCAL calendar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_store_event</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
     </methodsynopsis>
    <para> 
     <function>mcal_store_event</function> Stores the modifications
     to the current global event for the given stream.
    </para>
    <para>
     Returns &true; on success and &false; on error.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.mcal-delete-event">
   <refnamediv>
    <refname>mcal_delete_event</refname>
    <refpurpose>Delete an event from an MCAL calendar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_delete_event</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>event_id</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_delete_event</function> deletes the calendar event
     specified by the event_id.</para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-snooze">
   <refnamediv>
    <refname>mcal_snooze</refname>
    <refpurpose>Turn off an alarm for an event</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_snooze</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_snooze</function> turns off an alarm for a
     calendar event specified by the id.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-list-alarms">
   <refnamediv>
    <refname>mcal_list_alarms</refname>
    <refpurpose>
     Return a list of events that has an alarm triggered at the given
     datetime
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>mcal_list_alarms</methodname>
      <methodparam><type>int</type><parameter>mcal_stream</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>begin_year</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>begin_month</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>begin_day</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>end_year</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>end_month</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>end_day</parameter></methodparam>
     </methodsynopsis>
    <para>
     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.
    </para>
    <para> 
     <function>mcal_list_events</function> 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.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-init">
   <refnamediv>
    <refname>mcal_event_init</refname>
    <refpurpose>
     Initializes a streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_init</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_init</function> initializes a streams global
     event structure. this effectively sets all elements of the
     structure to 0, or the default settings.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-category">
   <refnamediv>
    <refname>mcal_event_set_category</refname>
    <refpurpose>
     Sets the category of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_category</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>category</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_category</function> sets the streams
     global event structure's category to the given string.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-title">
   <refnamediv>
    <refname>mcal_event_set_title</refname>
    <refpurpose>
     Sets the title of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_title</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>title</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_title</function> sets the streams global
     event structure's title to the given string.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-description">
   <refnamediv>
    <refname>mcal_event_set_description</refname>
    <refpurpose>
     Sets the description of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_description</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>description</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_description</function> sets the streams
     global event structure's description to the given string.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-start">
   <refnamediv>
    <refname>mcal_event_set_start</refname>
    <refpurpose>
     Sets the start date and time of the streams global event
     structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_start</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        day
       </parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        hour
       </parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        min</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        sec
       </parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_start</function> sets the streams global
     event structure's start date and time to the given values.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-end">
   <refnamediv>
    <refname>mcal_event_set_end</refname>
    <refpurpose>
     Sets the end date and time of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_end</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        day
       </parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        hour
       </parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        min
       </parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        sec
       </parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_end</function> sets the streams global
     event structure's end date and time to the given values.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-alarm">
   <refnamediv>
    <refname>mcal_event_set_alarm</refname>
    <refpurpose>
     Sets the alarm of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_alarm</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>alarm</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_alarm</function> sets the streams global
     event structure's alarm to the given minutes before the event.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-class">
   <refnamediv>
    <refname>mcal_event_set_class</refname>
    <refpurpose>
     Sets the class of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_class</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>class</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_class</function> sets the streams global
     event structure's class to the given value. The class is either 1
     for public, or 0 for private.
    </para>
    <para>
     Returns &true;.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.mcal-is-leap-year">
   <refnamediv>
    <refname>mcal_is_leap_year</refname>
    <refpurpose>
     Returns if the given year is a leap year or not
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_is_leap_year</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_is_leap_year</function> returns 1 if the given
     year is a leap year, 0 if not.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-days-in-month">
   <refnamediv>
    <refname>mcal_days_in_month</refname>
    <refpurpose>
     Returns the number of days in the given month
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_days_in_month</methodname>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>leap year</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_days_in_month</function> Returns the number of
     days in the given month, taking into account if the given year is
     a leap year or not.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-date-valid">
   <refnamediv>
    <refname>mcal_date_valid</refname>
    <refpurpose>
     Returns &true; if the given year, month, day is a valid date
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_date_valid</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_date_valid</function> Returns &true; if the given
     year, month and day is a valid date, &false; if not.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-time-valid">
   <refnamediv>
    <refname>mcal_time_valid</refname>
    <refpurpose>
     Returns &true; if the given year, month, day is a valid time
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_time_valid</methodname>
      <methodparam><type>int</type><parameter>hour</parameter></methodparam>
      <methodparam><type>int</type><parameter>minutes</parameter></methodparam>
      <methodparam><type>int</type><parameter>seconds</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_time_valid</function> Returns &true; if the given
     hour, minutes and seconds is a valid time, &false; if not.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-day-of-week">
   <refnamediv>
    <refname>mcal_day_of_week</refname>
    <refpurpose>
     Returns the day of the week of the given date
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_day_of_week</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_day_of_week</function> returns the day of the week
     of the given date.

	 Possible return values range from 0 for Sunday through 6 for Saturday. 
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-day-of-year">
   <refnamediv>
    <refname>mcal_day_of_year</refname>
    <refpurpose>
     Returns the day of the year of the given date
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_day_of_year</function> returns the day of the year
     of the given date.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-date-compare">
   <refnamediv>
    <refname>mcal_date_compare</refname>
    <refpurpose>Compares two dates</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_date_compare</methodname>
      <methodparam><type>int</type><parameter>a_year</parameter></methodparam>
      <methodparam><type>int</type><parameter>a_month</parameter></methodparam>
      <methodparam><type>int</type><parameter>a_day</parameter></methodparam>
      <methodparam><type>int</type><parameter>b_year</parameter></methodparam>
      <methodparam><type>int</type><parameter>b_month</parameter></methodparam>
      <methodparam><type>int</type><parameter>b_day</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_date_compare</function> Compares the two given
     dates, returns &lt;0, 0, >0 if a&lt;b, a==b, a>b respectively.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-next-recurrence">
   <refnamediv>
    <refname>mcal_next_recurrence</refname>
    <refpurpose>Returns the next recurrence of the event</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_next_recurrence</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>weekstart</parameter></methodparam>
      <methodparam><type>array</type><parameter>next</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_next_recurrence</function> 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.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-none">
   <refnamediv>
    <refname>mcal_event_set_recur_none</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_none</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_none</function> sets the streams
     global event structure to not recur (event->recur_type is set to
     MCAL_RECUR_NONE).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-daily">
   <refnamediv>
    <refname>mcal_event_set_recur_daily</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_daily</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>interval</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_daily</function> sets the streams
     global event structure's recurrence to the given value to be
     reoccuring on a daily basis, ending at the given date.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-weekly">
   <refnamediv>
    <refname>mcal_event_set_recur_weekly</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_weekly</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>interval</parameter></methodparam>
      <methodparam><type>int</type><parameter>weekdays</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_weekly</function> sets the streams
     global event structure's recurrence to the given value to be
     reoccuring on a weekly basis, ending at the given date.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-monthly-mday">
   <refnamediv>
    <refname>mcal_event_set_recur_monthly_mday</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_monthly_mday</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>interval</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_monthly_mday</function> 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.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-monthly-wday">
   <refnamediv>
    <refname>mcal_event_set_recur_monthly_wday</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_monthly_wday</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>interval</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_monthly_wday</function> 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.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-set-recur-yearly">
   <refnamediv>
    <refname>mcal_event_set_recur_yearly</refname>
    <refpurpose>
     Sets the recurrence of the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_event_set_recur_yearly</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>interval</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_set_recur_yearly</function> sets the streams
     global event structure's recurrence to the given value to be
     reoccuring on a yearly basis,ending at the given date.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-fetch-current-stream-event">
   <refnamediv>
    <refname>mcal_fetch_current_stream_event</refname>
    <refpurpose>
     Returns an object containing the current streams event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>mcal_fetch_current_stream_event</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_fetch_current_stream_event</function>
     returns the current stream's event structure as an object
     containing:

     <itemizedlist>
      <listitem><simpara>
	int id - ID of that event.</simpara></listitem>
      <listitem><simpara>
	int public - &true; if the event if public, &false; if it is
	private.</simpara></listitem>
      <listitem><simpara>
	string category - Category string of the event.</simpara></listitem> 
      <listitem><simpara>
	string title - Title string of the event.</simpara></listitem>
      <listitem><simpara>
	string description - Description string of the event.</simpara></listitem>
      <listitem><simpara>
	int alarm - number of minutes before the event to send an
	alarm/reminder.</simpara></listitem>
      <listitem><simpara>
	object start - Object containing a datetime entry.</simpara></listitem>
      <listitem><simpara>
	object end - Object containing a datetime entry.</simpara></listitem>
      <listitem><simpara>
	int recur_type   - recurrence type</simpara></listitem>
      <listitem><simpara>
	int recur_interval   - recurrence interval</simpara></listitem>
      <listitem><simpara>
	datetime recur_enddate   - recurrence end date</simpara></listitem>
      <listitem><simpara>
	int recur_data   - recurrence data</simpara></listitem>
     </itemizedlist>

     All datetime entries consist of an object that contains:

     <itemizedlist>
      <listitem><simpara>
	int year - year</simpara></listitem>
      <listitem><simpara>
	int month - month</simpara></listitem>
      <listitem><simpara>
	int mday  - day of month</simpara></listitem>
      <listitem><simpara>
	int hour  - hour</simpara></listitem>
      <listitem><simpara>
	int min   - minutes</simpara></listitem>
      <listitem><simpara>
	int sec   - seconds</simpara></listitem>         
      <listitem><simpara>
	int alarm   - minutes before event to send an alarm</simpara></listitem>         
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-event-add-attribute">
   <refnamediv>
    <refname>mcal_event_add_attribute</refname>
    <refpurpose>
     Adds an attribute and a value to the streams global event structure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>mcal_event_add_attribute</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>attribute</parameter></methodparam>
      <methodparam><type>string</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_event_add_attribute</function> adds an attribute
     to the stream's global event structure with the value given by
     "value".
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mcal-expunge">
   <refnamediv>
    <refname>mcal_expunge</refname>
    <refpurpose>
     Deletes all events marked for being expunged.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mcal_expunge</methodname>
      <methodparam><type>int</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>  
     <function>mcal_expunge</function> Deletes all events which have
     been previously marked for deletion.
    </para>
   </refsect1>
  </refentry>

</reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->