CascadeHTTPClient Class Reference

an API for using HTTP (up to v1.1) (RFC 2616) as a client of any HTTP server More...

#include <cascade/net/CascadeHTTPClient.h>

Inheritance diagram for CascadeHTTPClient:

List of all members.

Public Member Functions
	CascadeHTTPClient (const char *pURL)
	CascadeHTTPClient ()
virtual	~CascadeHTTPClient ()
virtual void	SetURL (const char *pURL)
virtual bool	GetURL (CascadeString &url) const
virtual void	SetHostname (const char *pHostname)
virtual bool	GetHostname (CascadeString &hostname) const
virtual void	SetPort (u16 nPort)
virtual u16	GetPort () const
virtual void	SetPath (const char *pPath)
virtual bool	GetPath (CascadeString &path) const
virtual bool	GetPathQuery (CascadeString &pathnquery) const
virtual void	SetFragment (const char *pFragment)
virtual bool	GetFragment (CascadeString &fragment) const
virtual void	SetQueryValue (const char *pQuery, const char *pQueryValue)
	specify or override any document request keyword
virtual bool	GetQueryValue (const char *pQuery, CascadeString &value) const
	discover current value of any document request keyword
virtual void	SetUsername (const char *pUsername)
virtual bool	GetUsername (CascadeString &username) const
virtual void	SetPassword (const char *pPassword)
virtual bool	GetPassword (CascadeString &password) const
virtual void	SetKeepAlive (bool bKeepAlive)
	default TRUE; FALSE to turn off keepalive
virtual bool	GetKeepAlive () const
	discover current keepalive setting
void	UserAgent (const char *user_agent)
	set or override user agent string; default "CascadeHTTPClient/1.0"
const char *	UserAgent () const
	discover current http version setting
virtual void	SetHTTPVersion (const char *pHTTPVersion)
	set or override http version; default "HTTP/1.1"
virtual bool	GetHTTPVersion (CascadeString &version) const
	discover current http version setting
virtual void	SetPeerHTTPVersion (const char *pPeerHTTPVersion)
	set or override required peer http version; default "HTTP/1.0"
virtual bool	GetPeerHTTPVersion (CascadeString &version) const
	discover current required peer http version
virtual void	SetMaxLineLength (u32 nMaxLineLength)
	set max_line_length; default 1024, 0 => no limit
virtual u32	GetMaxLineLength () const
	discover current max_line_length
virtual void	SetMaxHeaderLines (u32 nMaxHeaderLines)
	set max_header_lines; default 4096, 0 => no limit
virtual u32	GetMaxHeaderLines () const
	discover current max_header_lines
virtual void	SetRequestHeader (const char *pHeaderKey, const char *pHeaderValue)
	specify or override any HTTP header value
virtual bool	GetRequestHeader (const char *pHeaderKey, CascadeString &header) const
	discover current value of any request header
virtual void	SetByteRange (u64 nRangeStart, u64 nRangeStop)
virtual void	GetByteRange (u64 &nRangeStartToSet, u64 &nRangeStopToSet) const
u32	GET ()
	download a document
u32	GET (const char *path)
	download a document
u32	HEAD ()
	identical to GET() but without downloading entity content
u32	HEAD (const char *path)
	identical to GET(const char *path) but without downloading entity content
u32	POST (const char *buf, u32 len)
	post LEN chars of BUF to the current connection/path
u32	POST (const char *path, const char *buf, u32 len)
	post LEN chars of BUF to the relative path PATH
u32	PUT (const char *buf, u32 len)
	upload LEN chars of BUF to the current connection/path
u32	PUT (const char *path, const char *buf, u32 len)
	upload LEN chars of BUF to the relative path PATH
u32	DELETE ()
	delete the document at the current connection/path
u32	DELETE (const char *path)
	delete the document at a relative connection/path
u32	TRACE ()
	HTTP's version of "echo" service.
u32	TRACE (const char *path)
	HTTP's version of "echo" service.
virtual bool	GetResponseCode (CascadeString &code) const
	three-digit HTTP 1.1 response code (RFC 2616 Chapter 10)
virtual bool	GetResponseText (CascadeString &text) const
	RFC 2616 Chapter 10 translation of three-digit response code.
virtual u32	GetResponseCodeInt () const
	integerified three-digit HTTP 1.1 response code (RFC 2616 Chapter 10)
virtual bool	GetResponseHeader (CascadeString &header) const
	return content of entire response header
virtual bool	GetResponseHeaderAt (u32 nIndex, CascadeString &header) const
	return the text of the entire Ith respons header or empty string
virtual bool	GetResponseHeaderKey (u32 nIndex, CascadeString &key) const
	return the Ith response header name or empty string
virtual bool	GetResponseHeaderValue (const char *pResponseHeaderKey, CascadeString &value) const
	return the response header value associated with THIS_FIELD
virtual u32	ReadBytes (char *pBuff, u32 nBytes)
	read nBytes bytes into *pBuff
virtual bool	SetConnectTimeout (u32 nTimeoutMicroseconds)
	set the connect timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)
virtual bool	SetSendTimeout (u32 nTimeoutMicroseconds)
	set the send timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)
virtual bool	SetReceiveTimeout (u32 nTimeoutMicroseconds)
	set the receive timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)
virtual u32	GetConnectTimeout () const
	get the current connect timeout in microseconds
virtual u32	GetSendTimeout () const
	get the current send timeout in microseconds
virtual u32	GetReceiveTimeout () const
	get the current receive timeout in microseconds
virtual bool	SetAutoRedirectLimit (int this_many_times)
	set the number of times that CascadeHTTPClient will automatically fetch a redirect location
Static Public Member Functions
static void	URLEncodeString (const CascadeString input, CascadeString &output)
	encode the string in input, putting the result in output.
static bool	ErrorString (const u32 get_retval, CascadeString &error_string)
	return a string describing the error value returned by a call to GET()

---

Detailed Description

an API for using HTTP (up to v1.1) (RFC 2616) as a client of any HTTP server

Skip the description

Design Goals: Use this class to talk HTTP to any server on the routable network. Allow user to specify destinations and paths using string URLs (RFC 2396, URL subset), Allow user to send and receive messages to and from servers for those URLs. This is the ONLY class you will need to include in order to use all client features of the HTTP 1.1 protocol.

Examples: see test-htcli.cpp

---

class CascadeHTTPClient

---

Constructor & Destructor Documentation

CascadeHTTPClient::CascadeHTTPClient (  const char *  pURL  )

Become an HTTP client of the server at this URL Prerequisites: Parameters: url  is a URL as described by RFC2396 (not a URN). Returns: a CascadeHTTPClient object (not necessarily in a connected state)

CascadeHTTPClient::CascadeHTTPClient (   )

Become an HTTP client of a yet unspecified server Become an HTTP client. No server specified, so it must be specified later. Prerequisites: none Returns: a CascadeHTTPClient object (not in a connected state)

virtual CascadeHTTPClient::~CascadeHTTPClient (   )  [virtual]

destructor Prerequisites: this CascadeHTTPClient object can be in ANY state Postconditions: Guarantees any network connections opened by this CascadeHTTPClient object or its contained objects are closed. Guarantees any memory allocated by this this CascadeHTTPClient object or its contained objects is freed.

---

Member Function Documentation

u32 CascadeHTTPClient::DELETE (  const char *  path  )

delete the document at a relative connection/path

u32 CascadeHTTPClient::DELETE (   )

delete the document at the current connection/path

static bool CascadeHTTPClient::ErrorString (  const u32  get_retval, CascadeString &  error_string )  [static]

return a string describing the error value returned by a call to GET()

u32 CascadeHTTPClient::GET (  const char *  path  )

download a document

u32 CascadeHTTPClient::GET (   )

download a document

virtual void CascadeHTTPClient::GetByteRange (  u64 &  nRangeStartToSet, u64 &  nRangeStopToSet )  const [virtual]

virtual u32 CascadeHTTPClient::GetConnectTimeout (   )  const [virtual]

get the current connect timeout in microseconds

virtual bool CascadeHTTPClient::GetFragment (  CascadeString &  fragment  )  const [virtual]

discover current document path fragment Returns: a string which is the default fragment component of the RFC-2396 URL currently used by this CascadeHTTPClient object This fragment may have been set via the constructor, the url() method, or the fragment() method. Note: : the fragment specified by a GET() or other COMMAND method is not reflected in this fragment.

virtual bool CascadeHTTPClient::GetHostname (  CascadeString &  hostname  )  const [virtual]

discover current server hostname Returns: a string which is the hostname component of the RFC-2396 URL currently used by this CascadeHTTPClient object This hostname may have been set via the constructor, the url() method, or the hostname() method.

virtual bool CascadeHTTPClient::GetHTTPVersion (  CascadeString &  version  )  const [virtual]

discover current http version setting

virtual bool CascadeHTTPClient::GetKeepAlive (   )  const [virtual]

discover current keepalive setting

virtual u32 CascadeHTTPClient::GetMaxHeaderLines (   )  const [virtual]

discover current max_header_lines

virtual u32 CascadeHTTPClient::GetMaxLineLength (   )  const [virtual]

discover current max_line_length

virtual bool CascadeHTTPClient::GetPassword (  CascadeString &  password  )  const [virtual]

get password currently used for AUTH Returns: the UTF-8 password component of the URL currently used by this CascadeHTTPClient object

virtual bool CascadeHTTPClient::GetPath (  CascadeString &  path  )  const [virtual]

discover current document path Returns: a string which is the default path component of the RFC-2396 URL currently used by this CascadeHTTPClient object This path may have been set via the constructor, the url() method, or the path() method. Note: : the path specified by a GET() or other COMMAND method is not reflected in this path. : the path does NOT include the path fragment.

virtual bool CascadeHTTPClient::GetPathQuery (  CascadeString &  pathnquery  )  const [virtual]

discover current document path and complete query, quoted Returns: a string which is appropriate for use in DAAP checksumming Note: : the path specified by a GET() or other COMMAND method is not reflected in this path. : the path does NOT include the path fragment.

virtual bool CascadeHTTPClient::GetPeerHTTPVersion (  CascadeString &  version  )  const [virtual]

discover current required peer http version

virtual u16 CascadeHTTPClient::GetPort (   )  const [virtual]

discover current server port number Returns: an integer which is the port component of the RFC-2396 URL currently used by this CascadeHTTPClient object This port number may have been set via the constructor, the url() method, or the port() method.

virtual bool CascadeHTTPClient::GetQueryValue (  const char *  pQuery, CascadeString &  value )  const [virtual]

discover current value of any document request keyword

virtual u32 CascadeHTTPClient::GetReceiveTimeout (   )  const [virtual]

get the current receive timeout in microseconds

virtual bool CascadeHTTPClient::GetRequestHeader (  const char *  pHeaderKey, CascadeString &  header )  const [virtual]

discover current value of any request header

virtual bool CascadeHTTPClient::GetResponseCode (  CascadeString &  code  )  const [virtual]

three-digit HTTP 1.1 response code (RFC 2616 Chapter 10)

virtual u32 CascadeHTTPClient::GetResponseCodeInt (   )  const [virtual]

integerified three-digit HTTP 1.1 response code (RFC 2616 Chapter 10)

virtual bool CascadeHTTPClient::GetResponseHeader (  CascadeString &  header  )  const [virtual]

return content of entire response header

virtual bool CascadeHTTPClient::GetResponseHeaderAt (  u32  nIndex, CascadeString &  header )  const [virtual]

return the text of the entire Ith respons header or empty string

virtual bool CascadeHTTPClient::GetResponseHeaderKey (  u32  nIndex, CascadeString &  key )  const [virtual]

return the Ith response header name or empty string

virtual bool CascadeHTTPClient::GetResponseHeaderValue (  const char *  pResponseHeaderKey, CascadeString &  value )  const [virtual]

return the response header value associated with THIS_FIELD

virtual bool CascadeHTTPClient::GetResponseText (  CascadeString &  text  )  const [virtual]

RFC 2616 Chapter 10 translation of three-digit response code.

virtual u32 CascadeHTTPClient::GetSendTimeout (   )  const [virtual]

get the current send timeout in microseconds

virtual bool CascadeHTTPClient::GetURL (  CascadeString &  url  )  const [virtual]

discover the URL currently used by this HTTPClient. Returns: a string which is the same string set via the constructor or the url method.

virtual bool CascadeHTTPClient::GetUsername (  CascadeString &  username  )  const [virtual]

get username currently used by AUTH Returns: the UTF-8 username component of the URL currently used by this CascadeHTTPClient object

u32 CascadeHTTPClient::HEAD (  const char *  path  )

identical to GET(const char *path) but without downloading entity content

u32 CascadeHTTPClient::HEAD (   )

identical to GET() but without downloading entity content

u32 CascadeHTTPClient::POST (  const char *  path, const char *  buf, u32  len )

post LEN chars of BUF to the relative path PATH

u32 CascadeHTTPClient::POST (  const char *  buf, u32  len )

post LEN chars of BUF to the current connection/path

u32 CascadeHTTPClient::PUT (  const char *  path, const char *  buf, u32  len )

upload LEN chars of BUF to the relative path PATH

u32 CascadeHTTPClient::PUT (  const char *  buf, u32  len )

upload LEN chars of BUF to the current connection/path

virtual u32 CascadeHTTPClient::ReadBytes (  char *  pBuff, u32  nBytes )  [virtual]

read nBytes bytes into *pBuff

virtual bool CascadeHTTPClient::SetAutoRedirectLimit (  int  this_many_times  )  [virtual]

set the number of times that CascadeHTTPClient will automatically fetch a redirect location

virtual void CascadeHTTPClient::SetByteRange (  u64  nRangeStart, u64  nRangeStop )  [virtual]

virtual bool CascadeHTTPClient::SetConnectTimeout (  u32  nTimeoutMicroseconds  )  [virtual]

set the connect timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)

virtual void CascadeHTTPClient::SetFragment (  const char *  pFragment  )  [virtual]

specify or override document path fragment Parameters: fragment  may be any RFC-2396 URL fragment Postconditions: fragment( fragment);  strncmp (fragment(), fragment)  returns zero

virtual void CascadeHTTPClient::SetHostname (  const char *  pHostname  )  [virtual]

specify or override server hostname Parameters: hostname  may be either an IP address or a hostname Postconditions: hostname( hostname);  strncmp (hostname(), hostname)  returns zero

virtual void CascadeHTTPClient::SetHTTPVersion (  const char *  pHTTPVersion  )  [virtual]

set or override http version; default "HTTP/1.1"

virtual void CascadeHTTPClient::SetKeepAlive (  bool  bKeepAlive  )  [virtual]

default TRUE; FALSE to turn off keepalive

virtual void CascadeHTTPClient::SetMaxHeaderLines (  u32  nMaxHeaderLines  )  [virtual]

set max_header_lines; default 4096, 0 => no limit

virtual void CascadeHTTPClient::SetMaxLineLength (  u32  nMaxLineLength  )  [virtual]

set max_line_length; default 1024, 0 => no limit

virtual void CascadeHTTPClient::SetPassword (  const char *  pPassword  )  [virtual]

set (optionally pre-encrypted) password for AUTH Parameters: password  must be a UTF-8 string containing unreserved characters as defined by RFC-2396 Postconditions: password( password);  strncmp (password(), password)  returns zero

virtual void CascadeHTTPClient::SetPath (  const char *  pPath  )  [virtual]

specify or override document path Parameters: path  may be any RFC-2396 URL path Postconditions: path( path);  strncmp (path(), path)  returns zero

virtual void CascadeHTTPClient::SetPeerHTTPVersion (  const char *  pPeerHTTPVersion  )  [virtual]

set or override required peer http version; default "HTTP/1.0"

virtual void CascadeHTTPClient::SetPort (  u16  nPort  )  [virtual]

specify or override server port number Parameters: port  must be in the rage 1-32767 for the COMMAND methods to have a chance at success Postconditions: port( port);  (port() == port)  returns true

virtual void CascadeHTTPClient::SetQueryValue (  const char *  pQuery, const char *  pQueryValue )  [virtual]

specify or override any document request keyword

virtual bool CascadeHTTPClient::SetReceiveTimeout (  u32  nTimeoutMicroseconds  )  [virtual]

set the receive timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)

virtual void CascadeHTTPClient::SetRequestHeader (  const char *  pHeaderKey, const char *  pHeaderValue )  [virtual]

specify or override any HTTP header value

virtual bool CascadeHTTPClient::SetSendTimeout (  u32  nTimeoutMicroseconds  )  [virtual]

set the send timeout to this many microseconds (the default is 0 seconds, which means BLOCKING MODE)

virtual void CascadeHTTPClient::SetURL (  const char *  pURL  )  [virtual]

set or override the URL used by this HTTPClient. Parameters: url  must conform to RFC2396 and be a URL (not a URN). Prerequisites: this CascadeHTTPClient object may be in ANY state Postconditions: url( url);  strncmp (url(), url)  returns zero if this CascadeHTTPClient object was previously in a connected state, it might still be in a state connected to the previous URL. But that won't affect ANY of the other methods of this class --- they will all use the new URL.

virtual void CascadeHTTPClient::SetUsername (  const char *  pUsername  )  [virtual]

set username for AUTH Parameters: username  must be a UTF-8 string containing unreserved characters as defined by RFC-2396 Postconditions: username( username);  strncmp (username(), username)  returns zero

u32 CascadeHTTPClient::TRACE (  const char *  path  )

HTTP's version of "echo" service.

u32 CascadeHTTPClient::TRACE (   )

HTTP's version of "echo" service.

static void CascadeHTTPClient::URLEncodeString (  const CascadeString  input, CascadeString &  output )  [static]

encode the string in input, putting the result in output.

const char* CascadeHTTPClient::UserAgent (   )  const

discover current http version setting

void CascadeHTTPClient::UserAgent (  const char *  user_agent  )

set or override user agent string; default "CascadeHTTPClient/1.0"

---

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

• CascadeHTTPClient.h

---