libdas2
das2 core C utilities
|
HTTP and HTTPs network operations and authentication. More...
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 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.
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 |
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.
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. |
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.
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. |
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. |
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.
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. |