RWHttpAgent Class Reference

Provides a high-level interface for issuing common HTTP requests. More...

#include <rw/http/RWHttpAgent.h>

Public Member Functions
	RWHttpAgent ()
	RWHttpAgent (RWHttpClientManager::PointerType clientManager)
void	addCustomHeader (const RWHttpHeaderBase &hdr)
RWTIOUResult< RWHttpReply >	executeDelete (const RWURL &url) const
RWTIOUResult< RWHttpReply >	executeGet (const RWURL &url) const
RWTIOUResult< RWHttpReply >	executeGetIfModifiedSince (const RWURL &url, const RWHttpDate &date) const
RWTIOUResult< RWHttpReply >	executeGetRange (const RWURL &url, const RWHttpRange &range) const
RWTIOUResult< RWHttpReply >	executeGetRange (const RWURL &url, const RWHttpRange &range, const RWHttpDate &date) const
RWTIOUResult< RWHttpReply >	executeGetRange (const RWURL &url, const RWHttpRange &range, const RWCString &etag) const
RWTIOUResult< RWHttpReply >	executeHead (const RWURL &url) const
RWTIOUResult< RWHttpReply >	executeOptions (const RWURL &url, const RWHttpRequestBody &body=RWHttpRequestStringBody()) const
RWTIOUResult< RWHttpReply >	executeOptions (const RWCString &server, int port=80, const RWHttpRequestBody &body=RWHttpRequestStringBody()) const
RWTIOUResult< RWHttpReply >	executePost (const RWURL &url, const RWHttpRequestBody &body) const
RWTIOUResult< RWHttpReply >	executePut (const RWURL &url, const RWHttpRequestBody &body) const
RWTIOUResult< RWHttpReply >	executeServerOptions (const RWURL &url, const RWHttpRequestBody &body=RWHttpRequestStringBody()) const
RWTIOUResult< RWHttpReply >	executeServerTrace (const RWURL &url) const
RWTIOUResult< RWHttpReply >	executeTrace (const RWURL &url) const
RWTIOUResult< RWHttpReply >	executeTrace (const RWCString &server, int port=80) const
RWHttpClientManager &	getClientManagerInstance () const
bool	getFollowRedirects () const
RWCString	getFrom () const
unsigned long	getNetworkMaxWait () const
bool	getSendDate () const
RWCString	getUserAgent () const
const RWHttpHeaderList &	headers () const
bool	removeCustomHeader (const RWHttpHeaderBase &hdr)
void	setFollowRedirects (bool b)
void	setFrom (const RWCString &from)
void	setNetworkMaxWait (unsigned long milliseconds)
void	setSendDate (bool b)
void	setUserAgent (const RWCString &agent)

Detailed Description

RWHttpAgent handles the details of the most common HTTP requests. It calls RWHttpClient to perform these requests. RWHttpAgent uses an RWHttpClientManager to cache connections to HTTP servers, which means that requests from multiple RWHttpAgent instances can use the same underlying network connection to make requests of an HTTP server.

The default constructor creates an RWHttpAgent that uses a default, global RWHttpClientManager. For greater control, you can first create an RWHttpClientManager and then create an RWHttpAgent that uses this manager. The constructor for the manager takes parameters for the number of threads and the number of connections the manager can create, and the resulting object has methods for querying and resetting these parameters. See the RWHttpClientManager description for details.

Constructor & Destructor Documentation

RWHttpAgent::RWHttpAgent

(

)

Constructs an RWHttpAgent that uses the default, global RWHttpClientManager instance.

RWHttpAgent::RWHttpAgent

(

RWHttpClientManager::PointerType

clientManager

)

Constructs an RWHttpAgent that uses a supplied RWHttpClientManager instance.

Member Function Documentation

void RWHttpAgent::addCustomHeader ( const RWHttpHeaderBase &  hdr )

inline

Adds a custom header to the internal header list of the agent. This header is sent with all outgoing requests from this agent.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeDelete

(

const RWURL &

url

)

const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the delete request and any information from the server concerning the delete request.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeGet

(

const RWURL &

url

)

const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeGetIfModifiedSince	(	const RWURL &	url,
		const RWHttpDate &	date
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the document associated with the URL, if it has been modified since date. Otherwise it returns a 304 (not modified) return code.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeGetRange	(	const RWURL &	url,
		const RWHttpRange &	range
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. Only the subrange specified by start and end will be returned.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeGetRange	(	const RWURL &	url,
		const RWHttpRange &	range,
		const RWHttpDate &	date
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. If the Last-Modified date for the requested URL is older than the date specified, then only the sub-range requested will be returned, otherwise the entire document associated with the URL will be returned.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeGetRange	(	const RWURL &	url,
		const RWHttpRange &	range,
		const RWCString &	etag
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. If the Etag for the document matches the etag parameter of the request, only the specified subrange will be returned, otherwise the entire document will be returned. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeHead

(

const RWURL &

url

)

const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the header information associated with the user-defined URL. The body of the document associated with the URL is not returned.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeOptions	(	const RWURL &	url,
		const RWHttpRequestBody &	body = RWHttpRequestStringBody()
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the options associated with the URL.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeOptions	(	const RWCString &	server,
		int	port = 80,
		const RWHttpRequestBody &	body = RWHttpRequestStringBody()
	)		const

Deprecated:

As of SourcePro 3, use executeServerOptions() instead.

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the options associated with the server. This is equivalent to executing an OPTIONS * HTTP/1.1 request to server:port.

RWTIOUResult<RWHttpReply> RWHttpAgent::executePost	(	const RWURL &	url,
		const RWHttpRequestBody &	body
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the POST request and the response from the server to the POST request. The body of the POST request is extracted from the body parameter.

RWTIOUResult<RWHttpReply> RWHttpAgent::executePut	(	const RWURL &	url,
		const RWHttpRequestBody &	body
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the PUT request and any information from the server concerning the PUT request. The body of the POST request is extracted from the body parameter.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeServerOptions	(	const RWURL &	url,
		const RWHttpRequestBody &	body = RWHttpRequestStringBody()
	)		const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply will contain information concerning the options associated with the server. This is equivalent to executing an OPTIONS * HTTP/1.1 request to the url's server:port. This version uses the scheme encoded in the URL to determine the type of connection to make to the server. The path portion of the specified URL is ignored.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeServerTrace

(

const RWURL &

url

)

const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply will contain information concerning the network path that the request followed to reach the destination server. This is equivalent to executing a TRACE * HTTP/1.1 request to url's server:port. This version uses the scheme encoded in the URL to determine the type of connection to make to the server. The path portion of the specified URL is ignored.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeTrace

(

const RWURL &

url

)

const

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the network path that the request followed to reach the destination URL.

RWTIOUResult<RWHttpReply> RWHttpAgent::executeTrace	(	const RWCString &	server,
		int	port = 80
	)		const

Deprecated:

As of SourcePro 3, use executeServerTrace() instead.

Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the network path that the request followed to reach the destination server. This is equivalent to executing a TRACE * HTTP/1.1 request to server:port.

RWHttpClientManager & RWHttpAgent::getClientManagerInstance ( ) const

inline

Returns a reference to the underlying RWHttpClientManager instance associated with this agent.

bool RWHttpAgent::getFollowRedirects ( ) const

inline

Returns true if redirects are automatically followed. Otherwise returns false.

RWCString RWHttpAgent::getFrom ( ) const

inline

Returns the value of the internal from value. The RWCString should contain 7-bit US-ASCII data.

unsigned long RWHttpAgent::getNetworkMaxWait ( ) const

inline

Returns the amount of time in milliseconds that a request blocks on a socket and waits for data before deciding that the socket is dead.

bool RWHttpAgent::getSendDate ( ) const

inline

Returns true if a Date header is appended to outgoing requests. Otherwise returns false.

RWCString RWHttpAgent::getUserAgent ( ) const

inline

Returns the value of the internal User-Agent value. The RWCString should contain 7-bit US-ASCII data.

const RWHttpHeaderList & RWHttpAgent::headers ( ) const

inline

Returns an RWHttpHeaderList containing all headers that are sent with requests from this RWHttpAgent.

bool RWHttpAgent::removeCustomHeader ( const RWHttpHeaderBase &  hdr )

inline

Removes a header from the internal header list of the agent. If the header was not present in the RWHttpHeaderList, this function returns false.

void RWHttpAgent::setFollowRedirects ( bool  b )

inline

Determines whether redirect replies (those with reply codes 3XX) are automatically followed. If it is set to true then redirects are followed automatically, and the resulting document is returned instead of the document requested. If redirects are not followed, the 3XX reply from the original request is returned, along with any associated message body. The default is to follow the redirects.

void RWHttpAgent::setFrom ( const RWCString &  from )

inline

Assigns the string from to the internal from value. If from is set to a non-empty string, an RWHttpFromHeader is attached to all requests issued from the RWHttpAgent object. The RWCString should contain 7-bit US-ASCII data.

void RWHttpAgent::setNetworkMaxWait ( unsigned long  milliseconds )

inline

Sets the maximum amount of time in milliseconds that the RWHttpAgent waits for data to become available from the server or for data to be sent to the server. If you set milliseconds to 0, the RWHttpAgent waits indefinitely.

If data for a request is not available within the user-defined time milliseconds, an RWNetOperationTimeoutError is thrown.

void RWHttpAgent::setSendDate ( bool  b )

inline

Determines whether a Date header is sent with a request. If b is true, all subsequent requests from this RWHttpAgent object attach an RWHttpDateHeader with the current date. If b is false, a date header is not appended. The default is false.

void RWHttpAgent::setUserAgent ( const RWCString &  agent )

inline

Assigns the string agent to the internal User-Agent value. If User-Agent is set to a non-empty string, an RWHttpUserAgentHeader is attached to all requests issued from the RWHttpAgent object. The RWCString should contain 7-bit US-ASCII data.