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

VXIinetInterface Struct Reference
[Internet Interface]

#include <VXIinet.h>

List of all members.


Detailed Description

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.


Public Attributes

VXIint32(* GetVersion )(void)
 Get the VXI interface version implemented.
const VXIchar *(* GetImplementationName )(void)
 Get the name of the implementation.
VXIinetResult(* Prefetch )(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, VXIinetOpenMode mode, VXIint32 flags, const VXIMap *properties)
 Prefetch information (non-blocking).
VXIinetResult(* Open )(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, VXIinetOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIinetStream **stream)
 Open a stream for reading or writing.
VXIinetResult(* Close )(struct VXIinetInterface *pThis, VXIinetStream **stream)
 Close a previously opened stream Close a stream that was previously opened.
VXIinetResult(* Read )(struct VXIinetInterface *pThis, VXIbyte *buffer, VXIulong buflen, VXIulong *nread, VXIinetStream *stream)
 Read from a stream.
VXIinetResult(* Write )(struct VXIinetInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIinetStream *stream)
 Write to a stream.
VXIinetResult(* SetCookieJar )(struct VXIinetInterface *pThis, const VXIVector *jar)
 Set the cookie jar.
VXIinetResult(* GetCookieJar )(struct VXIinetInterface *pThis, VXIVector **jar, VXIbool *changed)
 Get the cookie jar.
VXIinetResult(* GetAbsoluteName )(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, const VXIMap *properties, VXIString **absoluteName)
 Get absolute URI.


Member Data Documentation

VXIinetResult(* VXIinetInterface::Close)(struct VXIinetInterface *pThis, VXIinetStream **stream)
 

Close a previously opened stream Close a stream that was previously opened.

Closing a NULL or previously closed stream will result in an error.

Parameters:
stream [IN/OUT] Stream to close
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::GetAbsoluteName)(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, const VXIMap *properties, VXIString **absoluteName)
 

Get absolute URI.

To get the canonical absolute URI from a base/relative URI pair.

Parameters:
moduleName [IN] Name of the software module that is outputting the error. See the top of VXIlog.h for moduleName allocation rules.
name [IN] Name of the data to canonicalize, see above for supported types
properties [IN] Properties to control the canonicalization, 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
absoluteName [OUT] The absolute URI after the canonicalization, may be NULL if an error occured.
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::GetCookieJar)(struct VXIinetInterface *pThis, VXIVector **jar, VXIbool *changed)
 

Get the cookie jar.

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.

Parameters:
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.
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.
Returns:
VXIinet_RESULT_SUCCESS on success

const VXIchar*(* VXIinetInterface::GetImplementationName)(void)
 

Get the name of the implementation.

Returns:
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.

VXIint32(* VXIinetInterface::GetVersion)(void)
 

Get the VXI interface version implemented.

Returns:
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.

VXIinetResult(* VXIinetInterface::Open)(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, VXIinetOpenMode mode, VXIint32 flags, const VXIMap *properties, VXIMap *streamInfo, VXIinetStream **stream)
 

Open a stream for reading or writing.

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).

For URLs, the only accepted unsafe characters are: { } [ ] ^ ~ ' They will be escaped if only when processing a HTTP request.

Parameters:
moduleName [IN] Name of the software module that is outputting the error. See the top of VXIlog.h for moduleName allocation rules.
name [IN] Name of the data to fetch, see above for supported types
mode [IN] Mode to open the data with, an INET_MODE value as defined above
flags [IN] Flags to control the open: INET_FLAG_NONBLOCKING_IO, non-blocking reads and writes, although the open and close is still blocking
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
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
stream [OUT] Handle to the opened stream
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::Prefetch)(struct VXIinetInterface *pThis, const VXIchar *moduleName, const VXIchar *name, VXIinetOpenMode mode, VXIint32 flags, const VXIMap *properties)
 

Prefetch information (non-blocking).

Note that this is optional, it does not need to be called prior to Open( ).

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).

Parameters:
moduleName [IN] Name of the software module that is outputting the error. See the top of VXIlog.h for moduleName allocation rules.
name [IN] Name of the data to fetch, see Open( ) for a description of supported types
mode [IN] Reserved for future use, pass INET_MODE_READ
flags [IN] Reserved for future use, pass 0
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
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::Read)(struct VXIinetInterface *pThis, VXIbyte *buffer, VXIulong buflen, VXIulong *nread, VXIinetStream *stream)
 

Read from a stream.

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.

Parameters:
buffer [OUT] Buffer that will receive data from the stream
buflen [IN] Length of buffer, in bytes
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
stream [IN] Handle to the stream to read from
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::SetCookieJar)(struct VXIinetInterface *pThis, const VXIVector *jar)
 

Set the cookie jar.

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.

Parameters:
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).
Returns:
VXIinet_RESULT_SUCCESS on success

VXIinetResult(* VXIinetInterface::Write)(struct VXIinetInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIinetStream *stream)
 

Write to a stream.

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.

Parameters:
buffer [OUT] Buffer of data to write to the stream
buflen [IN] Number of bytes to write
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
stream [IN] Handle to the stream to write to
Returns:
VXIinet_RESULT_SUCCESS on success


The documentation for this struct was generated from the following file:
Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2