207 lines
6.5 KiB
C++
207 lines
6.5 KiB
C++
/**
|
|
* @file httpcommon.h
|
|
* @brief Public-facing declarations and definitions of common types
|
|
*
|
|
* $LicenseInfo:firstyear=2012&license=viewerlgpl$
|
|
* Second Life Viewer Source Code
|
|
* Copyright (C) 2012, Linden Research, Inc.
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation;
|
|
* version 2.1 of the License only.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
*
|
|
* Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA
|
|
* $/LicenseInfo$
|
|
*/
|
|
|
|
#ifndef _LLCORE_HTTP_COMMON_H_
|
|
#define _LLCORE_HTTP_COMMON_H_
|
|
|
|
/// @package LLCore::HTTP
|
|
///
|
|
/// This library implements a high-level, Indra-code-free client interface to
|
|
/// HTTP services based on actual patterns found in the viewer and simulator.
|
|
/// Interfaces are similar to those supplied by the legacy classes
|
|
/// LLCurlRequest and LLHTTPClient. To that is added a policy scheme that
|
|
/// allows an application to specify connection behaviors: limits on
|
|
/// connections, HTTP keepalive, HTTP pipelining, retry-on-error limits, etc.
|
|
///
|
|
/// Features of the library include:
|
|
/// - Single, private working thread where all transport and processing occurs.
|
|
/// - Support for multiple consumers running in multiple threads.
|
|
/// - Scatter/gather (a.k.a. buffer array) model for bulk data movement.
|
|
/// - Reference counting used for many object instance lifetimes.
|
|
/// - Minimal data sharing across threads for correctness and low latency.
|
|
///
|
|
/// The public interface is declared in a few key header files:
|
|
/// - "llcorehttp/bufferarray.h"
|
|
/// - "llcorehttp/httpcommon.h"
|
|
/// - "llcorehttp/httphandler.h"
|
|
/// - "llcorehttp/httpheaders.h"
|
|
/// - "llcorehttp/httpoptions.h"
|
|
/// - "llcorehttp/httprequest.h"
|
|
/// - "llcorehttp/httpresponse.h"
|
|
///
|
|
/// The library is still under early development and particular users
|
|
/// may need access to internal implementation details that are found
|
|
/// in the _*.h header files. But this is a crutch to be avoided if at
|
|
/// all possible and probably indicates some interface work is neeeded.
|
|
///
|
|
/// Using the library is fairly easy. Global setup needs a few
|
|
/// steps:
|
|
///
|
|
/// - libcurl initialization with thread-safely callbacks for c-ares
|
|
/// DNS lookups.
|
|
/// - HttpRequest::createService() called to instantiate singletons
|
|
/// and support objects.
|
|
///
|
|
/// An HTTP consumer in an application, and an application may have many
|
|
/// consumers, does a few things:
|
|
///
|
|
/// - Instantiate and retain an object based on HttpRequest. This
|
|
/// object becomes the portal into runtime services for the consumer.
|
|
/// - Derive or mixin the HttpHandler class if you want notification
|
|
/// when requests succeed or fail. This object's onCompleted()
|
|
/// method is invoked and an instance can be shared across
|
|
/// requests.
|
|
///
|
|
/// Issuing a request is straightforward:
|
|
/// - Construct a suitable URL.
|
|
/// - Configure HTTP options for the request. (optional)
|
|
/// - Build a list of additional headers. (optional)
|
|
/// - Invoke one of the requestXXXX() methods (requestGetByteRange,
|
|
/// requestPost, etc.) on the HttpRequest instance supplying the
|
|
/// above along with a policy class, a priority and an optional
|
|
/// pointer to an HttpHandler instance. Work is then queued to
|
|
/// the worker thread and occurs asynchronously.
|
|
/// - Periodically invoke the update() method on the HttpRequest
|
|
/// instance which performs completion notification to HttpHandler
|
|
/// objects.
|
|
/// - Do completion processing in your onCompletion() method.
|
|
///
|
|
/// Code fragments:
|
|
/// <TBD>
|
|
///
|
|
|
|
#include "linden_common.h"
|
|
|
|
#include <string>
|
|
|
|
|
|
namespace LLCore
|
|
{
|
|
|
|
|
|
/// All queued requests are represented by an HttpHandle value.
|
|
/// The invalid value is returned when a request failed to queue.
|
|
/// The actual status for these failures is then fetched with
|
|
/// HttpRequest::getStatus().
|
|
///
|
|
/// The handle is valid only for the life of a request. On
|
|
/// return from any HttpHandler notification, the handle immediately
|
|
/// becomes invalid and may be recycled for other queued requests.
|
|
|
|
typedef void * HttpHandle;
|
|
#define LLCORE_HTTP_HANDLE_INVALID (NULL)
|
|
|
|
|
|
/// Error codes defined by the library itself as distinct from
|
|
/// libcurl (or any other transport provider).
|
|
enum HttpError
|
|
{
|
|
// Successful value compatible with the libcurl codes.
|
|
HE_SUCCESS = 0,
|
|
|
|
// Service is shutting down and requested operation will
|
|
// not be queued or performed.
|
|
HE_SHUTTING_DOWN = 1,
|
|
|
|
// Operation was canceled by request.
|
|
HE_OP_CANCELED = 2,
|
|
|
|
// Invalid content range header received.
|
|
HE_INV_CONTENT_RANGE_HDR = 3
|
|
|
|
}; // end enum HttpError
|
|
|
|
|
|
/// HttpStatus encapsulates errors from libcurl (easy, multi) as well as
|
|
/// internal errors. The encapsulation isn't expected to completely
|
|
/// isolate the caller from libcurl but basic operational tests (success
|
|
/// or failure) are provided.
|
|
struct HttpStatus
|
|
{
|
|
typedef unsigned short type_enum_t;
|
|
|
|
HttpStatus()
|
|
: mType(LLCORE),
|
|
mStatus(HE_SUCCESS)
|
|
{}
|
|
|
|
HttpStatus(type_enum_t type, short status)
|
|
: mType(type),
|
|
mStatus(status)
|
|
{}
|
|
|
|
HttpStatus(const HttpStatus & rhs)
|
|
: mType(rhs.mType),
|
|
mStatus(rhs.mStatus)
|
|
{}
|
|
|
|
HttpStatus & operator=(const HttpStatus & rhs)
|
|
{
|
|
// Don't care if lhs & rhs are the same object
|
|
|
|
mType = rhs.mType;
|
|
mStatus = rhs.mStatus;
|
|
return *this;
|
|
}
|
|
|
|
static const type_enum_t EXT_CURL_EASY = 0;
|
|
static const type_enum_t EXT_CURL_MULTI = 1;
|
|
static const type_enum_t LLCORE = 2;
|
|
|
|
type_enum_t mType;
|
|
short mStatus;
|
|
|
|
/// Test for successful status in the code regardless
|
|
/// of error source (internal, libcurl).
|
|
///
|
|
/// @return 'true' when status is successful.
|
|
///
|
|
operator bool() const
|
|
{
|
|
return 0 == mStatus;
|
|
}
|
|
|
|
/// Inverse of previous operator.
|
|
///
|
|
/// @return 'true' on any error condition
|
|
bool operator !() const
|
|
{
|
|
return 0 != mStatus;
|
|
}
|
|
|
|
/// Convert status to a string representation. For
|
|
/// success, returns an empty string. For failure
|
|
/// statuses, a string as appropriate for the source of
|
|
/// the error code (libcurl easy, libcurl multi, or
|
|
/// LLCore itself).
|
|
std::string toString() const;
|
|
|
|
}; // end struct HttpStatus
|
|
|
|
} // end namespace LLCore
|
|
|
|
#endif // _LLCORE_HTTP_COMMON_H_
|