vxiinet.h

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

 /****************License************************************************
  *
  * Copyright 2000-2003.  ScanSoft, Inc.    
  *
  * Use of this software is subject to notices and obligations set forth 
  * in the SpeechWorks Public License - Software Version 1.2 which is 
  * included with this software. 
  *
  * ScanSoft is a registered trademark of ScanSoft, Inc., and OpenSpeech, 
  * SpeechWorks and the SpeechWorks logo are registered trademarks or 
  * trademarks of SpeechWorks International, Inc. in the United States 
  * and other countries.
  *
  ***********************************************************************/
 

 #ifndef _VXIINET_H
 #define _VXIINET_H
 
 #include "VXIvalue.h"                  /* For VXIMap, VXIString, etc. */
 
 #include "VXIheaderPrefix.h"
 #ifdef VXIINET_EXPORTS
 #define VXIINET_API SYMBOL_EXPORT_DECL
 #else
 #define VXIINET_API SYMBOL_IMPORT_DECL
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #ifdef __cplusplus
 struct VXIinetStream;
 #else
 typedef struct VXIinetStream { void * dummy; } VXIinetStream;
 #endif
 
 
 /**
  * @name VXIinet
  * @memo Internet Interface
  * @version 1.0
  * @doc
  * Abstract interface for accessing Internet functionality including
  * HTTP requests, local file access, URL caching, and cookie access. <p>
  *
  * The interface is a synchronous interface based on the ANSI/ISO C
  * standard file I/O interface, the only exception is that pre-fetches are
  * asynchronous. The client of the interface may use this in an
  * asynchronous manner by using non-blocking I/O operations, creating
  * threads, or by invoking this from a separate server process. <p>
  *
  * There is one Internet interface per thread/line.
  */
 
 /*@{*/
 
 
 /**
  * @name VXIinet argument properties
  * @memo Keys identifying properties in VXIMap for Prefetch( ) and Open( )
  * @doc VXIinet functions take a VXIMap argument which contains a set of
  * key/value pairs. The listed arguments must be supported by an
  * implementation. Additional arguments can be added to this argument in
  * other implementations. Time durations are specified in milliseconds, see
  * below for valid values for the enumerated type properties.
  */
 
 /*@{*/
     /** Value for the HTTP 1.1 Cache-Control max-age directive for
 	requests. This specifies the client is willing to accept a
 	cached object no older than this value (given in seconds). A
 	value of 0 may be used to force re-validating the cached copy
 	with the origin server for every request. In most cases, this
 	property should not be present, thus allowing the origin
 	server to control expiration. Value is a VXIInteger */
 #define INET_CACHE_CONTROL_MAX_AGE       L"inet.maxage"
 
     /** Value for the HTTP 1.1 Cache-Control max-stale directive for
 	requests. This specifies the client is willing to accept a
 	cached object that is expired by up to this value (given in
 	seconds) past the expiration time specified by the origin
 	server. In most cases, this property should be set to 0 or not
 	present, thus respecting the expiration time specified by the
 	origin server. Value is a VXIInteger */
 #define INET_CACHE_CONTROL_MAX_STALE     L"inet.maxstale"
 
     /** Type of caching to apply: safe or fast. See the INET_CACHING
 	defines.  NOTE: Supported for backward compatibility only, use
 	INET_CACHE_CONTROL_MAX_AGE instead ("safe" mode is identical
 	to setting that parameter to 0, while "fast" mode is identical
 	to leaving that parameter unspecified).  Value is a VXIString */
 #define INET_CACHING                     L"inet.caching"
 
     /** Conditional open, used for cases where a cache outside of
       VXIinet is being maintained and the desired object is already
       present in that cache, but the user needs to verify whether
       that cached object is valid for reuse or not. (For example,
       maintaining a compiled grammar cache where the grammar source
       is obtained from a URL.) To do so, when writing data to the
       cache the user must also store the value of the
       INET_INFO_VALIDATOR return property. Then for the next request
       for that data, the user must set this property to that validator
       object and do an Open( ). If VXIinet_RESULT_NOT_MODIFIED is
       returned, the user may re-use the cached data, but must also
       update the associated validator with the updated validator
       returned in INET_INFO_VALIDATOR. Otherwise if
       VXIinet_RESULT_SUCCESS is returned, the cached entry is invalid
       and the user obtains a stream from which they must re-create
       (re-compile) the data.  (A simple case to understand is file://
       access: the validator will usually just be the modification time,
       if that changes the cached data is invalid. The need for an opaque
       validator and this conditional open mechanism is driven by HTTP 1.1,
       where the validator is far more complex, a combination of expiration
       times, a modification date, entity tags, and other data.)  Value is
       a VXIContent as returned for INET_INFO_VALIDATOR */
 #define INET_OPEN_IF_MODIFIED   L"inet.openIfModified"
 
     /** Whether to open local files normally or to return a
       VXIinet_RESULT_LOCAL_FILE error while still returning the
       stream information if requested.  Value is a VXIInteger where
       it is set to TRUE (1) or FALSE (0). */
 #define INET_OPEN_LOCAL_FILE    L"inet.openLocalFile"
 
     /** Prefetch priority. For implementations supporting priority
       this controls the order of opens and reads for multiple current
       reads.  Argument is a VXIInteger */
 #define INET_PREFETCH_PRIORITY  L"inet.prefetchPriority"
 
     /** Submit method: GET or POST.  Argument is a VXIString.
         Default is INET_SUBMIT_METHOD_DEFAULT. */
 #define INET_SUBMIT_METHOD      L"inet.submitMethod"
 
     /** Submit MIME type. MIME type of data sent in the submit. Default
         is INET_SUBMIT_MIME_TYPE_DEFAULT.  Argument is a VXIString */
 #define INET_SUBMIT_MIME_TYPE   L"inet.submitMimeType"
 
     /** Open timeout. Amount of time in (ms) to wait for an open to
       succeed before abadoning the open.  Default is
       INET_TIMEOUT_OPEN_DEFAULT Argument is a VXIInteger */
 #define INET_TIMEOUT_OPEN       L"inet.timeoutOpen"
 
     /** Read timeout.  Time in (ms) to attempt to read on the socket before
       abadoning the read. Default is INET_TIMEOUT_IO_DEFAULT. Argument is a
       VXIInteger */
 #define INET_TIMEOUT_IO         L"inet.timeoutIO"
 
     /** Total download timeout.  Time in (ms) to attempt to open and read
       all the contents on the socket before issuing a read.  This is
       optional and should be used to implement the VoiceXML timeout.
       Argument is a VXIinteger */
 #define INET_TIMEOUT_DOWNLOAD   L"inet.timeoutDownload"
 
     /** URL base for resolving relative URLs.  Note this is not a
       directory name, it is the full URL to the document that refers to
       this URL being fetched. No default.  Argument is a VXIString */
 #define INET_URL_BASE           L"inet.urlBase"
 
     /** URL Query Arguments.  Argument is a VXIMap containing zero or more
       key/value pairs.  When specified a submit is done as controlled
       by the INET_SUBMIT_METHOD and INET_SUBMIT_MIME_TYPE properties, for
       example doing a POST where the key/value pairs are appended to the
       URL in order to perform a query.  Only valid for INET_MODE_READ.
       By default is undefined (no submit performed). */
 #define INET_URL_QUERY_ARGS     L"inet.urlQueryArgs"
 
   /**
    * This property specifies whether the connection should be closed after the
    * fetch is completed.  This property, if specified and is a non-zero
    * VXIInteger, causes the the connection to be closed after the fetch.  If
    * specified and is zero VXIInteger, then an attempt to keep the connection
    * opened will be made.  If not specified, or not VXIInteger, then behaviour
    * is implementation dependant and should be specified in the
    * initialization of the inet layer
    */
 #define INET_CLOSE_CONNECTION   L"inet.closeConnection"
 
   /**
    * This property specifies whether a new connection should be established
    * regardless of the state of a previously established connection.  If
    * specified and is a non-zero VXIinteger, Open() will close any existing
    * connection and attempt establishing a new connection.  If specified and
    * is a zero VXIInteger, then Open() will try to reuse the existing
    * connection.  If not specified, or not VXIInteger, then behaviour
    * is implementation dependant and should be specified in the
    * initialization of the inet layer
    *
    * Whether the connection (whether new of existing) is closed or not after
    * the fetch is still controlled by the INET_CLOSE_CONNECTION property.
    *
    **/
 #define INET_NEW_CONNECTION    L"inet.newConnection"
 
 /*@}*/
 
 
 /**
  * @name INET_CACHING
  * @memo VXIinet caching property values.
  * @doc Set of defined caching property values that are used to control
  * when to retrieve information from the cache versus when to do a fetch.
  */
 /*@{*/
     /** Safe caching, follows VoiceXML 1 safe fetchhint property.
       Safe caching is the equivalent of end-to-end caching expiration
       checking.  The INET component will open a socket and check the
       document on the web server, even if the cache has not expired
       with safe caching */
 #define INET_CACHING_SAFE       L"safe"
 
     /** Fast caching, follows VoiceXML 1 fast fetchhint property.
       Fast caching will check the cache expiration of a document
       before opening a socket to the web server. If the document has
       not expired in the cache it will simply be returned.
       */
 #define INET_CACHING_FAST       L"fast"
 /*@}*/
 
 /**
  * INET_PREFETCH_PRIORITY property values.
  */
 typedef enum VXIinetPrefetchPriority {
   /** Caller is waiting for the document */
   INET_PREFETCH_PRIORITY_CRITICAL    =   40,
   /** Caller is going to get to this real soon */
   INET_PREFETCH_PRIORITY_HIGH        =   30,
   /** Caller is likely to need this in a little bit */
   INET_PREFETCH_PRIORITY_MEDIUM      =   20,
   /** Just initializing the system, no callers yet */
   INET_PREFETCH_PRIORITY_LOW         =   10
 } VXIinetPrefetchPriority;
 
 /**
  * @name INET_SUBMIT_METHOD
  * @memo INET_SUBMIT_METHOD supported property values.  PUT and DELETE
  are not supported.
  * @doc Full HTTP 1.1 support could be added to this interface. The
  current interface only supports the two methods commonly used for
  sending data back to a web server GET and POST.
  */
 /*@{*/
   /** HTTP GET */
 #define INET_SUBMIT_METHOD_GET   L"GET"
   /** HTTP POST */
 #define INET_SUBMIT_METHOD_POST  L"POST"
 /*@}*/
 
 /**
  * @name VXIinet property defaults
  * @memo Default values for properties in the VXIMap argument for
  * Prefetch() and Open()
  * @doc If the properties are not set in the call to these function
  the given default value will be assumed.
  */
 /*@{*/
    /** Cache Control max-age Default - NULL not present by default */
 #define INET_CACHE_CONTROL_MAX_AGE_DEFAULT    NULL
 
    /** Cache Control max-stale Default - 0, do not use expired entries */
 #define INET_CACHE_CONTROL_MAX_STALE_DEFAULT  0
 
    /** Caching Default - INET_CACHING_FAST */
 #define INET_CACHING_DEFAULT                  INET_CACHING_FAST
 
    /** Open If Modified Default - NULL not present by default */