NetIo Struct Reference

Detailed Description

The NetIo is similar to a network file system and makes it possible for the server to access resources on another Barracuda server.

The NetIo is a web file manager client specifically designed to operate a remote HttpResMgr. In other words, the remote HttpResMgr's file system appears as a local file system to code using an instance of the NetIo class.

The NetIo is typically used during development of LSP code in an embedded device without a file system. The device can access resources on for example a remote Windows computer as if the resources are locally on the device.

It is recommended to increase the size of the Web server's default HTTP response buffer if NetIo is configured as the I/O for a HttpResRdr, HttpResMgr, or a WebDAV instance. A size of 8Kbytes can reduce remote read requests compared with a small buffer; the benefit depends on the resources and access pattern. See HttpServerConfig::setResponseData for more information.

The NetIo code, which can be found in xrc/misc/NetIo.c, is delivered as example code. You must therefore include this code in your build if you intend to use NetIo. Serialize configuration changes with file operations; the internal I/O mutex does not protect all setters.

#include <NetIo.h>

Inheritance diagram for NetIo:

Public Member Functions
	NetIo (struct SoDisp *disp=0)
	The NetIo constructor. More...
	~NetIo ()
	Close the cached HTTP client and free copied configuration and its mutex. More...
int	setRootDir (const char *url)
	Initialize/set the URL to the far side Barracuda server. More...
int	setUser (const char *user, const char *password)
	Set HTTP Basic authentication credentials and discard the cached client. More...
int	setProxy (const char *proxy, U16 portNo, BaBool useSocksProxy)
	Set proxy. More...
int	setProxyUser (const char *user, const char *password)
	Set copied proxy authentication credentials; discard the cached client. More...
int	setIntfName (const char *intfName)
	Select the local interface for future HTTP clients. More...
void	setIPv6 (bool enable)
	Select the address family and discard the cached client. More...
void	setSSL (struct SharkSsl *sharkSslClient)
	Configure TLS for future HTTP clients. More...

Additional Inherited Members
Public Attributes inherited from IoIntf
IoIntf_Property	propertyFp
	Set or get property. More...
IoIntf_CloseDir	closeDirFp
	Close directory. More...
IoIntf_MkDir	mkDirFp
	Make directory. More...
IoIntf_Rename	renameFp
	Rename resource. More...
IoIntf_OpenDir	openDirFp
	Open directory. More...
IoIntf_OpenRes	openResFp
	Open resource. More...
IoIntf_OpenResGzip	openResGzipFp
	Open file as a compressed gzip file. More...
IoIntf_Remove	removeFp
	Remove file. More...
IoIntf_RmDir	rmDirFp
	Remove directory. More...
IoIntf_Stat	statFp
	Get resource information. More...

Constructor & Destructor Documentation

NetIo()

NetIo::NetIo

(

struct SoDisp *

disp = 0

)

The NetIo constructor.

A NetIo instance cannot be used before it is initialized by calling NetIo::setRootDir.

Parameters

disp

Borrowed dispatcher (default NULL), valid throughout use. This optional parameter that makes the integrated NetIo HTTP client release the dispatcher mutex when reading from or writing to the socket. The 'disp' parameter is typically set if the NetIo class is used by a Barracuda Web Server object such as a HttpResRdr instance.

~NetIo()

NetIo::~NetIo

(

)

Close the cached HTTP client and free copied configuration and its mutex.

Close open resources/iterators and stop callers first. Does not destroy the borrowed dispatcher or TLS client.

Member Function Documentation

setIntfName()

int NetIo::setIntfName

(

const char *

intfName

)

Select the local interface for future HTTP clients.

Parameters

[in]

intfName

Copied NUL-terminated platform interface/address, or NULL to use the default. Does not replace an already cached client.

Returns

Zero success, E_MALLOC allocation failure. Old value is discarded.

setIPv6()

void NetIo::setIPv6

(

bool

enable

)

Select the address family and discard the cached client.

Parameters

[in]

enable

True selects IPv6, false IPv4 (initial default).

setProxy()

int NetIo::setProxy	(	const char *	proxy,
		U16	portNo,
		BaBool	useSocksProxy
	)

Set proxy.

Parameters

proxy	Copied NUL-terminated proxy hostname/address, or NULL to disable.
portNo	Proxy TCP port in host byte order, 1..65535 when enabled.
useSocksProxy	FALSE selects the HTTP CONNECT proxy path; TRUE selects SOCKS5. This is a proxy protocol choice, not a promise of encrypted communication with the proxy itself.

Returns

Zero success, E_MALLOC allocation failure. Discards the cached client and changes proxy mode before allocating the new address.

setProxyUser()

int NetIo::setProxyUser	(	const char *	user,
		const char *	password
	)

Set copied proxy authentication credentials; discard the cached client.

Parameters

[in]	user	NUL-terminated username, or NULL to clear credentials.
[in]	password	NUL-terminated password, or NULL when user already contains user:password. Configure before opening remote resources.

Returns

Zero success, E_MALLOC allocation failure; old credentials are discarded before allocation.

setRootDir()

int NetIo::setRootDir

(

const char *

url

)

Initialize/set the URL to the far side Barracuda server.

The URL must identify the root of a HttpResMgr or a subdirectory within a HttpResMgr instance. As an example, a far side Barracuda server, with a HttpResMgr instance installed in the Virtual File System at URI /drive/ can be initialized as follows:

Base url: http://domainname/drive/
Sub-directory: http://domainname/drive/c/lsp/

In the second example above, the far side HttpResMgr is mapped to the root of the Windows computer. The path /c/lsp/ is to a directory where the files to a LSP application can be found.

The NetIo instance can also access a remote HttpResMgr protected by an authenticator as long as the far side authenticator accepts Basic authentication. In other words, the far side authenticator must be BasicAuthenticator or Authenticator.

Parameters

url	Required NUL-terminated HTTP(S) URL to the remote HttpResMgr directory, copied and normalized with a trailing slash. Example: http://192.168.1.100/fs/. Configure authentication and TLS first.

Returns

Zero after the remote stat confirms a directory; E_INVALID_URL for an invalid URL, E_MALLOC for allocation failure, IOINTF_ENOENT for a nondirectory, or another I/O/network status. This operation performs network I/O. The previous root is discarded even if the change fails; a failed instance must receive a valid root before normal file operations.

setSSL()

void NetIo::setSSL

(

struct SharkSsl *

sharkSslClient

)

Configure TLS for future HTTP clients.

Parameters

[in]

sharkSslClient

Borrowed initialized SharkSsl_Client, valid until NetIo and its HTTP clients are destroyed; NULL disables TLS setup. Configure before setRootDir for HTTPS. Does not replace a cached client or transfer ownership. Certificate policy belongs to the TLS setup.

setUser()

int NetIo::setUser	(	const char *	user,
		const char *	password
	)

Set HTTP Basic authentication credentials and discard the cached client.

Parameters

[in]	user	NUL-terminated username, or NULL to clear credentials.
[in]	password	NUL-terminated password; if NULL, user must contain the complete user:password string. Strings are copied.

Returns

Zero success, E_MALLOC allocation failure. Old credentials are discarded before allocation, so failure is not a rollback.