OSID Logo
OSID Specifications
calendaring package
Version 3.0.0
Release Candidate Preview
Interfaceosid.calendaring.EventLookupSession
Implementsosid.OsidSession
Description

This session provides methods for retrieving Event s.

This session defines views that offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition
  • isolated calendar view: All event methods in this session operate, retrieve and pertain to events defined explicitly in the current calendar. Using an isolated view is useful for managing events with the EventAdminSession.
  • federated calendar view: All event methods in this session operate, retrieve and pertain to all events defined in this calendar and any other calendars implicitly available in this calendar through calendar inheritence.
  • effective event view: All events lookup methods return events where the current date falls in between the effective dates inclusive.
  • any effective event view: Events of any effective date are returned from methods.
  • denormalized event view: recurring events are expanded into a series of non-recurring events
  • normalized event view: recurring events are represented by a single event
  • sequestered event viiew: All event methods suppress sequestered events.
  • unsequestered event view: All event methods return all events.

Events may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Event.

MethodgetCalendarId
Description

Gets the Calendar Id associated with this session.

Returnosid.id.Idthe Calendar Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetCalendar
Description

Gets the Calendar associated with this session.

Returnosid.calendaring.Calendarthe Calendar associated with this session
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupEvents
Description

Tests if this user can perform Event lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.

Returnboolean false if lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeEventView
Description

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

CompliancemandatoryThis method is must be implemented.
MethodusePlenaryEventView
Description

A complete view of the Event returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

CompliancemandatoryThis method is must be implemented.
MethoduseFederatedCalendarView
Description

Federates the view for methods in this session. A federated view will include events in calendars which are children of this calendar in the calendar hierarchy.

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedCalendarView
Description

Isolates the view for methods in this session. An isolated view restricts lookups to this calendar only.

CompliancemandatoryThis method is must be implemented.
MethoduseEffectiveEventView
Description

Only events whose effective dates are current are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveEventView
Description

All events of any effective dates are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethoduseNormalizedEventView
Description

A normalized view uses a single Event to represent a set of recurring events.

CompliancemandatoryThis method is must be implemented.
MethoduseDenormalizedEventView
Description

A denormalized view expands recurring events into a series of Events.

CompliancemandatoryThis method is must be implemented.
MethoduseSequesteredEventView
Description

The returns from the lookup methods omit sequestered events.

CompliancemandatoryThis method is must be implemented.
MethoduseUnsequesteredEventView
Description

All events are returned including sequestered events.

CompliancemandatoryThis method is must be implemented.
MethodgetEvent
Description

Gets the Event specified by its Id.

In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Event may have a different Id than requested, such as the case where a duplicate Id was assigned to an Event and retained for compatibility.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdeventId Id of the Event
Returnosid.calendaring.Eventthe event
ErrorsNOT_FOUND eventId not found
NULL_ARGUMENT eventId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodgetEventsByIds
Description

Gets an EventList corresponding to the given IdList.

In plenary mode, the returned list contains all of the events specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Events may be omitted from the list and may present the elements in any order including returning a unique set.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdListeventIdsthe list of Ids to retrieve
Returnosid.calendaring.EventListthe returned Event list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT eventIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByGenusType
Description

Gets an EventList corresponding to the given event genus Type which does not include events of genus types derived from the specified Type.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.type.TypeeventGenusTypean event genus type
Returnosid.calendaring.EventListthe returned Event list
ErrorsNULL_ARGUMENT eventGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByParentGenusType
Description

Gets an EventList corresponding to the given event genus Type and include any additional event with genus types derived from the specified Type.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.type.TypeeventGenusTypean event genus type
Returnosid.calendaring.EventListthe returned Event list
ErrorsNULL_ARGUMENT eventGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByRecordType
Description

Gets an EventList containing the given event record Type.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

Parametersosid.type.TypeeventRecordTypean event record type
Returnosid.calendaring.EventListthe returned Event list
ErrorsNULL_ARGUMENT eventRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsOnDate
Description

Gets a list of events where the given date range falls within an event inclusive.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsInDateRange
Description

Gets an EventList that fall within the given range inclusive .

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.calendaring.DateTimefromstart date
osid.calendaring.DateTimetoend date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetUpcomingEvents
Description

Gets the next upcoming events on this calendar.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parameterscardinalnumberthe number of events
Returnosid.calendaring.EventListthe returned Event list
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByLocation
Description

Gets a list of events with the given location.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdlocationIda location
Returnosid.calendaring.EventListthe returned Event list
ErrorsNULL_ARGUMENT locationId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByLocationOnDate
Description

Gets an EventList at the given location where the given date range falls within the event dates inclusive.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdlocationIda location
osid.calendaring.DateTimefromstart date
osid.calendaring.DateTimetoend date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT locationId, from , or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsByLocationInDateRange
Description

Gets an EventList that fall within the given range inclusive at the given location .

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdlocationIda location
osid.calendaring.DateTimefromstart date
osid.calendaring.DateTimetoend date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT locationId, from , or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsBySponsor
Description

Gets a list of events with the given sponsor.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdresourceIda sponsor
Returnosid.calendaring.EventListthe returned Event list
ErrorsNULL_ARGUMENT resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsBySponsorOnDate
Description

Gets an EventList with the given sponsor where the given date range falls within the event dates inclusive.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdresourceIda sponsor
osid.calendaring.DateTimefromstart date
osid.calendaring.DateTimetoend date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEventsBySponsorInDateRange
Description

Gets an EventList that fall within the given range inclusive at the given location .

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Parametersosid.id.IdresourceIda sponsor
osid.calendaring.DateTimefromstart date
osid.calendaring.DateTimetoend date
Returnosid.calendaring.EventListthe returned Event list
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEvents
Description

Gets all Events.

In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session.

In normalized mode, recurring events appear as a single event. In denormalized mode, each element in the recurring series appears as a separate event.

In effective mode, events are returned that are currently effective. In any effective mode, effective events and those currently expired are returned.

In sequestered mode, no sequestered events are returned. In unsequestered mode, all events are returned.

Returnosid.calendaring.EventListan EventList
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.