Barracuda Application Server C/C++ Reference
NO
The HTTP(S) client library.

Detailed Description

The HttpClient library is the C side implementation for the Lua httpc library. The library is also used internally by the NetIo network file system. See the Lua HTTP client for an introduction to this library.

This documentation is for the C++ API defined in the headers. See the introduction to object oriented code in C for an introduction to the C API's.

The HTTP client library can also be compiled into a standalone library. The HTTP client source code requires a few runtime files from the Barracuda Server such as the SoDisp, BufPrint, DynBuffer, HttpConnection, HttpServCon, and HttpSocket.

The HTTP client library can also be used standalone together with the SharkSSL SSL/TLS stack when secure HTTP (HTTPS) is required.

Collaboration diagram for The HTTP(S) client library.:

Classes

struct  HttpClientKeyVal
 A container for key/value pairs that is used when setting custom HTTP headers and/or when setting URL encoded HTTP parameters. More...
 
struct  HttpClientHeader
 The response HTTP headers returned by HttpClient::getHeaders. More...
 
struct  HttpClient
 The HTTP(S) "C" client library implementation conforms to the HTTP/1.1 standard, RFC 2616. More...
 

Typedefs

typedef struct HttpClientKeyVal HttpClientKeyVal
 A container for key/value pairs that is used when setting custom HTTP headers and/or when setting URL encoded HTTP parameters. More...
 
typedef HttpClient HttpClient
 The HTTP(S) "C" client library implementation conforms to the HTTP/1.1 standard, RFC 2616. More...
 

Functions

 HttpClient::HttpClient (SoDisp *disp, U8 mode=HttpClient_Persistent)
 Create a HttpClient instance. More...
 
 HttpClient::~HttpClient ()
 Terminate the HttpClient.
 
void HttpClient::setSSL (SharkSsl *ssl)
 Set the SharkSSL client object to enable https: URL's. More...
 
void HttpClient::setReadTmo (BaTime timeout)
 Set the read timeout (in milliseconds). More...
 
static int HttpClient::isURL (const char *url)
 Returns true if the URL is valid.
 
SharkSslConTrust HttpClient::trusted (void)
 Returns the peer's "trust" status. More...
 
void HttpClient::setAcceptTrusted (bool acceptTrusted)
 Force method HttpClient::request to accept only trusted connections when connecting to a server. More...
 
SharkSslCon * HttpClient::getSharkSslCon ()
 Wrapper for SoDispCon:getSharkSslCon.
 
int HttpClient::request (HttpMethod methodType, const char *url, const char *userPass=0, const HttpClientKeyVal *query=0, const HttpClientKeyVal *headers=0, BaFileSize size=0)
 
int HttpClient::sendData (const void *data, int len)
 Send data to the server. More...
 
int HttpClient::readData (void *buf, int bufSize)
 Read HTTP response data. More...
 
const char * HttpClient::getHeaderValue (const char *name)
 Returns the value for the header 'name' or NULL if the header is not in the response. More...
 
HttpClientHeaderHttpClient::getHeaders (int *hlen)
 Returns all HTTP response headers. More...
 
void HttpClient::close ()
 Close a persisten HTTP 1.1 connection.
 
int HttpClient::getStatus ()
 Returns the server's HTTP response code or a negative value on socket errors.
 
int HttpClient::getError ()
 Returns the last socket error code if any. More...
 
const char * HttpClientHeader::getKey (HttpClient *c)
 Returns the key.
 
const char * HttpClientHeader::getVal (HttpClient *c)
 Returns the value.
 

Typedef Documentation

◆ HttpClient

The HTTP(S) "C" client library implementation conforms to the HTTP/1.1 standard, RFC 2616.

The following example shows how to create a function that loads the response from a server that either returns static content with a known content length or from a server that returns dynamically created data using chunk encoding.

A server can send a content length or chunk encoding for dynamically generated data. We can trick the server into sending a content-length even for dynamically generated data by sending a head request. Knowing the content length makes it easier to allocate a storage buffer.

char* loadURL(HttpClient* http, const char* url, int* contentLen)
{
*contentLen = 0;
if( ! http->request(HttpMethod_Head, url) )
{
long int len;
const char* cl = http->getHeaderValue("Content-Length");
if(cl && http->getStatus() == 200)
{
len = strtol(cl, NULL, 10);
if(len > 0 && len < 30*1024 && //We do not want to alloc more than 30K
! http->request(HttpMethod_Get, url) && http->getStatus())
{
*contentLen = len;
char* buf = (char*)malloc(len+1); // +1 for strings (REF-S)
if(buf)
{
char* ptr=buf;
while(len)
{
int chunkLen = http->readData(ptr, len);
if(chunkLen <= 0)
break; //Failed: -1 on err. 0 not accepted
len -= chunkLen;
ptr += chunkLen;
assert(len >= 0);
}
if( ! len ) // if OK
{
// REF-S: Zero terminate.
// Can be used by caller if buf is a string.
*ptr=0;
return buf;
}
}
free(buf);
}
}
}
return NULL; // failed
}

◆ HttpClientKeyVal

A container for key/value pairs that is used when setting custom HTTP headers and/or when setting URL encoded HTTP parameters.

HttpClientKeyVal can be statically declared at compile time or be dynamically created during runtime. A dynamically created HttpClientKeyVal can be released as soon as HttpClient::request returns.

Example code:

HttpClientKeyVal myHeaders[]={
{"the-header-name","the header value"},
{"foo","bar"},
{0,0} // Terminator
};

Function Documentation

◆ getError()

int HttpClient::getError ( )

Returns the last socket error code if any.

The function is typically called if the response fails. The error codes are documented in BaErrorCodes.h.

◆ getHeaders()

HttpClientHeader * HttpClient::getHeaders ( int *  hlen)

Returns all HTTP response headers.

Example:

int hlen;
for(header=http.getHeaders(&hlen); hlen > 0 ; header++,hlen--)
{
printf("%s: %s\n",header->getKey(&http), header->getVal(&http));
}

◆ getHeaderValue()

const char * HttpClient::getHeaderValue ( const char *  name)

Returns the value for the header 'name' or NULL if the header is not in the response.

Parameters
namethe header key.

◆ HttpClient()

HttpClient::HttpClient ( SoDisp disp,
U8  mode = HttpClient_Persistent 
)

Create a HttpClient instance.

The following example shows how to use one (non threaded) instance of the HttpClient library. We set the mutex in SoDisp to NULL since we do not use threading. You must set a mutex and lock this mutex prior to calling any HttpClient methods if you use the HttpClient library simultaneously in multiple threads.

SoDisp disp(NULL);
HttpClient http(&disp);
Parameters
dispthe Barracuda platform's socket dispatcher is the interface between Barracuda code and the native TCP/IP stack.
modecan be a combination of the following: HttpClient_Persistent, HttpClient_SocksProxy, HttpClient_IPv6

HttpClient_Persistent: Use a persistent HTTP 1.1 connection

HttpClient_IPv6: Force the use of hostname to IPv6 address translation if applicable to the TCP/IP stack.

HttpClient_SocksProxy: Use socks proxy, not HTTPS proxy.

Proxy support is enabled by manually setting the following attributes:

  • proxy: Proxy name/IP addr, if any
  • proxyUserPass: Format: "user:password"

◆ readData()

int HttpClient::readData ( void *  buf,
int  bufSize 
)

Read HTTP response data.

Returns
the size read, 0 when no more data, and a negative value on socket errors.

◆ request()

int HttpClient::request ( HttpMethod  methodType,
const char *  url,
const char *  userPass = 0,
const HttpClientKeyVal query = 0,
const HttpClientKeyVal headers = 0,
BaFileSize  size = 0 
)
Parameters
methodTypeis one of:
  • HttpMethod_Delete
  • HttpMethod_Get
  • HttpMethod_Head
  • HttpMethod_Patch
  • HttpMethod_Post
  • HttpMethod_Put
urlmust be a valid URL such as https://realtimelogic.com/
userPassuse basic authentication if not NULL. Format: "user:password"
queryoptional HTTP parameters. A table with key value pairs. Includes url encoded data in the query component of the request URL.
headersoptional (custom) HTTP headers.
sizeis an optional length when sending data to a server using POST or PUT. The client sends data using chunked transfer encoding if no size is specified.
Returns
zero on succsss.

◆ sendData()

int HttpClient::sendData ( const void *  data,
int  len 
)

Send data to the server.

The data is sent using chunk encoding if param size of method request was set to zero.

Parameters
dataa chunk of data or the complete data you are sending to the server.
lenis the data length.
Returns
0 on success and a negative value on socket errors.

◆ setAcceptTrusted()

void HttpClient::setAcceptTrusted ( bool  acceptTrusted)

Force method HttpClient::request to accept only trusted connections when connecting to a server.

Setting this to boolean true makes HttpClient::request internally call HttpClient::trusted when connecting to a server and before sending any data to the server. The HttpClient::request will return the error code E_NOT_TRUSTED if HttpClient::trusted returns a value other than 1.

◆ setReadTmo()

void HttpClient::setReadTmo ( BaTime  timeout)

Set the read timeout (in milliseconds).

The default value is 20 secs.

◆ setSSL()

void HttpClient::setSSL ( SharkSsl ssl)

Set the SharkSSL client object to enable https: URL's.

Example:

//See the SharkSSL documentation for details on the SharkSSL API's.
//The SharkSSL documentation is provided as a PDF file.
SharkSsl* shark = allocate object or use a static object;
SharkSsl_constructor(SharkSsl_Client,0,2,3072,3072,0);
http->setSSL(shark);

◆ trusted()

SharkSslConTrust HttpClient::trusted ( void  )

Returns the peer's "trust" status.

See SharkSslConTrust in the SharkSSL documentation for more information.

HttpClientHeader::getKey
const char * getKey(HttpClient *c)
Returns the key.
Definition: HttpClient.h:512
SoDisp
The SoDisp dispatches any socket connection that contains data by calling the SoDispCon::execute memb...
Definition: SoDisp.h:86
HttpClient::getHeaders
HttpClientHeader * getHeaders(int *hlen)
Returns all HTTP response headers.
Definition: HttpClient.h:491
HttpClient::setSSL
void setSSL(SharkSsl *ssl)
Set the SharkSSL client object to enable https: URL's.
Definition: HttpClient.h:438
HttpClientKeyVal
A container for key/value pairs that is used when setting custom HTTP headers and/or when setting URL...
Definition: HttpClient.h:86
HttpClient
The HTTP(S) "C" client library implementation conforms to the HTTP/1.1 standard, RFC 2616.
Definition: HttpClient.h:188
HttpClientHeader::getVal
const char * getVal(HttpClient *c)
Returns the value.
Definition: HttpClient.h:515
HttpClient::readData
int readData(void *buf, int bufSize)
Read HTTP response data.
Definition: HttpClient.h:483
HttpClient::request
int request(HttpMethod methodType, const char *url, const char *userPass=0, const HttpClientKeyVal *query=0, const HttpClientKeyVal *headers=0, BaFileSize size=0)
Definition: HttpClient.h:465
HttpClientHeader
The response HTTP headers returned by HttpClient::getHeaders.
Definition: HttpClient.h:96
HttpClient::getHeaderValue
const char * getHeaderValue(const char *name)
Returns the value for the header 'name' or NULL if the header is not in the response.
Definition: HttpClient.h:487
HttpClient::getStatus
int getStatus()
Returns the server's HTTP response code or a negative value on socket errors.
Definition: HttpClient.h:499
SharkSsl
Definition: selib.h:257