Subject: Multiple types for properties

From: Eric Busboom <[email-masked]>
Date: Wed, 02 Jun 1999 12:21:26 -0700

The following are notes that I have from my experience in implementing a C library for the iCAL core objects and iTIP. ( see http://softwarestudio.org/libical/ )  I have several notes, so I will send several emails, one topic per email, to make discussions easier to sort out. 

The basic idea behind these notes is that the people who will most frequently interact directly with the iCAL protocols are those that are writing calendaring programs, so the protocol specifications should not require implementations to have strange interfaces.  I think that a protocol implementation's interface should have a structure that is similar to the protocol, so that the protocol specification is a major part of the documentation for the implementation. These notes point out places where these ideas are violated. 

eric. 

---------------------------------------------------------------------------------------------------------------------- 

Multiple Types for a Property
-----------------------------

Many properties can have more than one value, differentiated by the
VALUE parameter:

   Values                       Used in Property
   ------------------------------------------------
   URI or BINARY.  		ATTACH
   DATE or DATE-TIME.	DUE, DTSTART, DTEND, RECURRENCE-ID and  EXDATE
   DATE or DATE-TIME or 
   PERIOD  			RDATE
   DATE-TIME or DURATION. 	TRIGGER

Having multiple value types for a property makes creating a strong typed interface difficult. Either the client code will have to check the value type and call the appropriate accessor function to get the value:
 
        if ( value is a uri )
                get_uri_value()
        else
                get_binary_value()

 or the interface will have to combine the values into an
aggregate type.

        struct uriorbinary {
                uri
                binary 
        } v;

        struct uriorbinary get_value();	

The first model is very inconvenient and error prone, and the second creates an interface that does not map to the RFC.

Most of the overlap in value types is for types related to time, and they are all very similar. A DATE is a DATE-TIME without the time part, and a PERIOD is (mostly) a combination of two DATE-TIME values.

An implementation could, it seems, combine DATE, TIME, DATE-TIME, PERIOD and DURATION into a smaller set of type , if the types made a distinction between absolute time value and relative time values.  For instance, the machine representation for DATE, TIME and DATE-TIME in most implementations would probably be a common time type, like time_t ( an integer type representing seconds since Jan 1 1970. ) on UNIX.  DURATION can also be represented as a single integer value. 

I want to stay close to the specification so that the specification can be used to document my implementation, so I combine these types into aggregates based on how they are used: URI & BINARY, DATE & DATE-TIME, DATE, DATE-TIME & PERIOD,  DATE-TIME & DURATION. But, this still creates artificial new types that can probably be officially handled by the specification. 

Unnecessary VALUE parameter 
---------------------------

In each of the cases above, the VALUE parameter is used to resolve which of the overloaded value types should be used. However, all of the value types are syntactically different enough to make the use of the VALUE parameter unnecessary.