MityDSP::tcDspNetClientHttp Class Reference

#include <net/clients/DspNetClientHttp.h>

List of all members.

Public Types
enum	teHttpReturn {   eeERRHOST = -1, eeERRSOCK = -2, eeERRCONN = -3, eeERRWRHD = -4,   eeERRWRDT = -5, eeERRRDHD = -6, eeERRPAHD = -7, eeERRNULL = -8,   eeERRNOLG = -9, eeERRMEM = -10, eeERRRDDT = -11, eeERRURLH = -12,   eeERRURLP = -13, eeERRTIME = -14, eeERRSSL = -15, eeINF100 = 100,   eeINF101 = 101, eeOK = 0, eeOK200 = 200, eeOK201 = 201,   eeOK206 = 206, eeERR400 = 400, eeERR401 = 401, eeERR403 = 403,   eeERR404 = 404, eeERR408 = 408, eeERR500 = 500, eeERR501 = 501,   eeERR503 = 503 }
Public Member Functions
	tcDspNetClientHttp (const char *apProxy=NULL, int anProxyPort=gnDefaultProxyPort)
	~tcDspNetClientHttp ()
void	ssl_helper (tcDspNetSslHelper *apHelper)
void	set_timeout (int anTimeoutSec)
teHttpReturn	put (const char *apURL, void *apData, int anLength, bool abOverwrite, const char *apMimeType)
teHttpReturn	get (const char *apURL, void *apData, int &arLength, char *apMimeType, int anOffset=0)
teHttpReturn	post (const char *apURL, void *apData, int anLength, void *apResponse=NULL, int *apRespLen=NULL, char *apMimeType=NULL, const char *apMoreHeader=NULL)
teHttpReturn	del (const char *apURL)
teHttpReturn	head (const char *apURL, int &arLength, char *apMimeType)
Static Public Attributes
static const int	gnDefaultProxyPort = 8080
static const int	gnDefaultHttpPort = 80
static const int	gnDefaultHttpsPort = 443
static const int	gnMimeLength = 64
static const int	gnDefaultHTTPReadTimeout = 2
Protected Member Functions
teHttpReturn	query (const char *apHost, int anPort, const char *apFile, const char *apRequest, int &anSocket, const bool abHttps, void *apSslContext, const void *apData=NULL, int anLength=0, const char *apMoreHeader=NULL)
teHttpReturn	parse_url (const char *apURL, char *apHost, int &arPort, char *apFile, bool &arHttps)
int	expand_filename (const char *apFile, char *apResult)
int	read_line (int anSocket, bool abHttps, void *apSslContext, char *apBuffer, int anMax, int anTimeout)
int	read_buffer (int anSocket, bool abHttps, void *apSslContext, char *apBuffer, int anLength, int anTimeout)
teHttpReturn	read_headers (int anSocket, bool abHttps, void *apSslContext, int &arLength, bool &arChunked, char *apMimeType)
teHttpReturn	read_attachment (int anSocket, bool abHttps, void *apSslContext, char *apData, int anMaxLen, int &arLength, bool abChunked)
Protected Attributes
SEM_Handle	mhMyMutex
	To serialize access.
char *	mpProxy
	Name of any proxy server.
int	mnProxyPort
	Proxy port to use.
tcDspNetSslHelper *	mpSslHelper
	SSL "helper" class.
int	mnHTTPReadTimeout
	Timeout for HTTP reads in seconds (default: 2).
Static Protected Attributes
static const int	gnMinHostLen = 16
static const int	gnMinFileLen = 256
static const int	gnMaxWrtPktSize = 4096
	max outbound chunk size (POST)

---

Detailed Description

Instances of this class provide a simple HTTP/1.1 client capability for use in the MityDSP with the LWIP stack.

See also:

tcDspNetClientHttp Page

---

Member Enumeration Documentation

enum MityDSP::tcDspNetClientHttp::teHttpReturn

The teHttpReturn enumeration defines the various status values that may be returned by the client methods.

Enumerator:

eeERRHOST	No such host.
eeERRSOCK	Can't create socket.
eeERRCONN	Can't connect to host.
eeERRWRHD	Write error on socket while writing header.
eeERRWRDT	Write error on socket while writing data.
eeERRRDHD	Read error on socket while reading result.
eeERRPAHD	Invalid answer from data server.
eeERRNULL	Null data pointer.
eeERRNOLG	No/Bad length in header.
eeERRMEM	Can't allocate memory.
eeERRRDDT	Read error while reading data.
eeERRURLH	Invalid url.
eeERRURLP	Invalid port in url.
eeERRTIME	Timeout on read or write.
eeERRSSL	SSL set-up error.
eeINF100	Continue.
eeINF101	Switch to new protocol.
eeOK	general success
eeOK200	Resource successfully read.
eeOK201	Resource successfully created.
eeOK206	Partial content.
eeERR400	Invalid query.
eeERR401	Unauthorized.
eeERR403	Forbidden.
eeERR404	Not Found.
eeERR408	Request timeout.
eeERR500	Server error.
eeERR501	Not implemented.
eeERR503	Service overloaded.

---

Constructor & Destructor Documentation

tcDspNetClientHttp::tcDspNetClientHttp	(	const char *	apProxy = NULL,
		int	anProxyPort = gnDefaultProxyPort
	)

This constructor is used to open an instance of the tcDspNetClientHttp class.

Parameters:

[in]	apProxy	- Name or IP address of Proxy Server (default: NULL)
[in]	anProxyPort	- Port to use on Proxy Server (default: 8080)

Returns:

None.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::~tcDspNetClientHttp

(

)

This destructor is used to close up and free the resources tied to the associated HTTP client.

Returns:

None.

See also:

DspNetClientHttp.h

---

Member Function Documentation

void tcDspNetClientHttp::ssl_helper

(

tcDspNetSslHelper *

apHelper

)

This routine is used to set a helper class for handling SSL connections. The class must be derived from the tcDspNetSslHelper pure virtual base class. If no helper is provided, HTTPS requests will fail.

Parameters:

[in]

apHelper

Pointer to an SSL helper class derived from tcDspNetSslHelper.

Returns:

None

See also:

DspNetClientHttp.h

DspNetSslHelper.h

void tcDspNetClientHttp::set_timeout

(

int

anTimeoutSec

)

This routine is used to tailor the HTTP read timeout value (in seconds), if necessary. In most cases the default value (gnDefaultHTTPReadTimeout or 2 seconds) should be sufficient.

Parameters:

[in]

anTimeoutSec

New timeout value (in seconds).

Returns:

None

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::put	(	const char *	apURL,
		void *	apData,
		int	anLength,
		bool	abOverwrite,
		const char *	apMimeType
	)

This routine is used to issue a PUT request to the server location specified by the provided URL. The data, length of data, and MIME type must be provided. A flag is also used to force an overwrite if the file already exists on the server.

Parameters:

[in]	apURL	The URL string specifying server, port, and resource.
[in]	apData	Pointer to the data to transfer.
[in]	anLength	Length of the data to transfer.
[in]	abOverwrite	True to request an overwrite of existing data.
[in]	apMimeType	Pointer to MIME type of data.

Returns:

eeOK201 if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::get	(	const char *	apURL,
		void *	apData,
		int &	arLength,
		char *	apMimeType,
		int	anOffset = 0
	)

This routine is used to issue a GET request for the provided URL. A buffer, and the maximum length must be provided. The actual length of the data, and its MIME type are returned.

Parameters:

[in]	apURL	The URL string specifying server, port, and resource.
[in]	apData	Pointer to a buffer for the requested data.
[in]	arLength	Maximum length of the data to transfer.
[out]	arLength	Actual length of the data transferred.
[out]	apMimeType	Pointer to MIME type of data received (must be at least gnMimeLength bytes).
[in]	anOffset	Byte offset into the file, default 0.

Returns:

eeOK200 if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::post	(	const char *	apURL,
		void *	apData,
		int	anLength,
		void *	apResponse = NULL,
		int *	apRespLen = NULL,
		char *	apMimeType = NULL,
		const char *	apMoreHeader = NULL
	)

This routine is used to issue a POST request to the server location specified by the provided URL. The data and length of data to post must be provided. Optionally, storage for a response to the POST may be provided.

Parameters:

[in]	apURL	The URL string specifying server, port, and resource.
[in]	apData	Pointer to the data to transfer.
[in]	anLength	Length of the data to transfer.
[in]	apResponse	Pointer to a buffer for the response.
[in]	apRespLen	Pointer to maximum length of the data to transfer (default: NULL).
[out]	apRespLen	Pointer to the actual length of the data transferred (default: NULL).
[out]	apMimeType	Pointer to MIME type of data received Default: NULL, if non-NULL must be at least gnMimeLength bytes).
[in]	apMoreHeader	Pointer to additional header information which is passed to the query function (default: NULL).

Returns:

eeOK201 if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::del

(

const char *

apURL

)

This routine is used to issue a DELETE request for the provided URL.

Parameters:

[in]

apURL

The URL string specifying server, port, and resource.

Returns:

eeOK201 if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::head	(	const char *	apURL,
		int &	arLength,
		char *	apMimeType
	)

This routine is used to issue a HEAD request for the provided URL. This command transfers no data, but returns the length and type of the data requested.

Parameters:

[in]	apURL	The URL string specifying server, port, and resource.
[out]	arLength	Actual length of the data transferred.
[out]	apMimeType	Pointer to MIME type of data received (must be at least gnMimeLength bytes).

Returns:

eeOK200 if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::query	(	const char *	apHost,
		int	anPort,
		const char *	apFile,
		const char *	apRequest,
		int &	anSocket,
		const bool	abHttps,
		void *	apSslContext,
		const void *	apData = NULL,
		int	anLength = 0,
		const char *	apMoreHeader = NULL
	)			[protected]

This is an internal routine to open a connection to the desired host (through a proxy, if so configured), and issue the specified request. If a non-negative return is given, the socket is left open for the caller, who is responsible for closing it.

Parameters:

[in]	apHost	Pointer to the host name or IP address.
[in]	anPort	Port number to use.
[in]	apFile	Pointer to resource being requested.
[in]	apRequest	Pointer to request string.
[out]	anSocket	Socket identifier.
[in]	abHttps	True if a secure socket connection.
[in]	apSslContext	Pointer to SSL context information.
[in]	apData	Pointer to additional data to send with request.
[in]	anLength	Length of additional data.
[in]	apMoreHeader	Pointer to additional header fields to send with request (must end with <CR><LF>).

Returns:

eeOK if successful communication, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::parse_url	(	const char *	apURL,
		char *	apHost,
		int &	arPort,
		char *	apFile,
		bool &	arHttps
	)			[protected]

This routine parses a provided URL into its host, port, and resource components.

Parameters:

[in]	apURL	The URL string specifying server, port, and resource.
[out]	apHost	Buffer for the host name.
[out]	arPort	Port number to use (default: 80).
[out]	apFile	Buffer for resource name.
[out]	arHttps	True if a secure socket is required, false otherwise.

Returns:

eeOK if successful, another error code if not.

See also:

DspNetClientHttp.h

int tcDspNetClientHttp::expand_filename	(	const char *	apFile,
		char *	apResult
	)			[protected]

This routine expands a provided resource by changing any spaces into "+" characters, and encoding any non-alphanumeric characters into a three character hex notation (xx).

Parameters:

[in]	apFile	Pointer to the resource to expand.
[out]	apResult	Buffer for the expanded result.

Returns:

Length of expanded result (0 if unsuccessful).

See also:

DspNetClientHttp.h

int tcDspNetClientHttp::read_line	(	int	anSocket,
		bool	abHttps,
		void *	apSslContext,
		char *	apBuffer,
		int	anMax,
		int	anTimeout
	)			[protected]

This routine reads a line from the given socket, and returns the number of bytes read (negative if a read error occured). Carriage returns <CR> are ignored.

Note:

: not efficient on long lines (multiple unbuffered 1 char reads)

Parameters:

[in]	anSocket	Socket identifier.
[in]	abHttps	True if a secure socket connection.
[in]	apSslContext	Pointer to SSL context information.
[in]	apBuffer	Pointer to storage for read data.
[in]	anMax	Maximum length of data.
[in]	anTimeout	Timeout (in seconds) before a timeout error is returned

Returns:

+ve bytes read if anMax read, -ve if an error before anMax

See also:

DspNetClientHttp.h

int tcDspNetClientHttp::read_buffer	(	int	anSocket,
		bool	abHttps,
		void *	apSslContext,
		char *	apBuffer,
		int	anLength,
		int	anTimeout
	)			[protected]

This routine reads a specified number of bytes from the given socket. It keeps retrying until the requested data has been read, an error occurs, or the call times out. It returns the number of bytes read (negative if a read error occured).

Parameters:

[in]	anSocket	Socket identifier.
[in]	abHttps	True if a secure socket connection.
[in]	apSslContext	Pointer to SSL context information.
[in]	apBuffer	Pointer to storage for read data.
[in]	anLength	Length of data requested.
[in]	anTimeout	Timeout in seconds for the receive call

Returns:

+ve bytes read if anLength read, -ve if an error before anLength

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::read_headers	(	int	anSocket,
		bool	abHttps,
		void *	apSslContext,
		int &	arLength,
		bool &	arChunked,
		char *	apMimeType
	)			[protected]

This routine reads headers from an HTTP response. It decodes the length of any attachments, their MIME type, and whether or not the response is "chunked".

Parameters:

[in]	anSocket	Socket identifier.
[in]	abHttps	True if a secure socket connection.
[in]	apSslContext	Pointer to SSL context information.
[out]	arLength	Length of attachment data.
[out]	arChunked	Boolean indicating whether attachment is chunked.
[out]	apMimeType	Pointer to MIME type of data received.

Returns:

eeOK if successful, another error code if not.

See also:

DspNetClientHttp.h

tcDspNetClientHttp::teHttpReturn tcDspNetClientHttp::read_attachment	(	int	anSocket,
		bool	abHttps,
		void *	apSslContext,
		char *	apData,
		int	anMaxLen,
		int &	arLength,
		bool	abChunked
	)			[protected]

This routine reads the message body from an HTTP server. It handles either "chunked" encoding, a length given in a "Content-length" header, or it reads until the buffer is full or the connection is closed by the server.

Parameters:

[in]	anSocket	Socket identifier.
[in]	abHttps	True if a secure socket connection.
[in]	apSslContext	Pointer to SSL context information.
[in]	apData	Pointer to a buffer for the requested data.
[in]	anMaxLen	Maximum length of the data to transfer.
[in]	arLength	Length of the data to transfer (0=unknown).
[out]	arLength	Actual length of the data transferred.
[out]	abChunked	Boolean indicating whether data is chunked.

Returns:

eeOK if successful, another error code if not.

See also:

DspNetClientHttp.h

---

Member Data Documentation

const int MityDSP::tcDspNetClientHttp::gnDefaultProxyPort = 8080 [static]

const int MityDSP::tcDspNetClientHttp::gnDefaultHttpPort = 80 [static]

const int MityDSP::tcDspNetClientHttp::gnDefaultHttpsPort = 443 [static]

const int MityDSP::tcDspNetClientHttp::gnMimeLength = 64 [static]

const int MityDSP::tcDspNetClientHttp::gnDefaultHTTPReadTimeout = 2 [static]

const int MityDSP::tcDspNetClientHttp::gnMinHostLen = 16 [static, protected]

const int MityDSP::tcDspNetClientHttp::gnMinFileLen = 256 [static, protected]

const int MityDSP::tcDspNetClientHttp::gnMaxWrtPktSize = 4096 [static, protected]

max outbound chunk size (POST)

SEM_Handle MityDSP::tcDspNetClientHttp::mhMyMutex [protected]

To serialize access.

char* MityDSP::tcDspNetClientHttp::mpProxy [protected]

Name of any proxy server.

int MityDSP::tcDspNetClientHttp::mnProxyPort [protected]

Proxy port to use.

tcDspNetSslHelper* MityDSP::tcDspNetClientHttp::mpSslHelper [protected]

SSL "helper" class.

int MityDSP::tcDspNetClientHttp::mnHTTPReadTimeout [protected]

Timeout for HTTP reads in seconds (default: 2).