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 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.
Event objects 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
@start_time_str - the start time of the event, specified in the same format used for start and finish.
@end_time - the end time of the event, returned as a Time
@end_time_str - the end time of the event, specified in the same format used for start and finish.
@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 get_events, but is currently not used by set_event.
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 email address for the agenda. Note that resources don't have an email address.
Attendee.new()This creates a new instance of the Attendee class.
Attendee objects may possess the following attributes:
@mailto - the email 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)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.
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.
Written 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.6 2004/05/26 03:56:30 ianmacd Exp $