vxicache.h

OSB-PIK-OpenVXI-3.0.0源代码 “中国XML论坛 - 专业的XML技术讨论区--XML在语音技术中的应用”

    * @return  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.
    */
   const VXIchar* (*GetImplementationName)(void);
   
   /**
    * @name Open
    * @memo Open a stream for reading or writing given a wide character key
    *
    * NOTE: OpenEx( ) is the same but supports binary keys
    *
    * @doc
    * 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. <p>
    *
    * The behavior of opening a cache entry for reading during a write
    * operation is implementation defined. <p>
    *
    * @param moduleName   [IN] Name of the software module that is 
    *                       writing or reading the data. See the top of 
    *                       VXIlog.h for moduleName allocation rules.
    * @param key          [IN] Key name of the data to access, NULL
    *                       terminated VXIchar based string that may be
    *                       of an arbitrary length
    * @param mode         [IN] Mode to open the data with, a CACHE_MODE
    *                       value as defined above
    * @param 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
    * @param properties   [IN] Properties to control the open, as listed
    *                       above. May be NULL.
    * @param 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.
    * @param stream       [OUT] Handle to the opened stream
    *
    * @return VXIcache_RESULT_SUCCESS on success
    * @return VXIcache_RESULT_ENTRY_LOCKED if the entry is in used and 
    *           cannot be returned. Returned if a writer has the entry open.
    * @return VXIcache_RESULT_NULL_STREAM if the stream that was passed in 
    *           or the interface is NULL 
    */
   VXIcacheResult (*Open)(struct VXIcacheInterface  *pThis,
 			 const VXIchar             *moduleName,
 			 const VXIchar             *key,
 			 VXIcacheOpenMode           mode,
 			 VXIint32                   flags,
 			 const VXIMap              *properties,
 			 VXIMap                    *streamInfo,
 			 VXIcacheStream           **stream);
 
   /**
    * @name Close
    * @memo Close a previously opened stream
    *
    * NOTE: CloseEx( ) is the same but supports invalidating the entry
    *
    * @doc Close a previously opened stream.  If Close is called on 
    * a NULL stream or a previously closed stream an error will be
    * returned
    *
    * @param stream       [IN/OUT] Stream to close, set to NULL on
    *                       success
    *
    * @return VXIcache_RESULT_SUCCESS on success
    */
   VXIcacheResult (*Close)(struct VXIcacheInterface  *pThis,
 			  VXIcacheStream           **stream);
   
   /**
    * @name Unlock
    * @memo Unlock an entry that was previously locked into the cache given
    *       a wide character key
    *
    * NOTE: UnlockEx( ) is the same but supports binary keys
    *
    * @doc
    * 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.
    *
    * @param key          [IN] Key name of the data to access, NULL
    *                       terminated VXIchar based string that may be
    *                       of an arbitrary length
    *
    * @return VXIcache_RESULT_SUCCESS on success
    */
   VXIcacheResult (*Unlock)(struct VXIcacheInterface *pThis,
 			   const VXIchar            *key);
 
   /**
    * @name Read
    * @memo Read from a stream
    *
    * @doc
    * 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.
    *
    * @param buffer   [OUT] Buffer that will receive data from the stream
    * @param buflen   [IN] Length of buffer, in bytes
    * @param 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
    * @param stream   [IN] Handle to the stream to read from
    *
    * @return VXIcache_RESULT_SUCCESS on success 
    */
   VXIcacheResult (*Read)(struct VXIcacheInterface *pThis,
 			 VXIbyte                  *buffer,
 			 VXIulong                  buflen,
 			 VXIulong                 *nread,
 			 VXIcacheStream           *stream);
   
   /**
    * @name Write
    * @memo Write to a stream
    *
    * @doc
    * 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.
    *
    * @param buffer   [OUT] Buffer of data to write to the stream
    * @param buflen   [IN] Number of bytes to write
    * @param 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
    * @param stream   [IN] Handle to the stream to write to
    *
    * @return VXIcache_RESULT_SUCCESS on success 
    */
   VXIcacheResult (*Write)(struct VXIcacheInterface *pThis,
 			  const VXIbyte            *buffer,
 			  VXIulong                  buflen,
 			  VXIulong                 *nwritten,
 			  VXIcacheStream           *stream);
 
   /**
    * @name OpenEx
    * @memo 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.
    *
    * @doc
    * 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. <p>
    *
    * The behavior of opening a cache entry for reading during a write
    * operation is implementation defined. <p>
    *
    * @param moduleName   [IN] Name of the software module that is 
    *                       writing or reading the data. See the top of 
    *                       VXIlog.h for moduleName allocation rules.
    * @param key          [IN] Key name of the data to access, binary
    *                       data (raw bytes) of an arbitrary length
    * @param keySizeBytes [IN] Size of the key name in bytes
    * @param mode         [IN] Mode to open the data with, a CACHE_MODE
    *                       value as defined above
    * @param 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
    * @param properties   [IN] Properties to control the open, as listed
    *                       above. May be NULL.
    * @param 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.
    * @param stream       [OUT] Handle to the opened stream
    *
    * @return VXIcache_RESULT_SUCCESS on success
    * @return VXIcache_RESULT_ENTRY_LOCKED if the entry is in used and 
    *           cannot be returned. Returned if a writer has the entry open.
    * @return VXIcache_RESULT_NULL_STREAM if the stream that was passed in 
    *           or the interface is NULL 
    */
   VXIcacheResult (*OpenEx)(struct VXIcacheInterface  *pThis,
 			   const VXIchar             *moduleName,
 			   const VXIbyte             *key,
 			   VXIulong                   keySizeBytes,
 			   VXIcacheOpenMode           mode,
 			   VXIint32                   flags,
 			   const VXIMap              *properties,
 			   VXIMap                    *streamInfo,
 			   VXIcacheStream           **stream);
 
   /**
    * @name CloseEx
    * @memo 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.
    *
    * @doc Close a previously opened stream.  If Close is called on 
    * a NULL stream or a previously closed stream an error will be
    * returned
    *
    * @param 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)
    * @param stream       [IN/OUT] Stream to close, set to NULL on
    *                       success
    *
    * @return VXIcache_RESULT_SUCCESS on success
    */
   VXIcacheResult (*CloseEx)(struct VXIcacheInterface  *pThis,
 			    VXIbool                    keepEntry,
 			    VXIcacheStream           **stream);
   
   /**
    * @name UnlockEx
    * @memo 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.
    *
    * @doc
    * 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.
    *
    * @param key          [IN] Key name of the data to access, binary
    *                       data (raw bytes) of an arbitrary length
    * @param keySizeBytes [IN] Size of the key name in bytes
    *
    * @return VXIcache_RESULT_SUCCESS on success
    */
   VXIcacheResult (*UnlockEx)(struct VXIcacheInterface  *pThis,
 			     const VXIbyte             *key,
 			     VXIulong                   keySizeBytes);
 
 } VXIcacheInterface;
 
 /*@}*/
 
 #ifdef __cplusplus
 }
 #endif
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */