Ruby/CorporateTime - a Ruby interface to 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.
CTime objects possess the following attributes:
@agendas - an array of e-mail addresses, 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.
Event objects may possess the following attributes:
@uid - the unique identifier for this event in the calendar system
@start - the start time of the event, specified in the same format used for start and finish.
@duration - the duration of the event, whose format matches the regular expression 'P\dDT\d+H\d+M00S'. The end time of the event can thus be obtained as follows:
year, month, day, hours, mins, secs =
/^(\d{4})(\d\d)(\d\d)T(\d\d)(\d\d)(\d\d)Z$/.match(event.start)[1..6]
start = Time.gm(year, month, day, hours, mins, secs)
hours, mins, secs = /^P\dDT(\d+)H(\d+)M(\d+)S$/.match(e.duration)[1..3]
end = start + hours.to_s.to_i * 3600 + mins.to_s.to_i * 60 +
secs.to_s.to_i
Note that CorporateTime expects all times to be specified in UTC, so you may need to perform conversion to local time:
start.localtime end.localtime
@location - the location where the event will be held
@description - text detailing the purpose of and reasons for the event
CTime#open_agenda(user)This opens the agenda of the specified user.
Upon success, the e-mail address of the specified user 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(email)This closes the agenda of the user specified by email. An AgendaError exception will be raised if no such agenda is open. Otherwise, email is returned.
CTime#get_events(start, finish, properties)This fetches a range of events from start to finish. The format of these parameters is 'yyyymmddThhmmssZ', where the T and the Z are literal characters. properties should be either CTime::ALL_PROPERTIES or CTime::RESTRICTED_PROPERTIES. The latter is required to retrieve the start time and duration of events whose access level has been restricted to allow viewing of these attributes only.
The current date and time could be formatted to this template as follows:
require 'date'
today = Date.today
start = sprintf("%s%02d%02dT080000Z", today.year, today.month, today.day)
On success, an array of Event objects will 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, @duration and @summary attributes of event should not be nil, or an exception will be raised.
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.
Passing this to CTime#get_events causes all event properties to be returned and assigned to attributes of Event class objects.
Passing this to CTime#get_events will cause just the @start and @duration attributes of Event objects to be set.
The version number of Ruby/CorporateTime
Written by Ian Macdonald <ian@caliban.org>
Copyright (C) 2002-2003 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. In particular, CAPI 2.5 doesn't work for me, so it may be best to stick with CAPI 2.0 for now. Send all bug reports, enhancement requests and patches to the author.
$Id: ctime.rd,v 1.1 2002/09/25 04:30:34 ianmacd Exp $