| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: NatrounAPI | Next |
For large objects, an application may ask to get back a stream handle. This stream handle is much like a file handle (fd) in most Unixes. It provides only read, write, seek, and close. Locking should be arranged by locking the resource itself (See __cb_lock__). The stream handle must be unique for the driver until the application closes the stream handle. If the entity is deleted or overwritten via __cb_put__ while stream handles are open on it, then the stream handles must continue to point to, and operate on the origional content, not the new content placed by __cb_put__. [1]
Only items of type CaString or CaBinary may have stream handles. All other datatypes are "too small" to warrant stream handles. CaString objects must be treated as though they were CaBinary objects; i.e., they must be represented as a stream of CaUInt8's.
A stream handle must be an instance of a class which supports the read, write, seek and close methods. This class must be written by the Natroun driver author. It may be subclassed from any class deemed appropriate by the driver author.
When a stream handle is closed, the driver must check determine whether the closing stream handle is the last way to access the object. If it is, the driver must destroy and release the data associated with the object. [2]
An application must be able to open a stream handle on an object that is being translated using "accept-types" if the result of the translation will be in CaBinary or CaString form. The translation code must convert the data and write it to the stream as the application reads it. An application must also be able to open a stream handle for writing and write to it using translation. [3] Seek must be disabled on a stream handle that is open for translation.
Stream handles can have 3 different modes of operation: read-only, write-only, or read-write. Translation must only be available on read-only or write-only stream handles---providing translation services for read and write stream handles is far too difficult. The mode of a stream handle is the value of the __cb_get__ option "stream-handle", as a CaUInt32.
Table 22. Stream Handle Modes
Name | Value |
|---|---|
Read | 1 |
Write | 2 |
Read and Write | 3 |
The following methods are required on a stream handle. They are the manner in which an application interfaces with a stream handle. These methods are considered "raw" I/O and, for the most part, should not be buffered.
Table 23. Stream Methods
Return Type | Name | Arguments | Description |
|---|---|---|---|
CaBinary | read | (CaUInt32 len) | Read len bytes (CaUInt8's) and return them in a CaBinary. read may return less bytes than were requested. read must return a CaBinary of length 0 upon EOF (end of file). read must advance the file pointer. |
CaUInt32 | write | (CaBinary data) | Write data and return the number of bytes actually written. write may write less bytes than were passed. write must advance the file pointer. |
CaUInt64 | tell | () | Return the current address of the file pointer from the start of the file. The first byte in the file is numbered at 0. If the stream is unseekable, tell must return the number of bytes read or written so far. |
CaInt64 | seek | (CaUInt32 whence, CaInt64 pos) | seek changes the current file pointer. When whence is 0, pos is the absolute address to set the file pointer to. When whence is 1, pos is relative to the current file pointer and the new file pointer must be constructed by adding pos to the current file pointer. (pos may be negative.) seek returns the new file pointer. |
void | close | () | Close the stream handle. After the close operation the stream handle is no longer valid, and must not be reused. A close operation must be done by the application when it no longer wishes to use the stream handle so that the driver may release any resources associated with this handle. |
| [1] | Cf. this to the effect of renaming a file on top of an already open file in Unix. |
| [2] | Unix programmers may recognize this as the same behavior seen by file descriptors on, especially when files are unlinked while still open. |
| [3] | This allows an application to read or write a structured, parsed XML document as XML text. |