Network

HTTP and HTTPs network operations and authentication. More...

Detailed Description

HTTP and HTTPs network operations and authentication.

Data Structures
struct	das_credential
	A single credential. More...
struct	DasCredMngr
	Credentials manager Handles a list of login credentials and supplies these as needed for network operations. More...
struct	das_url
	A parsed URL structure. More...
struct	DasHttpResp
	Encapsulates the status of a HTTP resource request. More...

Typedefs
typedef bool(*	das_prompt )(const char *sServer, const char *sRealm, const char *sDataset, const char *sMessage, char *sUser, char *sPassword)
	Function signature for swapping out the user-prompt for credentials acquisition. More...

Functions
char *	das_ssl_getErr (const void *vpSsl, int nRet)
	Get a new string allocated on the heap explaining an SSL error or NULL in nRet == 0. More...
bool	das_http_getBody (const char *sUrl, const char *sAgent, DasCredMngr *pMgr, DasHttpResp *pRes, float rConSec)
	Get a socket positioned at the start of a remote resource. More...
DasAry *	das_http_readUrl (const char *sUrl, const char *sAgent, DasCredMngr *pMgr, DasHttpResp *pRes, int64_t nLimit, float rConSec)
	Read all the bytes for a URL into a byte array. More...
bool	das_cred_init (das_credential *pCred, const char *sServer, const char *sRealm, const char *sDataset, const char *sHash)
	Initialize a credential to be cached in the credentials manager. More...

Typedef Documentation

typedef bool(* das_prompt)(const char *sServer, const char *sRealm, const char *sDataset, const char *sMessage, char *sUser, char *sPassword)

Function signature for swapping out the user-prompt for credentials acquisition.

Parameters

sServer	The server name
sRealm	The authorization realm on this server, can be same as the dataset
sDataset	The name of the dataset on this server
sMessage	An additional message that may be supplied, such as "The user name cannot contain a colon, ':', character"
sUser	a pointer to 128 bytes of storage to hold the username
sPassword	a pointer to 128 bytes of storage to hold the password

Returns

true if the user entered a user name and password (even empty ones) and false if the prompt was canceled.

Function Documentation

char* das_ssl_getErr	(	const void *	vpSsl,
		int	nRet
	)

Get a new string allocated on the heap explaining an SSL error or NULL in nRet == 0.

To prevent memory leaks, caller must free string if return is NON null.

bool das_http_getBody	(	const char *	sUrl,
		const char *	sAgent,
		DasCredMngr *	pMgr,
		DasHttpResp *	pRes,
		float	rConSec
	)

Get a socket positioned at the start of a remote resource.

This function makes a connection to a remote HTTP or HTTPS server, reads through the HTTP headers and then passes the socket descriptor and possibly an SSL connection object back to the caller.

If a redirect response is detected, the initial connection is dropped and a new one is made to the indicated location.

If the GET request fails due to needing authentication, the given credential manager is consulted for a username and password. If one is present that matches the URL path (and optionally the dataset, see below) then it is used, otherwise the manager's getPassword function is called and another attempt is made. The cycle continues until the connection succeeds or getPassword fails.

Meta details about the connection including the body mime-type and any error messages are stored in the sHeaders element of the DasHttpResp structure.

It is the caller's responsibility to call shutdown for the provided socket descriptor or the SSL connection when it is finished reading the message body.

Das2 Note: Since das2 servers can request different authentication for each dataset, the get string is inpected for the 'server=dataset' pair. If found the URL saved in the credentials manager will be http://SERVER/path?dataset=DATASET instead of just http://SERVER/path. This a bit of a hack and a better solution should be found in the future.

Parameters

sUrl	The location to connect to, will be URL encoded before transmission
sAgent	The user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgr	A credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested.
pRes	A pointer to a response object that will be filled in with the result of the connection attempt. This contains the headers error messages etc.
rConSec	If > 0.0 this is the floating point number of seconds to wait on a connection before giving up. If 0.0 or less then operating system defaults are used. Typical OS default is about five minutes. This value only affects the initial connection timeout and not the wait time for data to appear.

Returns

true if pRes->nSockFd, or pRes->pSsl is ready for reading, false otherwise.

DasAry* das_http_readUrl	(	const char *	sUrl,
		const char *	sAgent,
		DasCredMngr *	pMgr,
		DasHttpResp *	pRes,
		int64_t	nLimit,
		float	rConSec
	)

Read all the bytes for a URL into a byte array.

Since network operations are presumed to fail often, all errors are logged using the functions in log.h, das_error is not called unless a memory allocation error occurs.

Parameters

sUrl	- The URL to read, may be http or https contain alternate port numbers etc.
sAgent	The user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgr	A credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested.
pRes	A pointer to a http response object that will hold the headers from the final destination. Due to redirects the URL in the response may not be the same as the initial one provided in sUrl
nLimit	An upper limit on the number of bytes to download, if less than 1 then limit checks are disabled and download will continue until complete, a socket error occurs, or no additional memory can be allocated. The actual amount of data read maybe upto 32K - 1 bytes more than the given limit.

• Parameters

  rConSec

  If > 0.0 this is the floating point number of seconds to wait on a connection before giving up. If 0.0 or less then operating system defaults are used. Typical OS default is about five minutes. This value only affects the initial connection timeout and not the wait time for data to appear.

  Returns

  A 1-dimensional DasAry with element type vtByte allocated on the heap, or NULL if the download failed.

  The ID member of the allocated array will correspond to the last component of the URL path, not including any fragments, or if accessing the root of a server, then the host name will be used.

bool das_cred_init	(	das_credential *	pCred,
		const char *	sServer,
		const char *	sRealm,
		const char *	sDataset,
		const char *	sHash
	)

Initialize a credential to be cached in the credentials manager.

Parameters

pCred	A pointer to a das_credentials structure
sServer	The name of the server, ex: 'jupiter.physics.uiowa.edu'
sRealm	The authentication realm. This is provided in the dsdf files under the securityRealm keyword.
sDataset	The dataset, ex: 'Juno/WAV/Survey' The dataset is typically determined by the http module by URL inspection. If this credentials manager is used for a general URL then the http module will not specify the the dataset. To match those sites, use NULL here.
sHash	The hash value. Currently the library only supports HTTP Basic Authentication hashes. i.e. a USERNAME:PASSWORD string that has been base64 encoded.