Ruby/CorporateTime - A Ruby interface to Oracle/Steltor's CorporateTime calendar.
require 'ctime' start_date = DateTime.now end_date = start_date + 7 ct = CTime.new.connect( 'foo.bar.com:5730', 'wold', 'secret' ) agenda = ct.open_agenda( 'ianmacd' ) events = agenda.get_events( start_date, end_date )
Ruby/CorporateTime is a Ruby interface to the Oracle/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. For compatibility with earlier versions of Ruby/CorporateTime, versions from 0.4.0 onwards allow you to specify server, user and password here. See CTime#connect.
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::Agenda::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 responds to either the gmtime or the new_offset method, 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::Agenda#get_event and Ctime::Agenda#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 if you are inspecting Event objects that have been returned by CTime::Agenda#get_event or CTime::Agenda#get_events.
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::Agenda#get_event and CTime::Agenda#get_events, but is used by CTime::Agenda#set_event only if Ruby/CorporateTim is compiled against the CAPI v9 libraries.
@organizer/@organiser - The e-mail address of the event's organiser.
@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#connect(server, user, password) { ... }This connects to server as user, using password and returns self. If a block is given, the connection object is passed into it and destroyed again when the block completes.
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#capabilitiesCTime#designate(user)This method allows you to perform work as user, assuming the necessary privileges have been granted.
On success, true is returned. A DesignationError exception will be raised if there are insufficient privileges or if user is unknown.
CTime#open_agenda(user) { ... }This opens the agenda of the specified user.
Upon success, an Agenda object is returned. If a block is provided, the agenda object will be passed into it and closed when the block is completed. If the agenda cannot be opened or does not exist, an AgendaError exception will be raised.
CTime::Agenda#closeCTime::Agenda#get_event(uid)This fetches the events associated with uid.
On success, an array of Event objects will be returned.
If a block is provided, each Event returned will be yielded to the block in turn.
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 be returned.
A CAPIError exception will be raised if no agenda is open.
CTime::Agenda#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.
If a block is provided, each Event returned will be yielded to the block in turn.
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.
A CAPIError exception will be raised if no agenda is open.
CTime::Agenda#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 on failure.
CTime::Agenda#delete_event(uid)This deletes the event matching uid from the server.
true will be returned on success. An AgendaError will be raised if no matching event is found.
CTime::Agenda#reply(event)This method updates an event with a new attendee list.
This method is experimental and only available when Ruby/CorporateTime is compiled against the CAPI v9 libraries.
CTime::Agenda::Event#start_time_strCTime::Agenda::Event#end_time_strCTime::Agenda::Event#inspectCTime::Agenda::Event#to_sAttendee#inspectWritten by Ian Macdonald <ian@caliban.org>
Copyright (C) 2002-2005 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.23 2005/03/15 23:59:28 ianmacd Exp $