Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

VXIcacheInterface Struct Reference
[Cache Interface]

#include <VXIcache.h>

List of all members.


Detailed Description

Abstract interface for accessing caching functionality.

Permits writing arbitrary data into the cache with a client supplied key name, then retrieving that data from the cache one or more times by reading against that key name.


Public Attributes

VXIint32(* GetVersion )(void)
 Get the VXI interface version implemented.
const VXIchar *(* GetImplementationName )(void)
 Get the name of the implementation.
VXIcacheResult(* Open )(struct VXIcacheInterface *pThis, const VXIchar *moduleName, const VXIchar *key, VXIcacheOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIcacheStream **stream)
 Open a stream for reading or writing given a wide character key.
VXIcacheResult(* Close )(struct VXIcacheInterface *pThis, VXIcacheStream **stream)
 Close a previously opened stream.
VXIcacheResult(* Unlock )(struct VXIcacheInterface *pThis, const VXIchar *key)
 Unlock an entry that was previously locked into the cache given a wide character key.
VXIcacheResult(* Read )(struct VXIcacheInterface *pThis, VXIbyte *buffer, VXIulong buflen, VXIulong *nread, VXIcacheStream *stream)
 Read from a stream.
VXIcacheResult(* Write )(struct VXIcacheInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIcacheStream *stream)
 Write to a stream.
VXIcacheResult(* OpenEx )(struct VXIcacheInterface *pThis, const VXIchar *moduleName, const VXIbyte *key, VXIulong keySizeBytes, VXIcacheOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIcacheStream **stream)
 Open a stream for reading or writing given a binary key.
VXIcacheResult(* CloseEx )(struct VXIcacheInterface *pThis, VXIbool keepEntry, VXIcacheStream **stream)
 Close a previously opened stream.
VXIcacheResult(* UnlockEx )(struct VXIcacheInterface *pThis, const VXIbyte *key, VXIulong keySizeBytes)
 Unlock an entry that was previously locked into the cache given a binary key.


Member Data Documentation

VXIcacheResult(* VXIcacheInterface::Close)(struct VXIcacheInterface *pThis, VXIcacheStream **stream)
 

Close a previously opened stream.

NOTE: CloseEx( ) is the same but supports invalidating the entry

Close a previously opened stream. If Close is called on a NULL stream or a previously closed stream an error will be returned

Parameters:
stream [IN/OUT] Stream to close, set to NULL on success
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcacheResult(* VXIcacheInterface::CloseEx)(struct VXIcacheInterface *pThis, VXIbool keepEntry, VXIcacheStream **stream)
 

Close a previously opened stream.

NOTE: Same as Close( ) but supports invalidating the entry. This is only available as of version 1.1 of the VXIcacheInterface, use CACHE_CLOSEEX_SUPPORTED( ) to determine availability.

Close a previously opened stream. If Close is called on a NULL stream or a previously closed stream an error will be returned

Parameters:
keepEntry [IN] TRUE to indiate the write was a success and the cache entry should be retained, FALSE to indicate the write failed (typically due to a data source read unexpectedly failing)
stream [IN/OUT] Stream to close, set to NULL on success
Returns:
VXIcache_RESULT_SUCCESS on success

const VXIchar*(* VXIcacheInterface::GetImplementationName)(void)
 

Get the name of the implementation.

Returns:
Implementation defined string that must be different from all other implementations. The recommended name is one where the interface name is prefixed by the implementator's Internet address in reverse order, such as com.xyz.rec for VXIrec from xyz.com. This is similar to how VoiceXML 1.0 recommends defining application specific error types.

VXIint32(* VXIcacheInterface::GetVersion)(void)
 

Get the VXI interface version implemented.

Returns:
VXIint32 for the version number. The high high word is the major version number, the low word is the minor version number, using the native CPU/OS byte order. The current version is VXI_CURRENT_VERSION as defined in VXItypes.h.

VXIcacheResult(* VXIcacheInterface::Open)(struct VXIcacheInterface *pThis, const VXIchar *moduleName, const VXIchar *key, VXIcacheOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIcacheStream **stream)
 

Open a stream for reading or writing given a wide character key.

NOTE: OpenEx( ) is the same but supports binary keys

If the cache entry is currently in use and a stream cannot be returned because this use locks the entry, Open should return VXIcache_RESULT_ENTRY_LOCKED.

The behavior of opening a cache entry for reading during a write operation is implementation defined.

Parameters:
moduleName [IN] Name of the software module that is writing or reading the data. See the top of VXIlog.h for moduleName allocation rules.
key [IN] Key name of the data to access, NULL terminated VXIchar based string that may be of an arbitrary length
mode [IN] Mode to open the data with, a CACHE_MODE value as defined above
flags [IN] Flags to control the open: CACHE_FLAG_LOCK, lock retrieved data in the cache so it is not flushed (although may be flushed from the memory cache to the disk cache) CACHE_FLAG_LOCK_MEMORY, lock retrieved data in the memory cache so it is not flushed (not even to the disk cache), note that some implementations may ignore this and simply treat this as CACHE_FLAG_LOCK. CACHE_FLAG_NONBLOCKING_IO, non-blocking reads and writes, although the open and close is still blocking
properties [IN] Properties to control the open, as listed above. May be NULL.
streamInfo [OUT] (Optional, pass NULL if not required.) Map that will be populated with information about the stream, the CACHE_INFO_[...] keys listed above are mandatory with the implementation possibly setting other keys. This may not be populated on an open for WRITE since that is creating a new file.
stream [OUT] Handle to the opened stream
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcache_RESULT_ENTRY_LOCKED if the entry is in used and cannot be returned. Returned if a writer has the entry open.

VXIcache_RESULT_NULL_STREAM if the stream that was passed in or the interface is NULL

VXIcacheResult(* VXIcacheInterface::OpenEx)(struct VXIcacheInterface *pThis, const VXIchar *moduleName, const VXIbyte *key, VXIulong keySizeBytes, VXIcacheOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIcacheStream **stream)
 

Open a stream for reading or writing given a binary key.

NOTE: Same as Open( ) but supports binary keys. This is only available as of version 1.1 of the VXIcacheInterface, use CACHE_OPENEX_SUPPORTED( ) to determine availability.

If the cache entry is currently in use and a stream cannot be returned because this use locks the entry, Open should return VXIcache_RESULT_ENTRY_LOCKED.

The behavior of opening a cache entry for reading during a write operation is implementation defined.

Parameters:
moduleName [IN] Name of the software module that is writing or reading the data. See the top of VXIlog.h for moduleName allocation rules.
key [IN] Key name of the data to access, binary data (raw bytes) of an arbitrary length
keySizeBytes [IN] Size of the key name in bytes
mode [IN] Mode to open the data with, a CACHE_MODE value as defined above
flags [IN] Flags to control the open: CACHE_FLAG_LOCK, lock retrieved data in the cache so it is not flushed (although may be flushed from the memory cache to the disk cache) CACHE_FLAG_LOCK_MEMORY, lock retrieved data in the memory cache so it is not flushed (not even to the disk cache), note that some implementations may ignore this and simply treat this as CACHE_FLAG_LOCK. CACHE_FLAG_NONBLOCKING_IO, non-blocking reads and writes, although the open and close is still blocking
properties [IN] Properties to control the open, as listed above. May be NULL.
streamInfo [OUT] (Optional, pass NULL if not required.) Map that will be populated with information about the stream, the CACHE_INFO_[...] keys listed above are mandatory with the implementation possibly setting other keys. This may not be populated on an open for WRITE since that is creating a new file.
stream [OUT] Handle to the opened stream
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcache_RESULT_ENTRY_LOCKED if the entry is in used and cannot be returned. Returned if a writer has the entry open.

VXIcache_RESULT_NULL_STREAM if the stream that was passed in or the interface is NULL

VXIcacheResult(* VXIcacheInterface::Read)(struct VXIcacheInterface *pThis, VXIbyte *buffer, VXIulong buflen, VXIulong *nread, VXIcacheStream *stream)
 

Read from a stream.

This may or not block, as determined by the flags used when opening the stream. When in non-blocking mode, partial buffers may be returned instead of blocking, or an VXIcache_RESULT_WOULD_BLOCK error is returned if no data is available at all.

Parameters:
buffer [OUT] Buffer that will receive data from the stream
buflen [IN] Length of buffer, in bytes
nread [OUT] Number of bytes actual read, may be less then buflen if the end of the stream was found, or if using non-blocking I/O and there is currently no more data available to read
stream [IN] Handle to the stream to read from
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcacheResult(* VXIcacheInterface::Unlock)(struct VXIcacheInterface *pThis, const VXIchar *key)
 

Unlock an entry that was previously locked into the cache given a wide character key.

NOTE: UnlockEx( ) is the same but supports binary keys

This releases a cache lock on the indicated data. Note that it is up to the implementation to decide when to flush the data from the cache, it may choose to do so immediately or may do so at a later time.

Parameters:
key [IN] Key name of the data to access, NULL terminated VXIchar based string that may be of an arbitrary length
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcacheResult(* VXIcacheInterface::UnlockEx)(struct VXIcacheInterface *pThis, const VXIbyte *key, VXIulong keySizeBytes)
 

Unlock an entry that was previously locked into the cache given a binary key.

NOTE: Same as Unlock( ) but supports binary keys. This is only available as of version 1.1 of the VXIcacheInterface, use CACHE_UNLOCKEX_SUPPORTED( ) to determine availability.

This releases a cache lock on the indicated data. Note that it is up to the implementation to decide when to flush the data from the cache, it may choose to do so immediately or may do so at a later time.

Parameters:
key [IN] Key name of the data to access, binary data (raw bytes) of an arbitrary length
keySizeBytes [IN] Size of the key name in bytes
Returns:
VXIcache_RESULT_SUCCESS on success

VXIcacheResult(* VXIcacheInterface::Write)(struct VXIcacheInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIcacheStream *stream)
 

Write to a stream.

This may or not block, as determined by the flags used when opening the stream. When in non-blocking mode, partial writes may occur instead of blocking, or an VXIcache_RESULT_WOULD_BLOCK error is returned if no data could be written at all.

Parameters:
buffer [OUT] Buffer of data to write to the stream
buflen [IN] Number of bytes to write
nread [OUT] Number of bytes actual written, may be less then buflen if an error is returned, or if using non-blocking I/O and the write operation would block
stream [IN] Handle to the stream to write to
Returns:
VXIcache_RESULT_SUCCESS on success


The documentation for this struct was generated from the following file:
Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2