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. 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 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
Note also that CAPI 2.5 and later return nil for @duration.
@end - the end time of the event, specified in the same format used for start and finish.
Note that CAPI 2.0 returns nil for @end.
@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)CTime#get_events(start, finish)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.
An attempt will be made to retrieve all properties for the events found. If this is unsuccessful (due to server-side restrictions), a second attempt will be made to request just the start and end times, pluys the duration.
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.
Note that the @start and @end attributes of the Event objects returned will be strings of the format 'yyyymmddThhmmssZ' for plain events, but identical strings of the format 'yyyymmdd' for all-day events.
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. 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.
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.4 2003/11/13 11:02:11 ianmacd Exp $