HTTPCLIENT Class Reference

Base-class for user-defined instance data for a client. More...

#include <mi32/httpclient.h>

Public Types
enum	CACHEMODE { CACHEMODE_NoCache = 0, CACHEMODE_IgnoreCache = 1, CACHEMODE_UseCacheIfCurrent = 2, CACHEMODE_UseCacheIfExists = 3 }
typedef fastdelegate::FastDelegate < ERRVALUE(const MISTRING &host, const MISTRING &realm)>	DELEGATE_ONAUTHREQUEST
typedef fastdelegate::FastDelegate < bool(double)>	DELEGATE_ONSTATUS
enum	STATE { STATE_Idle, STATE_WaitingForFirstLine, STATE_ReadingHeader, STATE_ReadingMessage }
Public Member Functions
	HTTPCLIENT (MISOCKET *socket, bool bTakeOwnership)
	HTTPCLIENT ()
virtual	~HTTPCLIENT ()
virtual	~INSTANCEDATA ()
ERRVALUE	ConnectToHost (const char *hostname, int port=80)
ERRVALUE	Download (const HTTPMESSAGE &request, HTTPMESSAGE &reply)
ERRVALUE	Download (const char *path, bool bIsEscaped, HTTPMESSAGE &reply)
ERRVALUE	Download (const char *path, HTTPMESSAGE &reply)
ERRVALUE	DownloadFile (const char *path, FILEPATH &filepath, const MILIST< STRUTF8 > &Headers, HTTPMESSAGE &Reply, bool bIgnoreCache=false)
ERRVALUE	DownloadFile (const char *path, FILEPATH &filepath, const MILIST< STRUTF8 > &Headers, bool bIgnoreCache=false)
ERRVALUE	GetAuthentication (const MISTRING &host, const MISTRING &realm, MISTRING &username, MISTRING &password)
ERRVALUE	GetAuthHeader (const HTTPMESSAGE &req, const HTTPMESSAGE &rep, MISTRING &header)
CACHEMODE	GetCacheMode () const
HTTPCLIENT *	GetClient () const
const MISTRING &	GetHostName () const
const STRUTF8 &	GetID () const
INSTANCEDATA *	GetInstanceData (const char *id) const
ERRVALUE	GetMsg (HTTPMESSAGE &obj)
	INSTANCEDATA (HTTPCLIENT *client)
ERRVALUE	PostFile (const char *path, FILEPATH &responsefile, GENERICRW &body, const MILIST< STRUTF8 > &headers, HTTPMESSAGE &Reply, bool bIgnoreCache=false)
ERRVALUE	RemoveAuthentication (const MISTRING &host, const MISTRING &realm)
ERRVALUE	Send (const HTTPMESSAGE &Request, HTTPMESSAGE &Reply)
ERRVALUE	SendMsg (const HTTPMESSAGE &headers, GENERICRW &body, bool bHeaderOnly=false)
ERRVALUE	SendMsg (const HTTPMESSAGE &headers, const XMLDOC &body, bool bHeaderOnly=false)
ERRVALUE	SendMsg (const HTTPMESSAGE &headers, const STRUTF8 &body, bool bHeaderOnly=false)
ERRVALUE	SendMsg (const HTTPMESSAGE &headers, const MISTRING &body, bool bHeaderOnly=false)
ERRVALUE	SendMsg (const HTTPMESSAGE &msg, bool bHeaderOnly=false)
ERRVALUE	SetAuthentication (const MISTRING &host, const MISTRING &realm, const MISTRING &username, const MISTRING &password)
void	SetCacheMode (CACHEMODE mode)
void	SetDelegateOnStatus (DELEGATE_ONSTATUS delegate)
void	SetDelegateOnStatusBegin (DELEGATE_VOID_NOPARMS delegate)
void	SetDelegateOnStatusEnd (DELEGATE_VOID_NOPARMS delegate)
void	SetHostName (const char *name)
void	SetTimeOut (int seconds)
void	SetUseProxy (bool UseProxy, const char *ProxyHost=0, int ProxyPort=0)
Static Public Member Functions
static void	CacheClear ()
static bool	CacheIsDisabled ()
static void	CacheSetDisabled (bool disable)
static INT32	GetCacheMaxSize ()
static const char *	GetDefaultStatusMessage (int code)
static void	RegisterDelegateOnAuthRequest (DELEGATE_ONAUTHREQUEST delegate)
static void	SetCacheMaxSize (INT32 Size)
Private Member Functions
virtual ERRVALUE	v_OnAuthRequest (const MISTRING &host, const MISTRING &realm)
Private Attributes
HTTPCLIENT *	m_client
STRUTF8	m_id

Detailed Description

Base-class for user-defined instance data for a client.

This class allows you to hang your own data off of an HTTPCLIENT. This data will automatically get deleted when the client is deleted, although you can delete it yourself before the client.

Member Typedef Documentation

typedef fastdelegate::FastDelegate<ERRVALUE (const MISTRING& host, const MISTRING& realm)> HTTPCLIENT::DELEGATE_ONAUTHREQUEST

typedef fastdelegate::FastDelegate<bool(double)> HTTPCLIENT::DELEGATE_ONSTATUS

Member Enumeration Documentation

enum HTTPCLIENT::CACHEMODE

Enumerator:

CACHEMODE_NoCache	Ignore the cache completely, don't cache result.
CACHEMODE_IgnoreCache	Ignore the copy in the cache (if any), but add the result to the cache for later.
CACHEMODE_UseCacheIfCurrent	If we have a copy in the cache, ask the server if it's "current" and retrieve new copy if server has a new copy.
CACHEMODE_UseCacheIfExists	If there's a copy in the cache, just use it (not recommended).

enum HTTPCLIENT::STATE

Enumerator:

STATE_Idle
STATE_WaitingForFirstLine
STATE_ReadingHeader
STATE_ReadingMessage

Constructor & Destructor Documentation

HTTPCLIENT::HTTPCLIENT ( )

Default constructor.

HTTPCLIENT::HTTPCLIENT	(	MISOCKET *	socket,
		bool	bTakeOwnership
	)

Create given an existing socket.

If bTakeOwnership is true, then this client will "own" the socket and delete it when it's done with it.

virtual HTTPCLIENT::~HTTPCLIENT ( ) [virtual]

Destructor.

virtual HTTPCLIENT::~INSTANCEDATA ( ) [virtual]

Member Function Documentation

static void HTTPCLIENT::CacheClear ( ) [static]

Clear cache contents.

static bool HTTPCLIENT::CacheIsDisabled ( ) [static]

Determine if all caching is disabled.

static void HTTPCLIENT::CacheSetDisabled ( bool disable ) [static]

Set whether cache is disabled.

Parameters:

disable

Whether to disable or not

ERRVALUE HTTPCLIENT::ConnectToHost	(	const char *	hostname,
		int	port = `80`
	)

Connect to a remote host by hostname.

If given a full URL, it will extract the hostname for you. It will also parse the port number if specified as hostname:portnum

ERRVALUE HTTPCLIENT::Download	(	const HTTPMESSAGE &	request,
		HTTPMESSAGE &	reply
	)

Send a request to the server and wait for the reply.

If authentication is needed, it will call v_OnAuthRequest() to get the username and password. If it gets an HTTP redirect, it will try again at the new address.

See the warnings about how the cache can affect the reply in the documentation for the other Download method.

Parameters:

	request	Request message
	reply	message to receive the reply

ERRVALUE HTTPCLIENT::Download	(	const char *	path,
		bool	bIsEscaped,
		HTTPMESSAGE &	reply
	)

Send a GET request to the server and wait for the reply.

If authentication is needed, it will call v_OnAuthRequest() to get the username and password. If it gets an HTTP redirect, it will try again at the new address. This method assumes you're allready connected to the host. According to the HTTP 1.1 protocol, the path can be either a full URI (http://hostname/abs_path) or just the "/abs_path" part.

Note: if SetCacheMode() has been called to enable the cache, you will need to check if the reply message IsDirectToFile(). If so, the result is in reply.GetDestFile(), which may be a cached file. If IsDirectToFile() returns false, the result is in the message itself and can be retrieved by calling reply.GetData(). You should code for either possibility even if you think it will always come out one way or the other. If the server says something should not be cached, it won't be.

Parameters:

	path	Path relative to the host (i.e., without the http://hostname part)
	bIsEscaped	Pass true if uri is escaped as per RFC1738
	reply	message to receive the reply

ERRVALUE HTTPCLIENT::Download	(	const char *	path,
		HTTPMESSAGE &	reply
	)

Send a GET request to the server and wait for the reply.

If authentication is needed, it will call v_OnAuthRequest() to get the username and password. If it gets an HTTP redirect, it will try again at the new address. This method assumes you're allready connected to the host. According to the HTTP 1.1 protocol, the path can be either a full URI (http://hostname/abs_path) or just the "/abs_path" part.

Note: if SetCacheMode() has been called to enable the cache, you will need to check if the reply message IsDirectToFile(). If so, the result is in reply.GetDestFile(), which may be a cached file. If IsDirectToFile() returns false, the result is in the message itself and can be retrieved by calling reply.GetData(). You should code for either possibility even if you think it will always come out one way or the other. If the server says something should not be cached, it won't be.

Parameters:

	path	Path relative to the host (i.e., without the http://hostname part)
	reply	message to receive the reply

ERRVALUE HTTPCLIENT::DownloadFile	(	const char *	path,
		FILEPATH &	filepath,
		const MILIST< STRUTF8 > &	Headers,
		HTTPMESSAGE &	Reply,
		bool	bIgnoreCache = `false`
	)

ERRVALUE HTTPCLIENT::DownloadFile	(	const char *	path,
		FILEPATH &	filepath,
		const MILIST< STRUTF8 > &	Headers,
		bool	bIgnoreCache = `false`
	)

Download a file from a server to a specified location.

If filepath points to an existing file and the one on the server is not newer than the existing copy, nothing will be downloaded unless bIgnoreCache is true. If authentication is needed, it will call v_OnAuthRequest() to get the username and password. If it gets an HTTP redirect, it will try again at the new address.

ERRVALUE HTTPCLIENT::GetAuthentication	(	const MISTRING &	host,
		const MISTRING &	realm,
		MISTRING &	username,
		MISTRING &	password
	)

ERRVALUE HTTPCLIENT::GetAuthHeader	(	const HTTPMESSAGE &	req,
		const HTTPMESSAGE &	rep,
		MISTRING &	header
	)

static INT32 HTTPCLIENT::GetCacheMaxSize ( ) [static]

Get the maximum cache size in Megabytes.

The cache directory is shared by all clients and is persistant.

CACHEMODE HTTPCLIENT::GetCacheMode ( ) const

Get the current CACHEMODE.

HTTPCLIENT* HTTPCLIENT::GetClient ( ) const

Get the client that this data is attached to.

static const char* HTTPCLIENT::GetDefaultStatusMessage ( int code ) [static]

Returns the status message for a given status code.

These are defined by RFC-2616. According to the standard, they MAY be localized without affecting the protocol, but they're not typically seen by the user.

Parameters:

code

The status code to get the message for.

const MISTRING& HTTPCLIENT::GetHostName ( ) const

const STRUTF8& HTTPCLIENT::GetID ( ) const

Get a unique identifier string that can be used to retrieve the data from the client.

INSTANCEDATA* HTTPCLIENT::GetInstanceData ( const char * id ) const

Looks up and returns an INSTANCEDATA with the given ID.

HTTPCLIENT::INSTANCEDATA is automatically attached to its client by its constructor and detached by its destructor.

Parameters:

id

The INSTANCEDATA's id as returned by GetID()

Returns:: A pointer to the instance data or NULL if no data with with the given id could be found.

ERRVALUE HTTPCLIENT::GetMsg ( HTTPMESSAGE & obj )

Get something from the server Mainly used after a call to SendMsg() to get the reply from the HTTP server.

HTTPCLIENT::INSTANCEDATA ( HTTPCLIENT * client )

ERRVALUE HTTPCLIENT::PostFile	(	const char *	path,
		FILEPATH &	responsefile,
		GENERICRW &	body,
		const MILIST< STRUTF8 > &	headers,
		HTTPMESSAGE &	Reply,
		bool	bIgnoreCache = `false`
	)

static void HTTPCLIENT::RegisterDelegateOnAuthRequest ( DELEGATE_ONAUTHREQUEST delegate ) [static]

Register common delegate to call when authorization for remote server is requested.

ERRVALUE HTTPCLIENT::RemoveAuthentication	(	const MISTRING &	host,
		const MISTRING &	realm
	)

ERRVALUE HTTPCLIENT::Send	(	const HTTPMESSAGE &	Request,
		HTTPMESSAGE &	Reply
	)

Send request and receive reply.

ERRVALUE HTTPCLIENT::SendMsg	(	const HTTPMESSAGE &	headers,
		GENERICRW &	body,
		bool	bHeaderOnly = `false`
	)

Send a message with body from GENERICRW.

The body of the message is read from the GENERICRW-derived class.

Parameters:

body

Reader for message body

ERRVALUE HTTPCLIENT::SendMsg	(	const HTTPMESSAGE &	headers,
		const XMLDOC &	body,
		bool	bHeaderOnly = `false`
	)

Send a message with XMLDOC body.

Parameters:

body

Message body

ERRVALUE HTTPCLIENT::SendMsg	(	const HTTPMESSAGE &	headers,
		const STRUTF8 &	body,
		bool	bHeaderOnly = `false`
	)

Send a message with STRUTF8 body.

Parameters:

body

Message body.

ERRVALUE HTTPCLIENT::SendMsg	(	const HTTPMESSAGE &	headers,
		const MISTRING &	body,
		bool	bHeaderOnly = `false`
	)

Send a message with MISTRING body.

Parameters:

body

Message body

ERRVALUE HTTPCLIENT::SendMsg	(	const HTTPMESSAGE &	msg,
		bool	bHeaderOnly = `false`
	)

Send a message.

Parameters:

msg

The headers and body of the message

ERRVALUE HTTPCLIENT::SetAuthentication	(	const MISTRING &	host,
		const MISTRING &	realm,
		const MISTRING &	username,
		const MISTRING &	password
	)

Set authentication.

static void HTTPCLIENT::SetCacheMaxSize ( INT32 Size ) [static]

Set the maximum cache size in Megabytes.

The cache directory is shared by all clients and is persistant. Setting the max cache size below the current size will just flush the cache.

Parameters:

Size

Max cache size in Megabytes

void HTTPCLIENT::SetCacheMode ( CACHEMODE mode )

Set the CACHEMODE.

The default cache mode is CACHEMODE_NoCache

void HTTPCLIENT::SetDelegateOnStatus ( DELEGATE_ONSTATUS delegate )

Set delegate to call while receiving data.

Delegate should return true to continue, false to cancel. Will be called several times with a value of 0.0 while reading the header. If the message is sent "chunked" the total size isn't known until it's all read, so in that case OnStatus is called once for each chunk with a value of -1. This allows for a status bar to at least do something and check cancel.

void HTTPCLIENT::SetDelegateOnStatusBegin ( DELEGATE_VOID_NOPARMS delegate )

Set delegate to be called before starting a message download.

void HTTPCLIENT::SetDelegateOnStatusEnd ( DELEGATE_VOID_NOPARMS delegate )

Set delegate to be called when a message download is done.

void HTTPCLIENT::SetHostName ( const char * name )

Set the host name of the remote server.

This is needed for the GET header when requesting data. We should be able to get this from the socket, but one server could serve multiple virtual hosts, so this lets you specify which one. Note, ConnectToHost() sets this for you.

void HTTPCLIENT::SetTimeOut ( int seconds )

Set the timeout interval in seconds.

If not set, the default is to wait indefinately.