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 */