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

VXIinetInterface Implementation


Detailed Description

SBinet interface, and implementation of VXIinetInterface for Internet functionality, including HTTP requests, local file access, URL caching, memory buffer 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.

This implementation currently does NOT support INET_MODE_WRITE for http:// access (HTTP PUT), and only supports http://, file://, and OS dependant paths.

There is one Internet interface per thread/line.


SBInet Properties

Properties used in the VXIMap configParams arguments to SBinetInitEx.

#define SBINET_EXTENSION_RULES   L"com.vocalocity.inet.extension.rules"
 Rules for mapping file extensions to MIME content types, used for that purpose when accessing local files and file:// URLs.
#define SBINET_PROXY_RULES   L"com.vocalocity.inet.proxy.rules"
 Rules for determining the proxy to use for given domains.
#define SBINET_PAGE_LOADING_TIMEOUT   L"com.vocalocity.inet.pageLoadingTimeout"
 Default timeout for fetching a page when not explicitely specified through the INET_TIMEOUT_DOWNLOAD property in the properties VXIMap argument of the VXIinterface::Open() function.
#define SBINET_PAGE_LOADING_TIMEOUT_DEFAULT   60000
 Default value for SBINET_PAGE_LOADING_TIMEOUT.
#define SBINET_FRESHNESS_FRACTION   L"com.vocalocity.inet.freshnessFraction"
 Properties used to estimate the cache lifetime of URIs that only have the Last-Modified header defined.
#define SBINET_FRESHNESS_LIFETIME   L"com.vocalocity.inet.freshnessLifetime"
#define SBINET_FRESHNESS_FRACTION_DEFAULT   0.1
 Default value for SBINET_FRESHNESS_FRACTION.
#define SBINET_FRESHNESS_LIFETIME_DEFAULT   86400
 Default value for SBINET_FRESHNESS_LIFETIME.
#define SBINET_MAX_LIFETIME   L"com.vocalocity.inet.maxLifetime"
 If returned paged from web server do not contain any caching information nor any Last-Modified header, this is the amount of time (number of seconds) that the page will be considered fresh before a new HTTP request is performed for this page.
#define SBINET_MAX_LIFETIME_DEFAULT   0
 Default value for SBINET_MAX_LIFETIME.
#define SBINET_POST_CONTINUE_TIMEOUT   L"com.vocalocity.inet.postContinueTimeout"
 Number of milliseconds that a POST-request should wait for a response.
#define SBINET_POST_CONTINUE_TIMEOUT_DEFAULT   5000
 Default value for SBINET_POST_CONTINUE_TIMEOUT.
#define SBINET_USER_AGENT_NAME   L"com.vocalocity.inet.userAgentName"
 Property specifiying tsent in all HTTP messages.
#define SBINET_PERSISTENT_CONNECTIONS   L"com.vocalocity.inet.usePersistentConnections"
 Properties allowing to disable persistent connections.
#define SBINET_DEFAULT_MIME_TYPE   L"com.vocalocity.inet.defaultMimeType"
 Default MIME type returned when it was not possible to determine the MIME type of a file URI from its extension or when an HTTP server does not return MIME type information.

Defines

#define SBINET_USER_AGENT_NAME_DEFAULT   L"OpenVXITestApp/" VXI_CURRENT_VERSION_STR
 Default value for the User Agent Name parameter of SBinetInit().

Functions

SBINET_API VXIinetResult SBinetInit (VXIlogInterface *log, const VXIunsigned diagLogBase, const VXIchar *reserved1, const VXIint reserved2, const VXIint reserved3, const VXIint reserved4, const VXIchar *proxyServer, const VXIulong proxyPort, const VXIchar *userAgentName, const VXIMap *extensionRules, const VXIVector *reserved)
 Global platform initialization of SBinet.
SBINET_API VXIinetResult SBinetInitEx (VXIlogInterface *log, const VXIunsigned diagLogBase, const VXIMap *configParams)
 Global platform initialization (extended version) of SBinet.
SBINET_API VXIinetResult SBinetShutDown (VXIlogInterface *log)
 Global platform shutdown of SBinet.
SBINET_API VXIinetResult SBinetCreateResource (VXIlogInterface *log, VXIcacheInterface *cache, VXIinetInterface **inet)
 Create a new inet service handle.
SBINET_API VXIinetResult SBinetDestroyResource (VXIinetInterface **inet)
 Destroy the interface and free internal resources.


Define Documentation

#define SBINET_DEFAULT_MIME_TYPE   L"com.vocalocity.inet.defaultMimeType"
 

Default MIME type returned when it was not possible to determine the MIME type of a file URI from its extension or when an HTTP server does not return MIME type information.

#define SBINET_EXTENSION_RULES   L"com.vocalocity.inet.extension.rules"
 

Rules for mapping file extensions to MIME content types, used for that purpose when accessing local files and file:// URLs.

The associated value is a VXIMap whose keys must be an extension (period followed by the extension such as ".txt") with the value being the MIME content type for that extension.

#define SBINET_FRESHNESS_FRACTION   L"com.vocalocity.inet.freshnessFraction"
 

Properties used to estimate the cache lifetime of URIs that only have the Last-Modified header defined.

SBINET_FRESHNESS_FRACTION must be a VXIFloat between 0 and 1.

SBINET_FRESHNESS_LIFETIME must be a VXIInteger whose units are in milliseconds.

The freshness lifetime of an HTTP document having only Last-Modified information is computed as the minimum between the amount of time since the last modification multiplied by SBINET_FRESHNESS_FRACTION and SBINET_FRESHNESS_LIFETIME.

freshness = MIN((now - lastMod) * SBINET_FRESHNESS_FRACTION, SBINET_FRESHNESS_LIFETIME)

Default values are 0.1 for SBINET_FRESHNESS_FRACTION and 86400 (24 hours) for SBINET_FRESHNESS_LIFETIME.

#define SBINET_FRESHNESS_FRACTION_DEFAULT   0.1
 

Default value for SBINET_FRESHNESS_FRACTION.

#define SBINET_FRESHNESS_LIFETIME   L"com.vocalocity.inet.freshnessLifetime"
 

#define SBINET_FRESHNESS_LIFETIME_DEFAULT   86400
 

Default value for SBINET_FRESHNESS_LIFETIME.

#define SBINET_MAX_LIFETIME   L"com.vocalocity.inet.maxLifetime"
 

If returned paged from web server do not contain any caching information nor any Last-Modified header, this is the amount of time (number of seconds) that the page will be considered fresh before a new HTTP request is performed for this page.

This value must be a VXIInteger and defaults to 0 (immediate expiration) if not specified.

#define SBINET_MAX_LIFETIME_DEFAULT   0
 

Default value for SBINET_MAX_LIFETIME.

#define SBINET_PAGE_LOADING_TIMEOUT   L"com.vocalocity.inet.pageLoadingTimeout"
 

Default timeout for fetching a page when not explicitely specified through the INET_TIMEOUT_DOWNLOAD property in the properties VXIMap argument of the VXIinterface::Open() function.

This value must be a VXIInteger and the units are expressed in milliseconds. If not specified, the default timeout used is 60000 (1 minute).

#define SBINET_PAGE_LOADING_TIMEOUT_DEFAULT   60000
 

Default value for SBINET_PAGE_LOADING_TIMEOUT.

#define SBINET_PERSISTENT_CONNECTIONS   L"com.vocalocity.inet.usePersistentConnections"
 

Properties allowing to disable persistent connections.

If this property is specified and is a VXIInteger with a value of 0, then a new connection is established, by default, for each HTTP request. If this property is not specified or is not a VXIInteger with a value of 0, then persistent connections are enabled. This property is overridden by the INET_CLOSE_CONNECTION and the INET_NEW_CONNECTION properties that can be passed to the Open() method of the VXIinet interface.

#define SBINET_POST_CONTINUE_TIMEOUT   L"com.vocalocity.inet.postContinueTimeout"
 

Number of milliseconds that a POST-request should wait for a response.

This value must be a VXIInteger. Default value is 5000 (5 seconds).

#define SBINET_POST_CONTINUE_TIMEOUT_DEFAULT   5000
 

Default value for SBINET_POST_CONTINUE_TIMEOUT.

#define SBINET_PROXY_RULES   L"com.vocalocity.inet.proxy.rules"
 

Rules for determining the proxy to use for given domains.

The associated value is a VXIVector whose entries are VXIString representing a key-value pair delimited by a vertical bar ('|') the key (left of the vertical bar) represents partial URLs to which a proxy applies, and the value is of the form of proxy:port representing the proxy/port combination to be used for the corresponding domain. The partial URLs are of the form domain/path where the left of the slash ('/') represents a domain (and must start with a dot '.' or be empty) and the part after the slash represents paths on this domain. If the slash is omitted, then all paths in this domain apply. Each entry are verified for a match in the order in which they appear in the VXIVector. Also, if nothing is specified in the proxy field (after the vertical bar), it means that no proxy is used

An entry matches a URL if its domain is a suffix of the URL's domain and its path is a prefix of the URL's path.

For Example: Assuming the following vector 1) ".vocalocity.com/specialPath | proxy1:port1" 2) ".vocalocity.com |" 3) ".com | proxy1:port1" 4) " | proxy2:port2"

The following URL would use the following proxy.

www.vocalocity.com -> no proxy (rule 2) www.vocalocity.com/specialPath/index.html -> proxy1:port1 (rule1) www.foo.bar.com -> proxy1:port1 (rule3) www.mit.edu -> proxy2:port2 (rule4)

Also note that if order of rule-1 and rule-2 were reversed, than the ".vocalocity.com/specialPath" rule would never be triggered as it is more specific than the ".vocalocity.com" rule.

#define SBINET_USER_AGENT_NAME   L"com.vocalocity.inet.userAgentName"
 

Property specifiying tsent in all HTTP messages.

If specified, it must be a VXIString of the form <app>/<version> with no spaces, such as "OpenVXI/1.0". When using the OpenVXI application name or a derivative, use use VXI_CURRENT_VERSION_STR for the version. Default value is specified by SBINET_USER_AGENT_NAME_DEFAULT.

#define SBINET_USER_AGENT_NAME_DEFAULT   L"OpenVXITestApp/" VXI_CURRENT_VERSION_STR
 

Default value for the User Agent Name parameter of SBinetInit().


Function Documentation

SBINET_API VXIinetResult SBinetCreateResource VXIlogInterface log,
VXIcacheInterface cache,
VXIinetInterface **  inet
 

Create a new inet service handle.

Parameters:
log [IN] VXI Logging interface used for error/diagnostic logging, must remain a valid pointer throughout the lifetime of the resource (until SBinetDestroyResource( ) is called)
cache [IN] VXI Cache interface used for HTTP document caching, must remain a valid pointer throughout the lifetime of the resource (until SBinetDestroyResource( ) is called)
inet [IN/OUT] Will hold the created Inet resource.
Returns:
VXIinet_RESULT_SUCCESS on success

SBINET_API VXIinetResult SBinetDestroyResource VXIinetInterface **  inet  ) 
 

Destroy the interface and free internal resources.

Once this is called, the logging interface passed to SBinetCreateResource() may be released as well.

Parameters:
inet [IN/OUT] The inet resource created by SBinetCreateResource()
Returns:
VXIinet_RESULT_SUCCESS on success

SBINET_API VXIinetResult SBinetInit VXIlogInterface log,
const VXIunsigned  diagLogBase,
const VXIchar reserved1,
const VXIint  reserved2,
const VXIint  reserved3,
const VXIint  reserved4,
const VXIchar proxyServer,
const VXIulong  proxyPort,
const VXIchar userAgentName,
const VXIMap *  extensionRules,
const VXIVector *  reserved
 

Global platform initialization of SBinet.

Parameters:
log VXI Logging interface used for error/diagnostic logging, only used for the duration of this function call
reserved1 Reserved for future use
reserved2 Reserved for future use
reserved3 Reserved for future use
reserved4 Reserved for future use
proxyServer Name of the proxy server to use for HTTP access, pass a server name or IP address, or NULL to do direct HTTP access.
proxyPort Port number for accessing the proxy server.
userAgentName HTTP user agent name sent in all HTTP messages. Must be of the form <app>/<version> with no spaces, such as "OpenVXI/1.0". When using the OpenVXI application name or a derrivative, use use VXI_CURRENT_VERSION_STR for the version.
extensionRules Rules for mapping file extensions to MIME content types, used for that purpose when accessing local files and file:// URLs. Each key in the map must be an extension (period followed by the extension such as ".txt") with the value being the MIME content type for that extension. Copied internally so the pointer that is passed in still belongs to the caller.
reserved Reserved VXIVector, pass NULL
Returns:
VXIinet_RESULT_SUCCESS on success

SBINET_API VXIinetResult SBinetInitEx VXIlogInterface log,
const VXIunsigned  diagLogBase,
const VXIMap *  configParams
 

Global platform initialization (extended version) of SBinet.

Parameters:
log VXI Logging interface used for error/diagnostic logging, only used for the duration of this function call
diagLogBase VXI Diagnostic Logging Base tag.
configParams Map containing configuration parameters used to initialize SBinet. These parameters are the properties defined above. Once the function returns, this Map can safely be destroyed as it is the responsibility of SBinet to copy any data it might require after initialization.
Returns:
VXIinet_RESULT_SUCCESS on success

SBINET_API VXIinetResult SBinetShutDown VXIlogInterface log  ) 
 

Global platform shutdown of SBinet.

Parameters:
log VXI Logging interface used for error/diagnostic logging, only used for the duration of this function call
Returns:
VXIinet_RESULT_SUCCESS on success


Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2