HttpClient Struct Reference

Detailed Description

Blocking HTTP/1.1 client with optional SharkSSL HTTPS support.

Send a request, send its body if applicable, obtain response headers/status, and read the response body. Serialize access to each instance. When the dispatcher has a mutex, hold it when entering the API; blocking transport operations release and reacquire it internally.

This example streams a GET response without relying on a prior HEAD request or allocating storage for the complete response. The destination writer is owned by the caller and is not flushed here. An error can leave partial output.

int copyURL(HttpClient* http, const char* url, BufPrint* dest)
{
   char buf[512];
   int status = http->request(HttpMethod_Get, url);
   if(status == 0)
   {
      int count;
      // This example accepts only HTTP 200 responses.
      status = http->getStatus();
      if(status == 200)
      {
         status = 0;
         while((count = http->readData(buf, sizeof(buf))) > 0)
         {
            status = dest->write(buf, count);
            if(status < 0) break;
         }
         if(count < 0) status = count;
      }
      else if(status >= 0) status = -1;
   }
   http->close();
   return status;
}

Note

The parser accepts status codes 100 through 599. Informational responses are consumed until a final response, except 101 protocol switching. Chunked response trailers are validated and discarded, not exposed as headers. Chunk-size lines must be shorter than 256 bytes, excluding CRLF; the entire trailer section including its terminating CRLF is limited to 8192 bytes. Content-Encoding (for example gzip) is not decoded. Applications must check the HTTP status separately from transport success.

#include <HttpClient.h>

Inheritance diagram for HttpClient:

Public Member Functions
	HttpClient (SoDisp *disp, U8 mode=HttpClient_Persistent)
	Construct an idle client; no connection is opened. More...
	~HttpClient ()
	Close the connection and release client-owned storage. More...
void	setSSL (SharkSsl *ssl)
	Select the TLS context for future HTTPS connections. More...
void	setReadTmo (BaTime timeout)
	Set the timeout applied to individual blocking reads. More...
SharkSslConTrust	trusted (void)
	Query the current connection's certificate trust result. More...
void	setAcceptTrusted (bool acceptTrusted)
	Choose whether new connections must pass the TLS trust check. More...
int	request (HttpMethod methodType, const char *url, const char *userPass=0, const HttpClientKeyVal *query=0, const HttpClientKeyVal *headers=0, BaFileSize size=0)
	Send request headers, opening or reusing a connection. More...
int	sendData (const void *data, int len)
	Send part or all of the request body after request(). More...
int	getBufSize ()
	Query bytes already buffered beyond the response headers. More...
int	readData (void *buf, int bufSize)
	Read response body bytes, removing chunk framing when applicable. More...
const char *	getHeaderValue (const char *name)
	Look up the first response header with this name, ignoring case. More...
HttpClientHeader *	getHeaders (int *hlen)
	Obtain parsed response headers; may finish an upload and block for input. More...
void	close ()
	Shut down the connection and discard the current response state. More...
int	getStatus ()
	Obtain the HTTP status, reading response headers if no status is cached. More...
int	getError ()
	Query the stored client error without performing I/O. More...
SharkSslCon *	getSharkSslCon ()
	Access the current SharkSSL connection. More...
SoDispCon *	getSoDispCon ()
	Access the embedded transport object. More...
Public Member Functions inherited from SoDispCon
	SoDispCon ()
	Uninitialized storage; call SoDispCon_constructor before use. More...
int	connect (const char *host, U16 port, const void *bindIntfName=0, U16 bindPort=0, U32 timeout=1500, BaBool dgram=false, BaBool ipv6=false, char **errinfo=0)
	Connect an initialized, empty connection to a remote endpoint. More...
bool	isSecure ()
	Deprecated: Use getSharkSslCon(NULL). More...
bool	getSharkSslCon (SharkSslCon **sc)
	Inspect a connected transport's TLS implementation. More...
bool	isValid ()
bool	isIP6 ()
int	getPeerName (HttpSockaddr *addr, U16 *port=0)
	Read the remote peer endpoint. More...
int	getSockName (HttpSockaddr *addr, U16 *port=0)
	Read the local socket endpoint. More...
char *	addr2String (HttpSockaddr *addr, char *buf, int len)
	Format a numeric address without a port number. More...
bool	cmpAddr (HttpSockaddr *addr2)
	Compare an address with the current peer address, ignoring port numbers. More...
void	setTCPNoDelay (bool enable)
	Disable the TCP delay. More...
struct SoDisp *	getDispatcher ()
bool	hasMoreData ()
bool	dispatcherHasCon ()
bool	recEvActive ()
bool	sendEvActive ()
void	setDispSendEvent (SoDispCon_DispSendEv ev)
	Install a send-ready callback before enabling send events. More...
void	setDispRecEvent (SoDispCon_DispRecEv ev)
	Install a receive callback before enabling receive events. More...
int	readData (void *data, int len, bool relmutex=false)
	Read through the installed transport using its recorded readiness. More...
int	setNonblocking ()
	Select nonblocking socket mode. More...
int	setBlocking ()
	Select blocking socket mode. More...
int	sendData (const void *data, int len)
	Send an entire buffer through the installed transport. More...
int	asyncSend (int len)
	Begin or advance a send from the transport's asynchronous buffer. More...
int	sendChunkData (const void *data, int len)
	Send one HTTP chunk, including its hexadecimal size and CRLF delimiters. More...
int	asyncReady ()
	Advance pending output and inspect completion. More...
void *	allocAsynchBuf (int *size)
	Obtain transport-owned writable storage for asynchronous sending. More...

Static Public Member Functions
static int	isURL (const char *url)
	Classify a URL scheme; this does not validate the complete URL. More...

Public Attributes
const char *	proxy
	Borrowed proxy host string, or NULL for a direct connection. More...
const char *	proxyUserPass
	Borrowed proxy credentials "user:password", or NULL. More...
const char *	intfName
	Borrowed local interface name/address, or NULL for the default binding. More...
U16	proxyPortNo
	Proxy TCP port, 1 through 65535 when proxy is configured. More...

Member Data Documentation

intfName

const char* HttpClient::intfName

Borrowed local interface name/address, or NULL for the default binding.

Set before connecting; retain while configured.

proxy

const char* HttpClient::proxy

Borrowed proxy host string, or NULL for a direct connection.

Set before connecting; retain while configured.

proxyPortNo

U16 HttpClient::proxyPortNo

Proxy TCP port, 1 through 65535 when proxy is configured.

proxyUserPass

const char* HttpClient::proxyUserPass

Borrowed proxy credentials "user:password", or NULL.

Set before connecting; retain while configured.