documentation: On `METHOD: ADD`

[acaird]

[This is mostly a documentation comment to help people understand what the SetMethod method is for and why it might impact importing the resulting iCal file]

This library includes the option for setting the METHOD for a set of events. In calendar.go SetMethod is defined

func (calendar *Calendar) SetMethod(method Method, props ...PropertyParameter) {
        calendar.setProperty(PropertyMethod, ToText(string(method)), props...)
}

and the Method* variables are defined:

type Method string

const (
        MethodPublish        Method = "PUBLISH"
        MethodRequest        Method = "REQUEST"
        MethodReply          Method = "REPLY"
        MethodAdd            Method = "ADD"
        MethodCancel         Method = "CANCEL"
        MethodRefresh        Method = "REFRESH"
        MethodCounter        Method = "COUNTER"
        MethodDeclinecounter Method = "DECLINECOUNTER"
)

These should be used with caution when creating simple iCal (.ics) files.

The iCalendar specification is defined in RFC 5545. It refers to RFC 5546, which defines the ADD method as:

The “ADD” method allows the “Organizer” to add one or more new instances to an existing “VEVENT” using a single iTIP message without having to send the entire “VEVENT” with all the existing instance data, as it would have to do if the “REQUEST” method were used.

The “UID” must be that of the existing event. If the “UID” property value in the “ADD” is not found on the recipient’s calendar, then the recipient SHOULD send a “REFRESH” to the “Organizer” in order to be updated with the latest version of the “VEVENT”. If an “Attendee” implementation does not support the “ADD” method, it should respond with a “REQUEST-STATUS” value of 3.14 and ask for a “REFRESH”.

If you include the line METHOD: ADD in your .ics file (or *ics.Calendar.SetMethod(ics.MethodAdd), it is required to refer to existing calendar events. There are certainly cases where this is what you intend, but if you are simply writing .ics files to import into calendaring tools, it is not likely that you will want to use this option.

If you do use ics.MethodAdd and find that your events aren’t being imported, this may be why. Notably, the Apple Calendar program will (correctly) reject events in .ics files that have this set; some other calendars (Microsoft Outlook, for example) have a more permissive import process and will accept the events in an .ics file that includes the METHOD: ADD line even if they do not refer to existing calendar events.

[arran4]

Thanks. When I get around to addressing issues, I will consider a validate helper too.