Ruby/CorporateTime - A Ruby interface to Oracle/Steltor's CorporateTime calendar.
require 'ctime'
ct = CTime.new(server, user, passwd)
unless ct.error == "CAPI_STAT_OK"
$stderr.puts "Failed to connect to #{server} as #{user}"
exit 1
end
Ruby/CorporateTime is a Ruby interface to the Steltor Calendar API (CAPI). Using this library, it's possible to perform most of the common tasks required in daily calendar usage: connect to the server; open and close agendas; work as a designate of another user; schedule, list and delete events; disconnect from the server.
CTime.new(server, user, password)This creates a new instance of the CTime class. Note that if you are using version 2.5x of the Steltor CAPI, you must include the server's port number as a part of server, e.g. foo.bar.com:5730
CTime objects possess the following attributes:
@agendas - an array of Agenda objects, corresponding to open agendas. This will be empty upon return, but calls to CTime#open_agenda will populate it and calls to CTime#close_agenda will remove elements from it.
@capabilities - a hash of server capabilities. The authentication, compression, encryption, unsupported_ical_prop and unsupported_ical_comp elements are returned as arrays. The max_date, capi_version, version and server_version elements are simple strings.
@error - all the instance methods set this attribute to indicate their success or type of failure
Event.new(start, duration, summary, location, description)This creates a new instance of the Event class.
If start is passed as String objects, the format should be 'yyyymmddThhmmssZ', where the T and the Z are literal characters. The time should be specified in UTC.
If start is an object that respond to the gmtime or new_offset methods, its values will be automatically converted to UTC. Otherwise, this step will need to be performed manually. For example, a Time object can be automatically converted using gmtime and a DateTime object can be converted using new_offset.
duration should be an Integer, while summary, location and description should be String objects.
Event objects you create and those returned by other methods, such as Ctime#get_events may possess the following attributes:
@uid - The unique identifier for this event in the calendar system.
@start_time - The start time of the event, returned as a Time object unless you have set it to something else.
@end_time - The end time of the event, returned as a Time object unless you have set it to something else.
@duration - The duration of the event in seconds.
Note that CorporateTime expects all times to be specified in UTC, so you may need to perform conversion to local time:
start_time.localtime end_time.localtime
@location - The location where the event will be held.
@description - Text detailing the purpose of and reasons for the event.
@attendees - An Array of Attendee objects for the attendees of the event. This is returned by CTime#get_events, but is currently not used by CTime#set_event.
@ics - the raw iCalendar stream pertaining to the event. Another way to view this is with Event#inspect.
Agenda.new()This creates a new instance of the Agenda class.
Agenda objects may possess the following attributes:
@type - The type of the agenda (person, resource).
@name - The name of the agenda.
@mailto - the e-mail address for the agenda. Note that resources don't have an e-mail address.
Attendee.new()This creates a new instance of the Attendee class.
Attendee objects may possess the following attributes:
@mailto - The e-mail address of the attendee.
@cn - The name of the attendee.
@partstat - The participant status of the attendee.
@role - The role of the attendee.
@cutype - The calendar user type of the attendee.
CTime#open_agenda(user)This opens the agenda of the specified user.
Upon success, an Agenda object is returned and the @agendas array is extended accordingly. If the agenda cannot be opened or does not exist, an AgendaError exception will be raised.
CTime#close_agenda(agenda)CTime#get_events(start, finish, parse_events=true)This fetches a range of events from start to finish. start and finish may be String objects or any object that responds to the strftime method.
If start and finish are passed as String objects, the format of these parameters is yyyymmddThhmmssZ, where the T and the Z are literal characters. The time should be specified in UTC.
If start and finish are objects that respond to the gmtime or new_offset methods, their values will be automatically converted to UTC. Otherwise, this step will need to be performed manually. For example, Time objects can be automatically converted using gmtime and DateTime objects can be converted using new_offset.
On success, an array of Event objects will be returned if parse_events is true. If parse_events is false, a string containing the raw iCalendar data will be returned instead.
In the event that not all properties can be retrieved for the events found (due to server-side access restrictions), the properties that are unrestricted will still be returned.
An AgendaError exception will be raised if no agenda is open. nil is returned if the operation fails for a different reason.
CTime#designate(user)This method allows you to perform work as user, assuming the necessary privileges have been granted.
On success, true is returned. An AgendaError exception will be raised if there are insufficient privileges. An UnknownUser exception will be raised if user is unknown. nil will be returned on any other kind of error.
CTime#set_event(event)This allows you to set an event in the calendar system. event should be an instance of class Event. If the uid attribute of the object is set and an event with a matching UID is present on the server, the event will be modified. Otherwise, a new event will be created.
The @start_time, @duration and @summary attributes of event should not be nil, or an exception will be raised. Note that it is currently not possible to set an all-day event.
A UID will be returned on success. An AgendaError exception will be raised if no agendas are open. nil will be returned on any other kind of error.
CTime#delete_event(uid)This deletes the event matching uid from the server.
true will be returned on success. An EventError will be raised if no matching event is found. nil will be returned in the event of any other error.
Event#start_time_strEvent#end_time_strEvent#inspectEvent#to_sAttendee#inspectWritten by Ian Macdonald <ian@caliban.org>
Copyright (C) 2002-2004 Ian Macdonald This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This library was authored by me and written in C, so you bet there are bugs.
$Id: ctime.rd,v 1.13 2004/11/07 05:27:17 ianmacd Exp $