libdas2
das2 core C utilities
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Data Structures | Typedefs | Functions
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...
 
DasArydas_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
sServerThe server name
sRealmThe authorization realm on this server, can be same as the dataset
sDatasetThe name of the dataset on this server
sMessageAn additional message that may be supplied, such as "The user name cannot contain a colon, ':', character"
sUsera pointer to 128 bytes of storage to hold the username
sPassworda 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
sUrlThe location to connect to, will be URL encoded before transmission
sAgentThe user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgrA credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested.
pResA pointer to a response object that will be filled in with the result of the connection attempt. This contains the headers error messages etc.
rConSecIf > 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.
sAgentThe user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgrA credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested.
pResA 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
nLimitAn 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
    rConSecIf > 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
pCredA pointer to a das_credentials structure
sServerThe name of the server, ex: 'jupiter.physics.uiowa.edu'
sRealmThe authentication realm. This is provided in the dsdf files under the securityRealm keyword.
sDatasetThe 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.
sHashThe hash value. Currently the library only supports HTTP Basic Authentication hashes. i.e. a USERNAME:PASSWORD string that has been base64 encoded.