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.

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...
HttpClientHeader *	HttpClient::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

typedef HttpClient 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

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.

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:

HttpClientHeader* header;
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

name	the 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

disp	the Barracuda platform's socket dispatcher is the interface between Barracuda code and the native TCP/IP stack.
mode	can 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

methodType	is one of: HttpMethod_Delete HttpMethod_Get HttpMethod_Head HttpMethod_Patch HttpMethod_Post HttpMethod_Put
url	must be a valid URL such as https://realtimelogic.com/
userPass	use basic authentication if not NULL. Format: "user:password"
query	optional HTTP parameters. A table with key value pairs. Includes url encoded data in the query component of the request URL.
headers	optional (custom) HTTP headers.
size	is 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

data	a chunk of data or the complete data you are sending to the server.
len	is 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.