vxiinet.h

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

  all the OpenVXI browser components.  The ability to prefetch
  and read URIs along with cookie management is provided.
  */
 
 typedef struct VXIinetInterface {
   /**
    * @name GetVersion
    * @memo Get the VXI interface version implemented
    *
    * @return  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.
    */
   VXIint32 (*GetVersion)(void);
 
   /**
    * @name GetImplementationName
    * @memo Get the name of the implementation
    *
    * @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 Prefetch
    * @memo Prefetch information (non-blocking)
    *
    * @doc
    * Note that this is optional, it does not need to be called prior
    * to Open( ). <p>
    *
    * Use the INET_PREFETCH_PRIORITY property to provide a hint to
    * indicate the priority of the prefetch. Note that the
    * implementation may opt to ignore the prefetch request (for
    * example a low priority prefetch when the cache is already full
    * with frequently used information). <p>
    *
    * @param moduleName  [IN] Name of the software module that is
    *                      outputting the error. See the top of VXIlog.h
    *                      for moduleName allocation rules.
    * @param name        [IN] Name of the data to fetch, see Open( ) for
    *                      a description of supported types
    * @param mode        [IN] Reserved for future use, pass INET_MODE_READ
    * @param flags       [IN] Reserved for future use, pass 0
    * @param properties  [IN] Properties to control the prefetch, as listed
    *                      above. May be NULL. Of particular note are:
    *                    INET_PREFETCH_PRIORITY, hint to indicate whether
    *                      and how soon to prefetch the data
    *                    INET_URL_BASE, base URL for resolving relative URLs
    *                    INET_URL_QUERY_ARGS, map containing key/value
    *                      pairs for HTTP queries, where the name of each
    *                      key is the query argument name, and the value of
    *                      each key is a VXIValue subclass that provides the
    *                      value for that argument
    *
    * @return VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*Prefetch)(struct VXIinetInterface *pThis,
 			    const VXIchar           *moduleName,
 			    const VXIchar           *name,
 			    VXIinetOpenMode          mode,
 			    VXIint32                 flags,
 			    const VXIMap            *properties);
 
   /**
    * @name Open
    * @memo Open a stream for reading or writing
    *
    * @doc
    * All implementations must support opening a URL for reading using
    * file:// or http:// access, and opening a platform dependant path
    * for reading. All implementations must support all the flags for
    * each of the above. For all other combinations support is
    * implementation dependant (i.e. write for URLs and platform dependant
    * paths). <p>
    *
    * For URLs, the only accepted unsafe characters are: { } [ ] ^ ~ '
    * They will be escaped if only when processing a HTTP request. <p>
    *
    * @param moduleName   [IN] Name of the software module that is
    *                       outputting the error. See the top of VXIlog.h
    *                       for moduleName allocation rules.
    * @param name         [IN] Name of the data to fetch, see above for
    *                       supported types
    * @param mode         [IN] Mode to open the data with, an INET_MODE
    *                       value as defined above
    * @param flags        [IN] Flags to control the open:
    *                     INET_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. Of particular note are:
    *                     INET_URL_BASE, base URL for resolving relative URLs
    *                     INET_URL_QUERY_ARGS, map containing key/value
    *                       pairs for HTTP queries, where the name of each
    *                       key is the query argument name, and the value of
    *                       each key is a VXIValue subclass that provides the
    *                       value for that argument
    * @param streamInfo   [OUT] (Optional, pass NULL if not required) Map
    *                       that will be populated with information about
    *                       the stream. See the INET_INFO_[...] keys listed
    *                       above, with the implementation possibly setting
    *                       other keys
    * @param stream       [OUT] Handle to the opened stream
    *
    * @return VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*Open)(struct VXIinetInterface  *pThis,
 			const VXIchar            *moduleName,
 			const VXIchar            *name,
 			VXIinetOpenMode           mode,
 			VXIint32                  flags,
 			const VXIMap             *properties,
 			VXIMap                   *streamInfo,
 			VXIinetStream           **stream);
 
   /**
    * @name Close
    * @memo Close a previously opened stream
    * @doc Close a stream that was previously opened. Closing a NULL or
    *      previously closed stream will result in an error.
    *
    * @param stream       [IN/OUT] Stream to close
    *
    * @return VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*Close)(struct VXIinetInterface  *pThis,
 			 VXIinetStream           **stream);
 
   /**
    * @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 VXIinet_RESULT_WOULD_BLOCK error
    * is returned if no data is available at all.
    *
    * NOTE: VXIinet_RESULT_END_OF_STREAM may be returned even when
    *   nread is greater then 0.  Example: if there are 20 more bytes
    *   remaining in a stream and the client component requests 50
    *   bytes via Read( ), the implementation should return
    *   VXIinet_RESULT_END_OF_STREAM with nread = 20. If the client
    *   component then (incorrectly) requests 50 more bytes via Read( ),
    *   return VXIinet_RESULT_END_OF_STREAM again with nread = 0.
    *
    * @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 VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*Read)(struct VXIinetInterface *pThis,
 			VXIbyte                 *buffer,
 			VXIulong                 buflen,
 			VXIulong                *nread,
 			VXIinetStream           *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 VXIinet_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 nwritten [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 VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*Write)(struct VXIinetInterface *pThis,
 			 const VXIbyte           *buffer,
 			 VXIulong                 buflen,
 			 VXIulong                *nwritten,
 			 VXIinetStream           *stream);
 
   /**
    * @name SetCookieJar
    * @memo Set the cookie jar
    *
    * @doc
    * The cookie jar is used to provide cookies and store cookies
    * during future VXIinet Prefetch( ) and Open( ) operations. Expired
    * cookies within the jar will not be used. Each time this is called
    * the prior cookie jar is discarded, the caller is responsible for
    * persistent storage of the cookie jar if desired. See
    * GetCookieJar( ) for details.
    *
    * If SetCookieJar( ) is never called, or if it is called with a
    * NULL jar, the VXIinet implementation will refuse to accept
    * cookies for fetches.
    *
    * @param jar     [IN] Cookie jar, specified as a VXIVector (see the
    *                  description of the cookie jar structure above).
    *                  Pass NULL to refuse all cookies. Pass an empty
    *                  VXIVector to accept new cookies starting with an
    *                  empty jar. Pass a non-empty VXIVector as returned
    *                  by GetCookieJar( ) to implement persist cookies
    *                  across multiple user sessions (telephone calls).
    *
    * @return VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*SetCookieJar)(struct VXIinetInterface  *pThis,
 				const VXIVector          *jar);
 
   /**
    * @name GetCookieJar
    * @memo Get the cookie jar
    *
    * @doc
    * The caller of VXIinet is responsible for persistent storage of
    * the cookie jar if desired. This is done by calling SetCookieJar( )
    * with the caller's cookie jar at the start of each call (use an
    * empty cookie jar if this is a new caller), then calling this
    * function to retrieve the updated cookie jar at the end of the
    * call for storage. When the cookie jar is returned, any expired
    * cookies will have been deleted.
    *
    * @param jar     [OUT] Cookie jar, returned as a newly allocated
    *                  VXIVector (see the description of the cookie jar
    *                  structure above, it may be empty). The client
    *                  is responsible for destroying this via
    *                  VXIVectorDestroy( ) when appropriate.
    * @param changed [OUT] Flag to indicate whether the cookie jar
    *                  has been modified since SetCookieJar( ), allows
    *                  suppressing the write of the cookie jar to
    *                  persistant storage when that operation is
    *                  expensive. Pass NULL if this information is not
    *                  desired.
    *
    * @return VXIinet_RESULT_SUCCESS on success
    */
   VXIinetResult (*GetCookieJar)(struct VXIinetInterface  *pThis,
 				VXIVector               **jar,
 				VXIbool                  *changed);
 
 } VXIinetInterface;
 
 /*@}*/
 
 #ifdef __cplusplus
 }
 #endif
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */