Commit update benchmark results
[bluesky.git] / libs3-1.4 / inc / request.h
1 /** **************************************************************************
2  * request.h
3  * 
4  * Copyright 2008 Bryan Ischo <bryan@ischo.com>
5  * 
6  * This file is part of libs3.
7  * 
8  * libs3 is free software: you can redistribute it and/or modify it under the
9  * terms of the GNU General Public License as published by the Free Software
10  * Foundation, version 3 of the License.
11  *
12  * In addition, as a special exception, the copyright holders give
13  * permission to link the code of this library and its programs with the
14  * OpenSSL library, and distribute linked combinations including the two.
15  *
16  * libs3 is distributed in the hope that it will be useful, but WITHOUT ANY
17  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
19  * details.
20  *
21  * You should have received a copy of the GNU General Public License version 3
22  * along with libs3, in a file named COPYING.  If not, see
23  * <http://www.gnu.org/licenses/>.
24  *
25  ************************************************************************** **/
26
27 #ifndef REQUEST_H
28 #define REQUEST_H
29
30 #include "libs3.h"
31 #include "error_parser.h"
32 #include "response_headers_handler.h"
33 #include "util.h"
34
35 // Describes a type of HTTP request (these are our supported HTTP "verbs")
36 typedef enum
37 {
38     HttpRequestTypeGET,
39     HttpRequestTypeHEAD,
40     HttpRequestTypePUT,
41     HttpRequestTypeCOPY,
42     HttpRequestTypeDELETE
43 } HttpRequestType;
44
45
46 // This completely describes a request.  A RequestParams is not required to be
47 // allocated from the heap and its lifetime is not assumed to extend beyond
48 // the lifetime of the function to which it has been passed.
49 typedef struct RequestParams
50 {
51     // Request type, affects the HTTP verb used
52     HttpRequestType httpRequestType;
53
54     // Bucket context for request
55     S3BucketContext bucketContext;
56
57     // Key, if any
58     const char *key;
59
60     // Query params - ready to append to URI (i.e. ?p1=v1?p2=v2)
61     const char *queryParams;
62
63     // sub resource, like ?acl, ?location, ?torrent, ?logging
64     const char *subResource;
65
66     // If this is a copy operation, this gives the source bucket
67     const char *copySourceBucketName;
68
69     // If this is a copy operation, this gives the source key
70     const char *copySourceKey;
71
72     // Get conditions
73     const S3GetConditions *getConditions;
74
75     // Start byte
76     uint64_t startByte;
77
78     // Byte count
79     uint64_t byteCount;
80
81     // Put properties
82     const S3PutProperties *putProperties;
83
84     // Callback to be made when headers are available.  Might not be called.
85     S3ResponsePropertiesCallback *propertiesCallback;
86
87     // Callback to be made to supply data to send to S3.  Might not be called.
88     S3PutObjectDataCallback *toS3Callback;
89
90     // Number of bytes total that readCallback will supply
91     int64_t toS3CallbackTotalSize;
92
93     // Callback to be made that supplies data read from S3.
94     // Might not be called.
95     S3GetObjectDataCallback *fromS3Callback;
96
97     // Callback to be made when request is complete.  This will *always* be
98     // called.
99     S3ResponseCompleteCallback *completeCallback;
100
101     // Data passed to the callbacks
102     void *callbackData;
103 } RequestParams;
104
105
106 // This is the stuff associated with a request that needs to be on the heap
107 // (and thus live while a curl_multi is in use).
108 typedef struct Request
109 {
110     // These put the request on a doubly-linked list of requests in a
111     // request context, *if* the request is in a request context (else these
112     // will both be 0)
113     struct Request *prev, *next;
114
115     // The status of this Request, as will be reported to the user via the
116     // complete callback
117     S3Status status;
118
119     // The HTTP code returned by the S3 server, if it is known.  Would rather
120     // not have to keep track of this but S3 doesn't always indicate its
121     // errors the same way
122     int httpResponseCode;
123
124     // The HTTP headers to use for the curl request
125     struct curl_slist *headers;
126
127     // The CURL structure driving the request
128     CURL *curl;
129
130     // libcurl requires that the uri be stored outside of the curl handle
131     char uri[MAX_URI_SIZE + 1];
132
133     // Callback to be made when headers are available.  Might not be called.
134     S3ResponsePropertiesCallback *propertiesCallback;
135
136     // Callback to be made to supply data to send to S3.  Might not be called.
137     S3PutObjectDataCallback *toS3Callback;
138
139     // Number of bytes total that readCallback has left to supply
140     int64_t toS3CallbackBytesRemaining;
141
142     // Callback to be made that supplies data read from S3.
143     // Might not be called.
144     S3GetObjectDataCallback *fromS3Callback;
145
146     // Callback to be made when request is complete.  This will *always* be
147     // called.
148     S3ResponseCompleteCallback *completeCallback;
149
150     // Data passed to the callbacks
151     void *callbackData;
152
153     // Handler of response headers
154     ResponseHeadersHandler responseHeadersHandler;
155
156     // This is set to nonzero after the properties callback has been made
157     int propertiesCallbackMade;
158
159     // Parser of errors
160     ErrorParser errorParser;
161 } Request;
162
163
164 // Request functions
165 // ----------------------------------------------------------------------------
166
167 // Initialize the API
168 S3Status request_api_initialize(const char *userAgentInfo, int flags);
169
170 // Deinitialize the API
171 void request_api_deinitialize();
172
173 // Perform a request; if context is 0, performs the request immediately;
174 // otherwise, sets it up to be performed by context.
175 void request_perform(const RequestParams *params, S3RequestContext *context);
176
177 // Called by the internal request code or internal request context code when a
178 // curl has finished the request
179 void request_finish(Request *request);
180
181 // Convert a CURLE code to an S3Status
182 S3Status request_curl_code_to_status(CURLcode code);
183
184
185 #endif /* REQUEST_H */