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.
Classes | |
struct | VXIinetInterface |
Abstract interface for accessing Internet functionality including HTTP requests, local file access, URL caching, and cookie access. More... | |
VXIinet argument properties | |
Keys identifying properties in VXIMap for Prefetch( ) and Open( ): 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. | |
#define | INET_CACHE_CONTROL_MAX_AGE L"inet.maxage" |
Value for the HTTP 1.1 Cache-Control max-age directive for requests. | |
#define | INET_CACHE_CONTROL_MAX_STALE L"inet.maxstale" |
Value for the HTTP 1.1 Cache-Control max-stale directive for requests. | |
#define | INET_CACHING L"inet.caching" |
Type of caching to apply: safe or fast. | |
#define | INET_OPEN_IF_MODIFIED L"inet.openIfModified" |
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. | |
#define | INET_OPEN_LOCAL_FILE L"inet.openLocalFile" |
Whether to open local files normally or to return a VXIinet_RESULT_LOCAL_FILE error while still returning the stream information if requested. | |
#define | INET_PREFETCH_PRIORITY L"inet.prefetchPriority" |
Prefetch priority. | |
#define | INET_SUBMIT_METHOD L"inet.submitMethod" |
Submit method: GET or POST. | |
#define | INET_SUBMIT_MIME_TYPE L"inet.submitMimeType" |
Submit MIME type. | |
#define | INET_TIMEOUT_OPEN L"inet.timeoutOpen" |
Open timeout. | |
#define | INET_TIMEOUT_IO L"inet.timeoutIO" |
Read timeout. | |
#define | INET_TIMEOUT_DOWNLOAD L"inet.timeoutDownload" |
Total download timeout. | |
#define | INET_URL_BASE L"inet.urlBase" |
URL base for resolving relative URLs. | |
#define | INET_URL_QUERY_ARGS L"inet.urlQueryArgs" |
URL Query Arguments. | |
#define | INET_CLOSE_CONNECTION L"inet.closeConnection" |
This property specifies whether the connection should be closed after the fetch is completed. | |
#define | INET_NEW_CONNECTION L"inet.newConnection" |
This property specifies whether a new connection should be established regardless of the state of a previously established connection. | |
VXIinet caching property values | |
Set of defined caching property values that are used to control when to retrieve information from the cache versus when to do a fetch. | |
#define | INET_CACHING_SAFE L"safe" |
Safe caching, follows VoiceXML 1 safe fetchhint property. | |
#define | INET_CACHING_FAST L"fast" |
Fast caching, follows VoiceXML 1 fast fetchhint property. | |
INET_SUBMIT_METHOD supported property values | |
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. | |
#define | INET_SUBMIT_METHOD_GET L"GET" |
HTTP GET. | |
#define | INET_SUBMIT_METHOD_POST L"POST" |
HTTP POST. | |
VXIinet property defaults | |
Default values for properties in the VXIMap argument for Prefetch() and Open(). If the properties are not set in the call to these function the given default value will be assumed. | |
#define | INET_CACHE_CONTROL_MAX_AGE_DEFAULT NULL |
Cache Control max-age Default - NULL not present by default. | |
#define | INET_CACHE_CONTROL_MAX_STALE_DEFAULT 0 |
Cache Control max-stale Default - 0, do not use expired entries. | |
#define | INET_CACHING_DEFAULT INET_CACHING_FAST |
Caching Default - INET_CACHING_FAST. | |
#define | INET_OPEN_IF_MODIFIED_DEFAULT NULL |
Open If Modified Default - NULL not present by default. | |
#define | INET_OPEN_LOCAL_FILE_DEFAULT TRUE |
Open Local File Default - TRUE. | |
#define | INET_PREFETCH_PRIORITY_DEFAULT INET_PREFETCH_PRIORITY_LOW |
Prefetch priority default - INET_PREFETCH_PRIORITY_LOW. | |
#define | INET_SUBMIT_METHOD_DEFAULT INET_SUBMIT_METHOD_GET |
Submit method default - INET_SUBMIT_METHOD_GET. | |
#define | INET_SUBMIT_MIME_TYPE_DEFAULT L"application/x-www-form-urlencoded" |
Submit MIME type default - "application/x-www-form-urlencoded". | |
#define | INET_TIMEOUT_OPEN_DEFAULT 30000 |
Open timeout default - 30000 (30 seconds). | |
#define | INET_TIMEOUT_IO_DEFAULT 30000 |
Read timeout default - 30000 (30 seconds). | |
#define | INET_TIMEOUT_DOWNLOAD_DEFAULT 30000 |
Total download timeout default - 30000 (30 seconds). | |
#define | INET_URL_BASE_DEFAULT L"" |
URL base default - "" (no base). | |
#define | INET_URL_QUERY_ARGS_DEFAULT NULL |
URL query arguments default - NULL not present by default. | |
Open flags | |
Flags for Open( ), may be combined through bitwise or. The Open() call takes a bitwise or of open flags which control the behavior of the returned stream. | |
#define | INET_FLAG_NULL 0x0 |
Null flag. | |
#define | INET_FLAG_NONBLOCKING_IO 0x8 |
Non-blocking reads/writes. | |
Open return properties | |
Keys identifying properties in VXIMap used to return stream information for Open( ). The VXIinet implementation determines information about the file or URI when it opens the URI. These are returned as key/value pairs through a VXIMap. Some values are not guaranteed to be returned after an open, see below. | |
#define | INET_INFO_ABSOLUTE_NAME L"inet.info.absoluteName" |
Absolute Name, always returned. | |
#define | INET_INFO_MIME_TYPE L"inet.info.mimeType" |
MIME type, always returned. | |
#define | INET_INFO_SIZE_BYTES L"inet.info.sizeBytes" |
Size in bytes, always returned. | |
#define | INET_INFO_VALIDATOR L"inet.info.validator" |
Validator, always returned on a successful Open( ) or when INET_OPEN_IF_MODIFIED was specified and VXIinet_RESULT_NOT_MODIFIED was returned. | |
#define | INET_INFO_HTTP_STATUS L"inet.info.httpStatus" |
HTTP status code, always returned for successful HTTP Open( ) operations, or HTTP Open( ) operations that fail due to the remote web server returning a HTTP failure code in the HTTP response. | |
#define | INET_INFO_VALIDATOR_STRONG L"inet.info.validatorStrong" |
INET_INFO_VALIDATOR_STRONG. | |
#define | INET_INFO_EXPIRES_HINT L"inet.info.expiresHint" |
Expires hint. | |
#define | INET_INFO_DATA_SOURCE L"inet.info.dataSource" |
an enum of type VXIinetDataSource (see above) in the Inet streamInfo map to indicate the data source: from a local file, from the fetch cache, from the fetch cache but had to revalidate with the web server, or from a full Internet fetch. | |
INET_COOKIE | |
Cookie jars are represented by a VXIVector. Each element of the vector is a VXIMap that represents a cookie. The cookie VXIMap will contain zero or more properties, each of which represent properties of the cookie. The properties of the cookie VXIMap match the cookie attribute names as defined in RFC 2965. The only exceptions are as follows:
| |
#define | INET_COOKIE_NAME L"inet.cookie.NAME" |
Cookie name. | |
#define | INET_COOKIE_VALUE L"inet.cookie.VALUE" |
Cookie value key. | |
#define | INET_COOKIE_EXPIRES L"inet.cookie.EXPIRES" |
Cookie expires key, calculated off the Max-Age property for the cookie. | |
#define | INET_COOKIE_COMMENT L"inet.cookie.Comment" |
Cookie comment, optional. | |
#define | INET_COOKIE_COMMENT_URL L"inet.cookie.CommentURL" |
Cookie comment URL, optional. | |
#define | INET_COOKIE_DOMAIN L"inet.cookie.Domain" |
Cookie domain key. | |
#define | INET_COOKIE_PATH L"inet.cookie.Path" |
Cookie path key. | |
#define | INET_COOKIE_PORT L"inet.cookie.Port" |
Cookie port key, optional. | |
#define | INET_COOKIE_SECURE L"inet.cookie.Secure" |
Cookie secure key, optional. | |
#define | INET_COOKIE_VERSION L"inet.cookie.Version" |
Cookie standard version. | |
Typedefs | |
typedef enum VXIinetPrefetchPriority | VXIinetPrefetchPriority |
INET_PREFETCH_PRIORITY property values. | |
typedef enum VXIinetDataSource | VXIinetDataSource |
Data source values. | |
typedef enum VXIinetOpenMode | VXIinetOpenMode |
Mode values for Open( ). | |
typedef enum VXIinetResult | VXIinetResult |
typedef VXIinetInterface | VXIinetInterface |
Abstract interface for accessing Internet functionality including HTTP requests, local file access, URL caching, and cookie access. | |
Enumerations | |
enum | VXIinetPrefetchPriority { INET_PREFETCH_PRIORITY_CRITICAL = 40, INET_PREFETCH_PRIORITY_HIGH = 30, INET_PREFETCH_PRIORITY_MEDIUM = 20, INET_PREFETCH_PRIORITY_LOW = 10 } |
INET_PREFETCH_PRIORITY property values. More... | |
enum | VXIinetDataSource { INET_DATA_SOURCE_FILE = 0x0, INET_DATA_SOURCE_HTTP = 0x1, INET_DATA_SOURCE_FTP = 0x2, INET_DATA_SOURCE_CACHE = 0x3, INET_DATA_SOURCE_VALIDATED = 0x4 } |
Data source values. More... | |
enum | VXIinetOpenMode { INET_MODE_READ = 0x0, INET_MODE_WRITE = 0x1 } |
Mode values for Open( ). More... | |
enum | VXIinetResult { VXIinet_RESULT_FATAL_ERROR = -100, VXIinet_RESULT_IO_ERROR = -8, VXIinet_RESULT_OUT_OF_MEMORY = -7, VXIinet_RESULT_SYSTEM_ERROR = -6, VXIinet_RESULT_PLATFORM_ERROR = -5, VXIinet_RESULT_BUFFER_TOO_SMALL = -4, VXIinet_RESULT_INVALID_PROP_NAME = -3, VXIinet_RESULT_INVALID_PROP_VALUE = -2, VXIinet_RESULT_INVALID_ARGUMENT = -1, VXIinet_RESULT_SUCCESS = 0, VXIinet_RESULT_FAILURE = 1, VXIinet_RESULT_NON_FATAL_ERROR = 2, VXIinet_RESULT_NOT_FOUND = 50, VXIinet_RESULT_FETCH_TIMEOUT = 51, VXIinet_RESULT_FETCH_ERROR = 52, VXIinet_RESULT_WOULD_BLOCK = 53, VXIinet_RESULT_END_OF_STREAM = 54, VXIinet_RESULT_LOCAL_FILE = 55, VXIinet_RESULT_NOT_MODIFIED = 57, VXIinet_RESULT_UNSUPPORTED = 100 } |
|
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 |
|
Cache Control max-age Default - NULL not present by default.
|
|
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 |
|
Cache Control max-stale Default - 0, do not use expired entries.
|
|
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 |
|
Caching Default - INET_CACHING_FAST.
|
|
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. |
|
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 |
|
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 |
|
Cookie comment, optional. Value of the key is a VXIString. |
|
Cookie comment URL, optional. Value of the key is a VXIString. |
|
Cookie domain key. Value of the key is a VXIString. |
|
Cookie expires key, calculated off the Max-Age property for the cookie. Value of the key is a VXIInteger giving time since the epoch for expiration. |
|
Cookie name. Value of the key is a VXIString. |
|
Cookie path key. Value of the key is a VXIString. |
|
Cookie port key, optional. Value of the key is a VXIInteger. |
|
Cookie secure key, optional. Value of the key is a VXIInteger set to 0 (FALSE) or 1 (TRUE). |
|
Cookie value key. Value of the key is a VXIString. |
|
Cookie standard version. Value of the key is a VXIInteger. |
|
Non-blocking reads/writes. Do all I/O using non-blocking operations. |
|
Null flag. This causes the cache to use default behavior, specifically I/O using blocking operations. |
|
Absolute Name, always returned. The absolute URI for a URI which may have been provided as a relative URI against a base. For local file access (file:// access or an OS dependant path) an OS dependant path must be returned, never a file:// URI. This should be passed unmodified as the value of the INET_URL_BASE property for fetching URIs referenced within this document, if any. Returned as a VXIString |
|
an enum of type VXIinetDataSource (see above) in the Inet streamInfo map to indicate the data source: from a local file, from the fetch cache, from the fetch cache but had to revalidate with the web server, or from a full Internet fetch.
|
|
Expires hint. Timestamp indicating when the cache entry will expire. The property is returned by Open() as a VXIInteger representing an ANSI/ISO time_t integer, representing the number of seconds since Jan 1, 1970). If the entry is already expired, a VXIInteger of value 0 is returned. This number only indicates this is the time where the request has to be made again to the remote web server. This doesn't necessarily mean that there will be new data after this time (For example, having the property INET_INFO_VALIDATOR_STRONG with an EXPIRES_HINT of 0, means the URL has to be revalidated but does not imply that the data will change. |
|
HTTP status code, always returned for successful HTTP Open( ) operations, or HTTP Open( ) operations that fail due to the remote web server returning a HTTP failure code in the HTTP response. Never returned in other cases (such as for failures for file:// fetches, or failures for HTTP fetches due to non-HTTP response failures such as TCP/IP connection failures). HTTP status code from the last HTTP response received related to the Open( ) request. Returned as a VXIInteger. For example, a successful Open( ) for a http:// URL will most commonly report a HTTP status 200 (OK), while a failed attempt will often report a HTTP status 404 (Not Found). Note that interim response codes, such as HTTP status 301 (Redirect -- Moved Permanently) should not be returned as the VXIinet implementation should respond by doing a HTTP request against the redirected location, resulting in a new HTTP status code from the new HTTP response. |
|
MIME type, always returned. The MIME type of the URI. For HTTP requests, this is set to the type returned by the HTTP server. For file: requests, a MIME mapping table is used to determine the correct MIME type. This table is also used when the HTTP server returns no MIME type or a generic type. If the MIME type cannot be determined at all, it is set to "application/octet-stream". Returned as a VXIString |
|
Size in bytes, always returned. Size of the file in bytes. For HTTP requests, this is set to the size returned by the HTTP server. If the server returns no size, or if the file size cannot be determined for file: requests, it is set to zero. Returned as a VXIInteger |
|
Validator, always returned on a successful Open( ) or when INET_OPEN_IF_MODIFIED was specified and VXIinet_RESULT_NOT_MODIFIED was returned. Opaque validator for future conditional open operations against the named object, see INET_OPEN_IF_MODIFIED for details. Returned as a VXIContent |
|
INET_INFO_VALIDATOR_STRONG. Open() must return this property as a VXIinteger with value TRUE when a strong validator is available for the page. |
|
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. |
|
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 |
|
Open If Modified Default - NULL not present by default.
|
|
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). |
|
Open Local File Default - TRUE.
|
|
Prefetch priority. For implementations supporting priority this controls the order of opens and reads for multiple current reads. Argument is a VXIInteger |
|
Prefetch priority default - INET_PREFETCH_PRIORITY_LOW.
|
|
Submit method: GET or POST. Argument is a VXIString. Default is INET_SUBMIT_METHOD_DEFAULT. |
|
Submit method default - INET_SUBMIT_METHOD_GET.
|
|
HTTP GET.
|
|
HTTP POST.
|
|
Submit MIME type. MIME type of data sent in the submit. Default is INET_SUBMIT_MIME_TYPE_DEFAULT. Argument is a VXIString |
|
Submit MIME type default - "application/x-www-form-urlencoded".
|
|
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 |
|
Total download timeout default - 30000 (30 seconds).
|
|
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 |
|
Read timeout default - 30000 (30 seconds).
|
|
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 |
|
Open timeout default - 30000 (30 seconds).
|
|
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 |
|
URL base default - "" (no base).
|
|
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). |
|
URL query arguments default - NULL not present by default.
|
|
Data source values. An enum in the Inet streamInfo map to indicate the data source: from a local file, from the fetch cache, from the fetch cache but had to revalidate with the web server, or from a full Internet fetch. |
|
Abstract interface for accessing Internet functionality including HTTP requests, local file access, URL caching, and cookie access. 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. There is one Internet interface per thread/line. |
|
Mode values for Open( ).
|
|
INET_PREFETCH_PRIORITY property values.
|
|
|
|
|
Mode values for Open( ).
|
|
INET_PREFETCH_PRIORITY property values.
|
|
|