1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
/**
* @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" // Modifies curl/curl.h interfaces
#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_
|
