LLURLRequest Class Reference

Class to handle url based requests. More...

#include <llurlrequest.h>

Inheritance diagram for LLURLRequest:

[legend]Collaboration diagram for LLURLRequest:


Public Types
	INVALID
	HTTP_GET
	HTTP_PUT
	HTTP_POST
	HTTP_DELETE
	REQUEST_ACTION_COUNT
enum	ERequestAction { INVALID, HTTP_GET, HTTP_PUT, HTTP_POST, HTTP_DELETE, REQUEST_ACTION_COUNT }
	This enumeration is for specifying the type of request. More...
Public Member Functions
	LLURLRequest (ERequestAction action)
	Constructor.
	LLURLRequest (ERequestAction action, const std::string &url)
	Constructor.
virtual	~LLURLRequest ()
	Destructor.
void	useProxy (bool use_proxy)
virtual EStatus	handleError (EStatus status, LLPumpIO *pump)
	Give this pipe a chance to handle a generated error.

void	setURL (const std::string &url)
	Set the url for the request.
void	addHeader (const char *header)
	Add a header to the http post.
void	checkRootCertificate (bool check, const char *caBundle=NULL)
	Check remote server certificate signed by a known root CA.
void	requestEncoding (const char *encoding)
	Request a particular response encoding if available.
void	setBodyLimit (U32 size)
	Return at most size bytes of body.
void	setCallback (LLURLRequestComplete *callback)
	Set a completion callback for this URLRequest.
Static Public Member Functions
static void	setCertificateAuthorityFile (const std::string &file_name)
static void	setCertificateAuthorityPath (const std::string &path)
Protected Types
	STATE_INITIALIZED
	STATE_WAITING_FOR_RESPONSE
	STATE_PROCESSING_RESPONSE
	STATE_HAVE_RESPONSE
enum	EState { STATE_INITIALIZED, STATE_WAITING_FOR_RESPONSE, STATE_PROCESSING_RESPONSE, STATE_HAVE_RESPONSE }
Protected Member Functions
virtual EStatus	process_impl (const LLChannelDescriptors &channels, buffer_ptr_t &buffer, bool &eos, LLSD &context, LLPumpIO *pump)
	Process the data in buffer.
Protected Attributes
EState	mState
ERequestAction	mAction
LLURLRequestDetail *	mDetail
LLIOPipe::ptr_t	mCompletionCallback
Private Member Functions
void	initialize ()
	Initialize the object. Called during construction.
bool	configure ()
	Handle action specific url request configuration.
	LLURLRequest (const LLURLRequest &)
	Declaration of unimplemented method to prevent copy construction.
Static Private Member Functions
static size_t	downCallback (void data, size_t size, size_t nmemb, void user)
	Download callback method.
static size_t	upCallback (void data, size_t size, size_t nmemb, void user)
	Upload callback method.

Detailed Description

Class to handle url based requests.

See also:: LLIOPipe

Currently, this class is implemented on top of curl. From the vantage of a programmer using this class, you do not care so much, but it's useful to know since in order to accomplish 'non-blocking' behavior, we have to use a more expensive curl interface which can still block if the server enters a half-accepted state. It would be worth the time and effort to eventually port this to a raw client socket.

Definition at line 63 of file llurlrequest.h.

Member Enumeration Documentation

enum LLURLRequest::ERequestAction

This enumeration is for specifying the type of request.

Enumerator:

INVALID
HTTP_GET
HTTP_PUT
HTTP_POST
HTTP_DELETE
REQUEST_ACTION_COUNT

Definition at line 69 of file llurlrequest.h.

enum LLURLRequest::EState [protected]

Enumerator:

STATE_INITIALIZED
STATE_WAITING_FOR_RESPONSE
STATE_PROCESSING_RESPONSE
STATE_HAVE_RESPONSE

Definition at line 205 of file llurlrequest.h.

Constructor & Destructor Documentation

LLURLRequest::LLURLRequest ( ERequestAction action )

Constructor.

Parameters:

action

One of the ERequestAction enumerations.

Definition at line 132 of file llurlrequest.cpp.

References initialize(), and LLMemType::MTYPE_IO_URL_REQUEST.

LLURLRequest::LLURLRequest	(	ERequestAction	action,
		const std::string &	url
	)

Constructor.

Parameters:

	action	One of the ERequestAction enumerations.
	url	The url of the request. It should already be encoded.

Definition at line 139 of file llurlrequest.cpp.

References initialize(), LLMemType::MTYPE_IO_URL_REQUEST, and setURL().

LLURLRequest::~LLURLRequest ( ) [virtual]

Destructor.

Definition at line 149 of file llurlrequest.cpp.

References mDetail, and LLMemType::MTYPE_IO_URL_REQUEST.

LLURLRequest::LLURLRequest ( const LLURLRequest & ) [private]

Declaration of unimplemented method to prevent copy construction.

Member Function Documentation

void LLURLRequest::addHeader ( const char * header )

Add a header to the http post.

The header must be correctly formatted for HTTP requests. This provides a raw interface if you know what kind of request you will be making during construction of this instance. All required headers will be automatically constructed, so this is usually useful for encoding parameters.

Definition at line 173 of file llurlrequest.cpp.

References mDetail, LLURLRequestDetail::mHeaders, and LLMemType::MTYPE_IO_URL_REQUEST.

Referenced by LLXMLSDRPCClientFactory< Client >::build(), LLSDRPCClientFactory< Client >::build(), configure(), and request().

void LLURLRequest::checkRootCertificate	(	bool	check,
		const char *	caBundle = `NULL`
	)

Check remote server certificate signed by a known root CA.

Set whether request will check that remote server certificates are signed by a known root CA when using HTTPS. Use the supplied root certificate bundle if supplied, else use the standard bundle as found by libcurl and openssl.

Definition at line 191 of file llurlrequest.cpp.

References FALSE, LLURLRequestDetail::mCurl, mDetail, and TRUE.

Referenced by request().

bool LLURLRequest::configure ( ) [private]

Handle action specific url request configuration.

Returns:: Returns true if this is configured.

Definition at line 422 of file llurlrequest.cpp.

References addHeader(), LLBufferArray::countAfter(), HTTP_DELETE, HTTP_GET, HTTP_POST, HTTP_PUT, LLChannelDescriptors::in(), llendl, llwarns, mAction, LLURLRequestDetail::mChannels, LLURLRequestDetail::mCurl, LLURLRequestDetail::mCurlMulti, mDetail, LLURLRequestDetail::mHeaders, LLURLRequestDetail::mNeedToRemoveEasyHandle, LLURLRequestDetail::mResponseBuffer, LLMemType::MTYPE_IO_URL_REQUEST, LLURLRequestDetail::mURL, NULL, and S32.

Referenced by process_impl().

size_t LLURLRequest::downCallback	(	void *	data,
		size_t	size,
		size_t	nmemb,
		void *	user
	)			`[static, private]`

Download callback method.

Definition at line 490 of file llurlrequest.cpp.

References LLBufferArray::append(), LLURLRequestDetail::mBodyLimit, LLURLRequestDetail::mChannels, mDetail, LLURLRequestDetail::mIsBodyLimitSet, LLURLRequestDetail::mResponseBuffer, mState, LLMemType::MTYPE_IO_URL_REQUEST, LLChannelDescriptors::out(), STATE_PROCESSING_RESPONSE, and STATE_WAITING_FOR_RESPONSE.

Referenced by initialize().

virtual EStatus LLURLRequest::handleError	(	EStatus	status,
		LLPumpIO *	pump
	)			`[virtual]`

Give this pipe a chance to handle a generated error.

void LLURLRequest::initialize ( ) [private]

Initialize the object. Called during construction.

Definition at line 395 of file llurlrequest.cpp.

References downCallback(), LLURLRequestDetail::mCurl, LLURLRequestDetail::mCurlErrorBuf, LLURLRequestDetail::mCurlMulti, mDetail, mState, LLMemType::MTYPE_IO_URL_REQUEST, sCAFile(), sCAPath(), STATE_INITIALIZED, and upCallback().

Referenced by LLURLRequest().

LLIOPipe::EStatus LLURLRequest::process_impl	(	const LLChannelDescriptors &	channels,
		buffer_ptr_t &	buffer,
		bool &	eos,
		LLSD &	context,
		LLPumpIO *	pump
	)			`[protected, virtual]`

Process the data in buffer.

Definition at line 271 of file llurlrequest.cpp.

References configure(), count, LLFastTimer::FTM_CURL, HTTP_POST, HTTP_PUT, llendl, llwarns, mAction, LLBufferArray::makeChannelConsumer(), LLPumpIO::LLLinkInfo::mChannels, LLURLRequestDetail::mChannels, mCompletionCallback, LLURLRequestDetail::mCurl, LLURLRequestDetail::mCurlMulti, mDetail, LLURLRequestDetail::mNeedToRemoveEasyHandle, LLPumpIO::LLLinkInfo::mPipe, LLURLRequestDetail::mResponseBuffer, mState, LLMemType::MTYPE_IO_URL_REQUEST, LLURLRequestDetail::mURL, NULL, PUMP_DEBUG, LLPumpIO::respond(), LLURLRequestComplete::responseStatus(), S32, STATE_HAVE_RESPONSE, STATE_INITIALIZED, STATE_PROCESSING_RESPONSE, STATE_WAITING_FOR_RESPONSE, LLIOPipe::STATUS_BREAK, LLIOPipe::STATUS_DONE, LLIOPipe::STATUS_ERROR, LLIOPipe::STATUS_NO_CONNECTION, LLIOPipe::STATUS_OK, and LLIOPipe::STATUS_STOP.

void LLURLRequest::requestEncoding ( const char * encoding )

Request a particular response encoding if available.

This call is a shortcut for requesting a particular encoding from the server, eg, 'gzip'.

Definition at line 179 of file llurlrequest.cpp.

References LLURLRequestDetail::mCurl, mDetail, and LLMemType::MTYPE_IO_URL_REQUEST.

Referenced by request().

void LLURLRequest::setBodyLimit ( U32 size )

Return at most size bytes of body.

If the body had more bytes than this limit, they will not be returned and the connection closed. In this case, STATUS_STOP will be passed to responseStatus();

Definition at line 185 of file llurlrequest.cpp.

References LLURLRequestDetail::mBodyLimit, mDetail, and LLURLRequestDetail::mIsBodyLimitSet.

void LLURLRequest::setCallback ( LLURLRequestComplete * callback )

Set a completion callback for this URLRequest.

The callback is added to this URLRequet's pump when either the entire buffer is known or an error like timeout or connection refused has happened. In the case of a complete transfer, this object builds a response chain such that the callback and the next process consumer get to read the output.

This setup is a little fragile since the url request consumer might not just read the data - it may do a channel change, which invalidates the input to the callback, but it works well in practice.

Definition at line 200 of file llurlrequest.cpp.

References headerCallback(), mCompletionCallback, LLURLRequestDetail::mCurl, mDetail, and LLMemType::MTYPE_IO_URL_REQUEST.

Referenced by request().

void LLURLRequest::setCertificateAuthorityFile ( const std::string & file_name ) [static]

@ brief Set certificate authority file used to verify HTTPS certs.

Definition at line 603 of file llurlrequest.cpp.

References sCAFile().

void LLURLRequest::setCertificateAuthorityPath ( const std::string & path ) [static]

@ brief Set certificate authority path used to verify HTTPS certs.

Definition at line 609 of file llurlrequest.cpp.

References sCAPath().

void LLURLRequest::setURL ( const std::string & url )

Set the url for the request.

This method assumes the url is encoded appropriately for the request. The url must be set somehow before the first call to process(), or the url will not be set correctly.

Definition at line 155 of file llurlrequest.cpp.

References mDetail, LLMemType::MTYPE_IO_URL_REQUEST, LLURLRequestDetail::mURL, and NULL.

Referenced by LLXMLSDRPCClientFactory< Client >::build(), LLSDRPCClientFactory< Client >::build(), LLURLRequest(), and LLContextURLExtractor::process_impl().