OW32::CHTTP Class Reference

A simple HTTP request object. More...

#include <http.h>

Inheritance diagram for OW32::CHTTP:

List of all members.

Public Types
enum	HTTP_OPTIONS { OPT_FOLLOW_REDIRECT = 1, OPT_KEEP_ALIVE = 2 }
	Options that modify the requestor's behaviour. More...
Public Member Functions
void	Reset ()
	Return the object to the default state. This allows CHTTP objects to be pooled and reused.
void	setListener (CHTTPListener *listener)
	Set the event notification object (see #CHTTPListener).
CHTTPListener *	getListener ()
	Return a pointer to the current listener object.
void	close ()
	Close the current HTTP connection nicely.
void	abort ()
	Abort the current HTTP connection.
std::string	lastErrorMessage ()
	Return the last error, formatted up as a message.
int	lastError () const
	Return the last error code, from #HTTP_ERRORS.
DWORD	lastAPIError () const
	Return the last API error code.
bool	isOptionSet (int opt) const
	See if an option has set.
bool	getOption (int opt) const
	See if an option is set.
int	setOption (int opt)
	Set an option.
void	clearOption (int opt)
	Clear an option.
int	setOptions (int opt)
	Set all option flags to the given mask.
int	getOptions () const
	Return the options mask.
int	setMaximumResponseSize (int maxResponseSize)
	Set the maximum size of the result document.
int	getMaximumResponseSize () const
	Return the current maximum result size.
int	setTimeout (int timeout)
	Set the TCP timeouts for send() and recv().
int	getTimeout () const
	Return the current TCP timeout.
int	setMaximumRedirects (int maxRedirects)
	Set the maximum number of redirects to be followed.
int	getMaximumRedirects () const
	Get the maximum number of redirects to be followed.
CURIComponents &	getURI ()
	Get the current URI in component form.
void	setURI (const CURIComponents &URI)
	Set the current URI in component form.
void	setProxyServer (const char *proxyServer)
	Set the proxy server to the given DNS name.
const std::string &	getProxyServer () const
	Get the remote ProxyServer's name.
void	setProxyPort (int proxyPort)
	Set the proxy server's port.
int	getProxyPort () const
	Get the remote ProxyPort's name.
void	parseURI (const char *URIString, std::string::size_type URILength)
	Parse the given URI.
void	parseURI (const std::string &URIString)
	Parse the given URI.
std::string	getCanonicalURI () const
	Get the canonical URI for the current URI.
auto_byte_buf &	getRequest ()
	Return the request buffer. You can write into this directly for a custom HTTP request.
int	getStatusCode () const
	Return the last HTTP status code.
bool	isResponseValid () const
	See if there is a valid HTTP response stored by the object.
const unsigned char *	getResponse () const
	Return a pointer to the entire response. The response is as seen from the server, and therfore is NOT null terminated.
unsigned char *	detachResponse ()
	Detach the response buffer The caller owns this buffer and should call free() on it eventually.
size_t	getResponseLength () const
	Return the length of the response.
size_t	getHeaderLength () const
	Return the length of the headers.
const unsigned char *	getBody () const
	Return a pointer to the body portion of the response, or NULL if none.
size_t	getBodyOffset () const
	Return the offset of the body data within the response, or 0 if no content was received.
size_t	getBodyLength () const
	Return the length of the body data.
size_t	getTrailerOffset () const
	Return the offset of the trailer, or 0 if no trailer is present.
size_t	getTrailerLength () const
	Return the length of the trailer.
int	connect (AsyncIoType tAsyncIo, HANDLE hCompletionPort=NULL)
	Connect to the given server or proxy (oops, deleted proxy support - TODO: put it back in).
int	makeRequest (bool fInitial=true)
	Begin an asynchronous HTTP request. To get anything useful out of this you ought to have set a listener first.
void	addHeader (const char *header)
	Add a header (used in formatGETRequest).
int	formatGETRequest ()
	Format a simple get request into the request buffer.
bool	isConnected () const
	See if the object is connected.
unsigned char *	getHeader (const char *header)
	Search for a HTTP header in the response.
std::string	getHeaderValue (const char *header)
	Return a header value, or "" if the header is not found.
Static Public Member Functions
int	initialise ()
	Called to initialise the requestor library.
void	terminate ()
	Called to shutdown the requestor library.
CHTTP *	createObject ()
	Create a CHTTP object.
void	urlEncode (auto_byte_buf &out, const unsigned char *data, int len)
	urlEncode a given byte string
unsigned char *	findLineEnd (const unsigned char *start, const unsigned char *end)
	Utility function to find the end of a line in HTTP headers.
Friends
class	CConnectionThread
	For asynchronous connection notification.

---

Detailed Description

A simple HTTP request object.

---

Member Enumeration Documentation

enum OW32::CHTTP::HTTP_OPTIONS

Options that modify the requestor's behaviour. Enumeration values: OPT_FOLLOW_REDIRECT  Follow HTTP redirects. OPT_KEEP_ALIVE  Keep the connection alive if possible (can override with headers).

---

Member Function Documentation

void OW32::CHTTP::addHeader (  const char *  header  )

Add a header (used in formatGETRequest). Parameters: header  The header to add

void OW32::CHTTP::clearOption (  int  opt  )  [inline]

Clear an option. Parameters: opt  The option to clear, from HTTP_OPTIONS.

CHTTP* OW32::CHTTP::createObject (   )  [inline, static]

Create a CHTTP object. Returns: The newly created object, with a reference count of 1.

unsigned char* OW32::CHTTP::findLineEnd (  const unsigned char *  start, const unsigned char *  end )  [static]

Utility function to find the end of a line in HTTP headers. Parameters: start  Pointer to the start of the buffer to search for the line end in end  Pointer to the end of the buffer Conforms to the HTTP/1.1 protocol specification in that it allows white space as a continuation in header lines.

int OW32::CHTTP::formatGETRequest (   )

Format a simple get request into the request buffer. Returns: An error code from #HTTP_ERRORS. To set the address, use #parseAddress or #setServer and #setObject. Note that this clears any existing request.

std::string OW32::CHTTP::getCanonicalURI (   )  const [inline]

Get the canonical URI for the current URI. Returns: The canonical URI

unsigned char* OW32::CHTTP::getHeader (  const char *  header  )

Search for a HTTP header in the response. Parameters: header  The header to search for Returns: Pointer to the start of the header line You must have a response before you call this.

std::string OW32::CHTTP::getHeaderValue (  const char *  header  )

Return a header value, or "" if the header is not found. Parameters: header  The header to search for Returns: The header value You must have a response before you call this.

CHTTPListener* OW32::CHTTP::getListener (   )  [inline]

Return a pointer to the current listener object. Returns: The current listener. If no listener object has been set, the return value will be NULL.

int OW32::CHTTP::getMaximumRedirects (   )  const [inline]

Get the maximum number of redirects to be followed. Returns: The current number of redirects The default number is 15.

int OW32::CHTTP::getMaximumResponseSize (   )  const [inline]

Return the current maximum result size. Returns: The current maximum response size. The default size is unlimited, indicated by zero. The response size does not include the headers.

bool OW32::CHTTP::getOption (  int  opt  )  const [inline]

See if an option is set. Parameters: opt  The option to check, from HTTP_OPTIONS.

int OW32::CHTTP::getOptions (   )  const [inline]

Return the options mask. Returns: The options mask.

int OW32::CHTTP::getProxyPort (   )  const [inline]

Get the remote ProxyPort's name. Returns: The remote ProxyPort's name

const std::string& OW32::CHTTP::getProxyServer (   )  const [inline]

Get the remote ProxyServer's name. Returns: The remote ProxyServer's name

int OW32::CHTTP::getStatusCode (   )  const [inline]

Return the last HTTP status code. Returns: Standard HTTP status code, or -1 if no code.

int OW32::CHTTP::getTimeout (   )  const [inline]

Return the current TCP timeout. Returns: The current timeout

int OW32::CHTTP::initialise (   )  [static]

Called to initialise the requestor library. Returns: Error code from #HTTP_ERRORS.

bool OW32::CHTTP::isConnected (   )  const [inline]

See if the object is connected. Returns: True if so, false if not.

bool OW32::CHTTP::isOptionSet (  int  opt  )  const [inline]

See if an option has set. Returns: true if the option is set, false if not. Parameters: opt  The option to check, from HTTP_OPTIONS.

bool OW32::CHTTP::isResponseValid (   )  const [inline]

See if there is a valid HTTP response stored by the object. This is the case if: a) We have a complete set of headers b) There was no I/O error Should only be called after the object is quiesced.

std::string OW32::CHTTP::lastErrorMessage (   )

Return the last error, formatted up as a message. Returns: The last error message

int OW32::CHTTP::makeRequest (  bool  fInitial = true  )

Begin an asynchronous HTTP request. To get anything useful out of this you ought to have set a listener first. Parameters: fInitial  Set if this is the initial request in a redirect chain (resets the count of redirects encountered so far). Returns: An error code from #HTTP_ERRORS. Typically returns HTTP_IO_PENDING on success, at which point you must wait for notifications on the listener object.

void OW32::CHTTP::parseURI (  const std::string &  URIString  )  [inline]

Parse the given URI. Parameters: URIString  The uri string to parse

void OW32::CHTTP::parseURI (  const char *  URIString, std::string::size_type  URILength )  [inline]

Parse the given URI. Parameters: URIString  The uri string to parse URILength  The length of the uri string

void OW32::CHTTP::setListener (  CHTTPListener *  listener  )  [inline]

Set the event notification object (see #CHTTPListener). Parameters: listener  The listener object. The listener object should only be set when the object is quiescent: that is, either it has just been created, or OnRequestCompleted has been called. The lifetime of the listener follows the same rules.

int OW32::CHTTP::setMaximumRedirects (  int  maxRedirects  )  [inline]

Set the maximum number of redirects to be followed. Returns: The old number of redirects Parameters: maxRedirects  The number of redirects to allow. The default number is 15.

int OW32::CHTTP::setMaximumResponseSize (  int  maxResponseSize  )  [inline]

Set the maximum size of the result document. Parameters: maxResponseSize  The new maximum result size Returns: The old maximum result size Works by: 1) Where possible, checking the content length, and aborting immediately 2) Otherwise, stops the request part way through. If maxResponseSize is zero, then no limit is set. The response size does not include the headers. The response size is also approximate -- the intention is to prevent fetches of _enormous_ documents (the tolerance will be within the chunk size, defaulting to 4K).

int OW32::CHTTP::setOption (  int  opt  )  [inline]

Set an option. Returns: The old value of the option. Parameters: opt  The option to check, from HTTP_OPTIONS.

int OW32::CHTTP::setOptions (  int  opt  )  [inline]

Set all option flags to the given mask. Parameters: opt  The options to set, or'd together. Returns: The value of the old option set.

void OW32::CHTTP::setProxyPort (  int  proxyPort  )  [inline]

Set the proxy server's port. Parameters: proxyPort  The DNS name of the remote ProxyPort.

void OW32::CHTTP::setProxyServer (  const char *  proxyServer  )  [inline]

Set the proxy server to the given DNS name. Parameters: proxyServer  The DNS name of the remote ProxyServer.

int OW32::CHTTP::setTimeout (  int  timeout  )  [inline]

Set the TCP timeouts for send() and recv(). Parameters: timeout  Timeout in seconds. 0 indicates no timeout (the default). Returns: The old timeout value This does not take effect until the next connect() call.

void OW32::CHTTP::urlEncode (  auto_byte_buf &  out, const unsigned char *  data, int  len )  [static]

urlEncode a given byte string Parameters: out  The output buffer data  The data to encode len  The length of the data

---

The documentation for this class was generated from the following file:

• http.h

---