OSID Logo
OSID Specifications
room package
Version 3.0.0
Release Candidate Preview
Interfaceosid.room.RoomLookupSession
Implementsosid.OsidSession
Description

This session defines methods for retrieving rooms.

This lookup session defines several views:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition
  • isolated campus view: All room methods in this session operate, retrieve and pertain to rooms defined explicitly in the current campus. Using an isolated view is useful for managing rooms with the RoomAdminSession.
  • federated campus view: All room lookup methods in this session operate, retrieve and pertain to all rooms defined in this campus and any other campuses implicitly available in this campus through campus inheritence.
  • effective room view: All room lookup methods return effective rooms.
  • any effective room view: Rooms of any effective date are returned.

The methods useFederatedCampusView() and useIsolatedCampusView() behave as a radio group and one should be selected before invoking any lookup methods.

MethodgetCampusId
Description

Gets the Campus Id associated with this session.

Returnosid.id.Idthe Campus Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetCampus
Description

Gets the Campus associated with this session.

Returnosid.room.Campusthe campus
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupRooms
Description

Tests if this user can lookup rooms. 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 these operations.

Returnboolean false if room lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeRoomView
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.
MethodusePlenaryRoomView
Description

A complete view of the Room 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.
MethoduseFederatedCampusView
Description

Federates the view for methods in this session. A federated view will include rooms in campuses which are children of this campus in the campus hierarchy.

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedCampusView
Description

Isolates the view for methods in this session. An isolated view restricts retrievals to this campus only.

CompliancemandatoryThis method is must be implemented.
MethoduseEffectiveRoomView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveRoomView
Description

Rooms of any effective dates are returned by all methods in this session.

CompliancemandatoryThis method is must be implemented.
MethodgetRoom
Description

Gets the Room specified by its Id.

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

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

Parametersosid.id.IdroomIdthe Id of the Room to retrieve
Returnosid.room.Roomthe returned Room
ErrorsNOT_FOUNDno Room found with the given Id
NULL_ARGUMENT roomId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByIds
Description

Gets a RoomList corresponding to the given IdList.

In plenary mode, the returned list contains all of the rooms 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 rooms may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IdListroomIdsthe list of Ids to retrieve
Returnosid.room.RoomListthe returned Room list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT roomIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByGenusType
Description

Gets a RoomList corresponding to the given room genus Type which does not include rooms of genus types derived from the specified Type.

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

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

Parametersosid.type.TyperoomGenusTypea room genus type
Returnosid.room.RoomListthe returned Room list
ErrorsNULL_ARGUMENT roomGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByParentGenusType
Description

Gets a RoomList corresponding to the given room genus Type and include any additional rooms with genus types derived from the specified Type.

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

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

Parametersosid.type.TyperoomGenusTypea room genus type
Returnosid.room.RoomListthe returned Rooms list
ErrorsNULL_ARGUMENT roomGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByRecordType
Description

Gets a RoomList containing the given room record Type.

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

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

Parametersosid.type.TyperoomRecordTypea room record type
Returnosid.room.RoomListthe returned Rooms list
ErrorsNULL_ARGUMENT roomRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsOnDate
Description

Gets a list of all rooms effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.room.RoomListthe returned RoomList
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.
MethodgetRoomsByGenusTypeOnDate
Description

Gets a list of all rooms of a genus type effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.type.TyperoomGenusTypea room genus Type
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.room.RoomListthe returned RoomList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT roomGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsForBuilding
Description

Gets a list of all rooms corresponding to a building Id.

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

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

Parametersosid.id.IdbuildingIdthe Id of the building
Returnosid.room.RoomListthe returned RoomList
ErrorsNULL_ARGUMENT buildingId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsForBuildingOnDate
Description

Gets a list of all rooms corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IdbuildingIda building Id
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.room.RoomListthe returned RoomList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT buildingId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByGenusTypeForBuilding
Description

Gets a list of all rooms of the given genus type corresponding to a building Id.

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

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

Parametersosid.id.IdbuildingIdthe Id of the building
osid.type.TyperoomGenusTypea room genus type
Returnosid.room.RoomListthe returned RoomList
ErrorsNULL_ARGUMENT buildingId or roomGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByGenusTypeForBuildingOnDate
Description

Gets a list of all rooms of the given genus type corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IdbuildingIda building Id
osid.type.TyperoomGenusTypea room genus type
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.room.RoomListthe returned RoomList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT buildingId, roomGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsForFloor
Description

Gets a list of all rooms corresponding to a floor Id.

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

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

Parametersosid.id.IdfloorIdthe Id of the building
Returnosid.room.RoomListthe returned RoomList
ErrorsNULL_ARGUMENT floorId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsForFloorOnDate
Description

Gets a list of all rooms corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range.

Rooms are returned with start effective dates that fall between the requested dates inclusive. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session.

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

Parametersosid.id.IdfloorIda building Id
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.room.RoomListthe returned RoomList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT floorId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByGenusTypeForFloor
Description

Gets a list of all rooms of the given genus type corresponding to a floor Id.

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

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

Parametersosid.id.IdfloorIdthe Id of the floor
osid.type.TyperoomGenusTypea room genus type
Returnosid.room.RoomListthe returned RoomList
ErrorsNULL_ARGUMENT floorId or roomGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByGenusTypeForFloorOnDate
Description

Gets a list of all rooms of the given genus type corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range.

Rooms are returned with start effective dates that fall between the requested dates inclusive. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session.

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

Parametersosid.id.IdfloorIda floor Id
osid.type.TyperoomGenusTypea room genus type
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.room.RoomListthe returned RoomList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT floorId, roomGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoomsByRoomNumber
Description

Gets a list of all rooms of the given room number.

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

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

Parametersstringnumbera room number
Returnosid.room.RoomListthe returned RoomList
ErrorsNULL_ARGUMENT number is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRooms
Description

Gets all rooms.

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

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

Returnosid.room.RoomLista list of rooms
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.