| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: NatrounAPI | Next |
The Natroun API defines the way that the Cairo Application Object Server communicates with storage devices. It is a simple API with required and optional methods. All Natroun method names have two underscores leading and trailing them because all Casbah objects can use the NatrounAPI to implement accessor's to themselves. Natroun drivers are just Casbah objects that support all of the required methods.[1]
Every Natroun method takes a reference to an object. This reference is always a CaList containing elements that describe the object that the method's action is to be taken on. Three different types of elements are allowed in this list: CaString, CaUInt32, and CaObject (used to hold object handles).
CaStrings in the list are considered the name of an element in a table, class or CaDict. CaUInt32 elements are treated specially and signal the Natroun driver to alter its behavior while processing the list. Any other object type is considered an object handle. Object handles must occur only as the first element. Therefore, elements 1 through the end of the list must be either of type CaString or CaUInt32. Object handles may be any class created by the Natroun driver author; they and may contain any information that the Natroun driver needs them to contain.
All Conformant Natroun Driver must be able to handle the special case path where the path list contains no elements. This case is a request for the top level of the Natroun driver's namespace. In order to request all of the instance variables for a driver, you must use the path /^/ in the parent Natroun driver, allowing the parent driver to handle the request.
Additionally, any Conformant Natroun Drivers which support the (optional) __cb_lock__ method must allow the terminal element of any path list to be a CaBinary object. The terminal element must be the lock token granted by __cb_lock__ at some point in time. An application may invoke __cb_monitor__, __cb_unmonitor__, __cb_delete__ and __cb_stat__ on this special path. For all other operations the driver may throw an exception.
All Conformant Natroun Drivers must support all of the required tokens in the following list. If a Natroun driver encounters a token that it does not understand, it must throw an exception. It should be noted that Natroun drivers are required to process the path list in order, such that if the token "56" was present in the path list after a reference to another Natroun driver was used, the parent driver must pass this token through to the sub-driver without error. This is to allow Natroun drivers to define their own tokens.
Table 1. Tokens in Path List
Status | Value | Meaning |
|---|---|---|
optional | 1 | This element was the element ":". The driver must aquire the following element (and only the following element) using aquisition. |
required | 2 | This element was the element "^". The driver must treat the next element literally, and not pass it through special processing. If the next element in the list names a Natroun driver instance, this driver must not pass the call to the Natroun driver. Instead this driver must handle the call itself. (This allows Natroun drivers to access themselves.) Additionally, if the next element names a link, the link object itself must be operated on, not the item the link refers to. |
required | 3 | The next element in the path list is an index into a list, for e.g., "[12]". The next element is a CaUInt32 holding the index. This next element must not be viewed as a token. |
API / User Division | 2,147,483,647 | All tokens before 2,147,483,647 are reserved for later drafts of the Natroun API. All tokens after 2,147,483,647 are reserved for Natroun driver developers. |
| [1] | Natroun methods that modify a resource can return an error on read-only datastores. These methods must be provided in order to send back the error "read only". If they are not provided, the useless error message "method not found" would be returned. |