The Casbah Project: APIs and Reference Manual: Developer's Release 1
Prev	Cairo Public Interface (CairoAdapter)	Next

Cairo Public Interface Instance Methods

`get()`

Table 2. get()

Return Type	Method Name	Method Arguments
CaObject	`get()`	(CaObject path, CaDict opts)

get() fetches an object from the server [[which server?]] and returns it. For atomic values, get() must by default return the value directly.[1] For non-atomics, __cb_get__ must by default return a proxy to the object instance on the server. This default behavior may be modified using an option supplied in opts. __cb_get__ may also be used to get handles to objects.

Table 3. get() Required Options

Name	Type	Meaning	Default Value
recurse-depth	CaInt32	The number of levels deep to copy this object. A depth of 0 means just the object's immediate atomic values; a depth of 1 means to copy this object, its immediates, its children and their immediates. Any objects not copied must have proxies returned for them. A recurse-depth of -1 is special, asking that a proxy must be returned for this object itself. An application may ask for all objects by using the recurse-deth of 2,147,483,647. A Conformant Natroun Driver must ignore this option for any object that is not a CaList or CaDict.	-1
accept-types	CaList of CaString	A list of the datatypes that the application can handle as a result from `__cb_get__`. If the object's datatype does not match one of the datatypes named in this list, the object must either be converted to one of the types named in this list, or the driver must return an error. An entry of `*` should be interpreted as matching any datatype.	{*}
get-object-handle	CaBoolean	If set to true, the driver must return a handle to the object instead of the object itself. See the The Casbah Project: NatrounAPI for more information.	FALSE
stream-handle	CaUInt32	Opens a stream handle on the specified object, allowing the caller to do file-like IO operations such as read, write and seek. See the The Casbah Project: NatrounAPI for more information about streams and the values this option may contain.	0

`put()`

Table 4. put()

Return Type	Method Name	Method Arguments
CaBoolean	`put()`	(CaObject path, CaObject value, CaDict opts)

Stores a value at a path, completely replacing path. Should the operation fail, path must be left intact as if put() wasn't called.

options is a CaDict providing a variable number of arguments to the Natroun drivers encountered along the path supplied.

Table 5. put() Required Options

Name	Type	Meaning	Default Value
store-as	CaString	Converts value to the Casbah object type named in this option. If the driver cannot do the conversion, it must signal an error and leave path unmodified.	not supplied

`delete()`

Table 6. delete()

Return Type	Method Name	Method Arguments
CaBoolean	`delete()`	(CaObject path)

Deletes everything at path recursively. Should the operation fail, path must be left intact as if __cb_delete__ wasn't called.

If the Natroun driver supports __cb_lock__ and __cb_monitor__ and the last element of path is of type CaBinary delete must act as if __cb_unlock__ was called on the lock token which was supplied as the last element of path.

`stat()`

Table 7. stat()

Return Type	Method Name	Method Arguments
CaDict	`stat()`	(CaObject path, CaDict options)

Gets summarized information for the object at path. This information must be returned in a CaDict, where the keys are from the following table. Required keys must be supported by all Cairo Public Interface implementations, while optional keys may be supported. Keys whose class is default must be returned as part of the status information for each object.

All Conformant Natroun Drivers which support __cb_lock__, must also support the keys which are marked with "__cb_lock__-required".

Table 8. Result Keys and Meanings

Required	Class	Key	Value Type	Meaning
required	default	value	depends[[!]]	The value will depend on the object itself and its datatypes. See the Datatype and Value Mappings for a complete description of this key. There is an exception: If the item is a lock-token, the entire lock token must be returned, not just the first 32 bytes.
required	default	size	CaUInt64	Contains the size of an object. This varies based on the object type. See the Datatype and Value Mappingsfor a description of what this key should hold for varying object types.
required	default	type	CaString	Contains the actual type of the object. Types must be in Casbah type notation (See Casbah Datatypes). If the object is a CaDict and contains the key `class`, this key must contain the value of the dict's `class` member.
optional	specified	last-accessed	CaDateTime	Date and time of last access (read). Some drivers may not store this information. This information must only be available on items of type CaDict; all other items must not have this information attached to them.
optional	specified	last-modified	CaDateTime	Date and time of last modification (write). Some drivers may not store this information. This information must only be available on items of type CaDict, all other items must not have this information attached to them.
optional	specified	created	CaDateTime	Date and time this object was created. Some drivers may not store this information. This information must only be available on items of type CaDict, all other items must not have this information attached to them.
optional	specified	created-by	CaString	User (in form "user@realm") that created the object. Some drivers may not store this information. This information must only be available on items of type CaDict, all other items must not have this information attached to them.
`__cb_lock__`-required	specified by `get-lock-tokens`	lock-owner	CaString	User that holds this lock token.
`__cb_lock__`-required	specified by `get-lock-tokens`	lock-granted-at	CaDateTime	Date and time that the lock token was granted. If the lock as not been granted yet, this key is nonsensical and therefore must be ignored by applications.
`__cb_lock__`-required	specified by `get-lock-tokens`	lock-granted	CaBoolean	Has this token been granted yet?
`__cb_lock__`-required	specified by `get-lock-tokens`	lock-method	CaInt32	Method/Type of this lock. This is the value that was passed to `__cb_lock__` as the method argument. (See [[xref points to what?]] for a complete description.)
`__cb_lock__`-required	specified by 'get-lock-tokens'	lock-experiation	CaDateTime	Date and time that the lock token will expire.

Table 9. Datatype and Value Mappings

Object Type	Value Type	Size	Value
CaString	CaString	number of characters in string	first 40 characters
CaInt*	CaInt*	not used	actual value of number
CaFloat, CaDouble	CaFloat, CaDouble	not used	actual value of number
CaDict	CaUInt32	not used	either the number of pairs in the dictionary or the result of doing a `__cb_stat__` operation on the dictionary itself, depending on the current depth and the value of the `recurse-depth` option.)
CaList	CaList	number of elements in list	return the first 4 items of the list. Each of these items should be returned in their "short" form, which can be obtained from this table. CaDicts embedded in a CaList are a special case: an empty CaDict must be returned in place of the original CaDict.
CaBinary	CaBinary	number of bytes in binary	first 32 bytes of binary

options is a dictionary providing a variable number of arguments to the Natroun driver. The Cairo Public Interface Required Options lists the required options and how they must be supported. If an option is not supplied, the driver must assume the default value. If a driver does not understand an option provided in the dictionary, it must ignore it. If a driver needs to invoke the services of another driver, it must pass the options dictionary on to the sub-driver.

Table 10. Cairo Public Interface Required Options

Name	Type	Meaning	Default Value
recurse-depth	CaInt32	How many levels deep to stat if the object(s) is a table. A depth of 0 means just this object's contents. A depth of 1 means this object and its children, 2 this object, its children, and its children's children.	0
stat-info	CaList of CaString	A list containing the result keys which the driver must return during this stat operation.	[] (the empty list)
get-lock-tokens	CaBoolean	If TRUE, `__cb_stat__` returns information on the lock tokens for this object instead of information on the object itself. If recurse-depth is supplied, it must be ignored as you may only get the lock tokens for an explicit object.	FALSE

Example result for a __cb_stat__ operation on a CaString object.

{
"type" => "CaString",
"value" => "This is an example string"
}

Example 1. __cb_stat__

Example result for a __cb_stat__ operation on a CaDict with depth of 1.

{
        "myString" => {
                      "type" => "CaString",
                      "value" => "This is an example string...",
                      "size" => 82
                },
        "myFloat" => {
                     "type" => "CaFloat",
                     "value" => 4.2
                },
        "theStates" => {
                       "type" => "CaDict",
                       "value" => 50
                }
}

`monitor()`

Table 11. monitor()

Return Type	Method Name	Method Arguments
CaObject	`monitor()`	(CaObject path, NatrounCallback callbackObject, CaDict options)

__cb_monitor__ is conceptually similar to some parts of the BeOS API. Namely, it allows an application to register interest in an object, and when anything inside of that object (or the object itself) is modified, the application is notified by way of the NatrounCallback object supplied to __cb_monitor__.

__cb_monitor__ must return a vaild monitor token --- to be used to unregister this monitor---on success, or throw an exception on error. A monitor token is different from a lock token, and should never be the same.

callbackObject may be registered for more than one path. If callbackObject is already registered for exactly this path, __cb_monitor__ must return the original monitor token. Different callbackObjects must be able to be supplied for the same path.

NatrounCallback is a class with at least the method:

Table 12. monitor_callback parameters

return type	method name	method arguments
void	`monitor_callback`	(CaList objects, CaUInt32 event)

This method will be invoked with a CaList of objects which have been modified. Each object's path is identified by an absoluate path in CaString form.

The argument event gives monitor_callback the event that occured prompting this callback. The CairoAdapter must support the events which are listed as required in the following table.

Table 13. Events for monitor_callback

Class	Value	Meaning
required	1	The object being monitored was the target of a `__cb_put__` operation.
required	2	An object inside of the object being monitored was the target of a `__cb_put__` operation.
required	4	The object being monitored was the target of a `__cb_delete__` operation.
required	8	An object inside of the object being monitored was the target of a `__cb_delete__` operation.
required	16	The lock token being monitored has been granted.
required	32	The lock token being monitored has expired.

An application may remove the listener by either making the callbackObject no longer valid (i.e., if the application hosting the original object disappears and the proxy becomes invalid) or the application removes the monitor using __cb_unmonitor__

If monitor_callback throws an exception during its execution, the monitor must be unregistered by the driver which caught the exception.

The CaDict options allows you to set a few options, such as the recurse-depth of the monitor (how deep to monitor this object's children), and the events which you want.

Table 14. Options for __cb_monitor__

Name	Type	Meaning	Default
recurse-depth	CaInt32	Specifies the number of children deep to monitor. A depth of 0 monitors only changes to this object, not to anything contained in it.	2,147,483,647
event-mask	CaUInt32	A bitmask of the events that you wish to receive events for. These events should be OR'd together from the values in the above event table.	4,294,967,295 (full bitset, all events)

`unmonitor()`

Table 15. unmonitor()

Return Type	Method Name	Method Arguments
void	`unmonitor()`	(CaObject monitor)

__cb_unmonitor__ removes the monitor named by the monitor token.

__cb_unmonitor__ must throw an exception on error. On success __cb_unmonitor__ must just return nothing.

`lock()`

Table 16. lock()

Return Type	Method Name	Method Arguments
CaDict	`lock()`	(CaObject object, CaInt32 method, CaDateTime timeout)

Manipulates a lock for an object. The type of object and the value of type determines the exact operation. object must be either a path or a lock token returned by a prior call to lock(). All CairoAdapters must wrap lock tokens so that they can direct the token to the correct Natroun driver.

Table 17. Lock Operations

Operation	Value for method	Meaning of object
Obtain Exclusive Lock	-2	Path or Token
Obtain Update Lock	-1	must be a path only
Refresh Token	0	must be a token only
Obtain Shared Lock	1	Path or token

An Update lock ensures that the caller can upgrade to an Exclusive lock at a later point. An Update lock must not be granted unless it will always be possible to upgrade the Update lock into an Exclusive lock at a later point. If it is possible that the Update lock cannot be upgraded into an Exclusive lock at a later point, the driver must not grant the Update lock.

All locks must have a timeout. After the timeout has expired, the lock may be released automatically by the driver. This includes locks that are pending but have not been granted yet. The timeout is advisory, applications must expect to get back a different value than they provide. This allows the Natroun driver to set and enforce reasonable values. A time very far in the future (for example, a few years) may be used for "infinite" time locks.

__cb_lock__ method must never block. Should the lock not be grantable at the present time, perhaps because it is held by another user or task,[2] the driver must give out a token and return a wait status. The token must be put into a queue and granted after the resource becomes available. Should the token expire prior to the lock being granted to it, it may be removed from the wait queue. It must not be necessary for an application to "poll" the driver through __cb_lock__ in order to actually upgrade a token in wait status to a token in locked status.

An application may use refresh to reset the timeout of a lock token, discover if the lock has expired, or to check if the lock has been granted yet by the driver.

The return value of __cb_lock__ must be of type CaDict with the following required members.

Table 18. __cb_lock__ Return Format

Name	Type	Meaning
status	CaInt32	Status of lock token
token	CaBinary	Opaque lock token
timeout	CaDateTime/para>	Time lock expires
error_message	CaString	Description of error (only provided on error condition)

Depending on the result of the specified operation, __cb_lock__ should return a particular condition.

Table 19. Lock Conditions and Status Codes

Condition	Reason Condition Arises	Token	Timeout	Status
success	lock was granted, updated or refreshed	the (possibly new) lock token	the actual timeout value used	0
wait	resource already locked, must wait	lock token (must be placed on wait queue)	the actual timeout value used	1
failure	object did not exist, not enough lock resources available, etc.	not returned	not returned	-1
invalid lock token	lock token supplied has expired or is not valid	not returned	not returned	-2

The driver may return a different lock token than what the application passed as an argument. If the object is accessible through more than one path name, all of those paths must share the the same set of locks and tokens.

`unlock()`

Table 20. unlock()

Return Type	Method Name	Method Arguments
CaBoolean	`unlock()`	(CaObject token)

Releases the lock held by token. Conformant Natroun Drivers must grant any locks that are blocked on the waiting list.[3] Token should not be valid after an __cb_unlock__ operation.

`invoke()`

Table 21. invoke()

Return Type	Method Name	Method Arguments
CaObject	`invoke()`	(CaObject path, CaList args)

Invoke the method (or script) named in path, providing it the arguments in args. If the item named in path is a script, it will be invoked with the args form the arg list. If the item named in path is a method of an object (see [[CasbahAM xref]]), the method will be invoked on the object (which is also named in path), and the method will be passed the args from args.

invoke() must throw any exception that the invoked method (or script) threw during execution. Otherwise invoke() must return the result of the method (or script).

`begin_authentication()`

Table 22. lock()

Return Type	Method Name	Method Arguments
CaDict	`begin_authentication()`	(CaString user, CaString realm)

begin_authentication() asks CairoAdapter to begin an authentication exchange with the realm provided. After the exchange is successful, this CairoAdapter instance will act and respond to all requests as the user "user@realm".

begin_authentication() must return a result dict, which is generated as the result of a ShariffAPI __cb_authenticate__() method. This result dict contains a status field, and potentially a challenge. An application may respond to a challenge using authenticate()

If begin_authentication() cannot start an authentication session, begin_authentication() must return a result with the 'error' response code.

Table 23. Keys Used In Result of begin_authentication()

Member Name	Datatype	Description
status	CaInt32	Status condition of this authentication attempt. See [[what status codes xref?]] status codes.
cred-prompt	CaString	Prompt to give to user to get the next credential from them. Prompts are strings like "joe's password: " or "number on security card: ". Prompt strings may be 0 characters in length.
error	CaString	Error message that can be displayed to the user. A driver may return this item, however most error messages that could be returned are considered security errors and should be advoided.

Table 24. begin_authentication() Result Conditions

Status Condition	Value for 'status'	Notes
error	-2	The user or relam was incorrect, or the CairoAdapter could not start the authentication.
incorrect cred	-1	Either user or cred was incorrect for this stage of authentication. The realm must stop authentication with this module, as the module no longer wants to grant access.
authenticated	0	User is successfully authenticated, cred-prompt must not appear in the result. The realm may setup the user's authentication information with Cairo at this point.
prompt cred	1	Shariff module needs another credential supplied for this user. cred-prompt must appear in the result set, and must contain the prompt the application should show to the user. The Shariff driver may place any other items in conv, as it will be passed back in on the next call if there is one.

`authenticate()`

Table 25. authenticate()

Return Type	Method Name	Method Arguments
CaDict	`authenticate()`	(CaObject cred)

authenticate() hands the realm a new credential. This credential is a response to a challenge presented by the realm, for instance a password or a peice of text encrypted by the client using a public/private key system. authenticate() returns exactly the same information as begin_authentication(), in exactly the same format. See begin_authentication() for a description of the return value.

`abort_authentication()`

Table 26. abort_authentication()

Return Type	Method Name	Method Arguments
void	`abort_authentication()`	()

abort_authentication() aborts any currently running authentication process, reverting the CairoAdapter instance's authentication information to their values before begin_authentication() was invoked. abort_authentication() is useful for applications where a user might press a "Cancel" button in a GUI window prompting for a password.

`set_state()`

Table 27. set_state()

Return Type	Method Name	Method Arguments
CaDict	`set_state()`	(CaObject key, CaObject newstate)

set_state() returns the previous value of the state identified by key after setting to newstate.

`get_state()`

Table 28. get_state()

Return Type	Method Name	Method Arguments
CaString	`get_state()`	(CaObject key)

get_state() takes key and returns the element of CairoAdapter's local state which matches key. It returns either a CaString or CaNull if state is unavailable.

`chpath()`

Table 29. chpath()

Return Type	Method Name	Method Arguments
CaList	`chpath()`	(CaObject path)

chpath() changes the current path to another path in the Casbah Virtual Namespace. It takes an CaObject as its only argument. It returns a CaList containing elements of the current path before chpath() was called.

`curpath()`

Table 30. curpath()

Return Type	Method Name	Method Arguments
CaList	`curpath()`	()

curpath() returns a CaList of elements representing the current path.

[1]	The atomic types are CaString, CaInt, CaFloat, CaDouble, CaBinary, and CaBoolean.
[2]	This document uses the terms "thread" and "task" interchangeably.
[3]	For example, if the token being unlocked was representing an Exclusive lock, and there are Read locks waiting, the Read locks should now be granted.

Prev	Home	Next
Cairo Public Interface Static Methods	Up	Casbah Virtual Namespace

Notes