src/serf/serf_bucket_types.h

   1 /* Copyright 2002-2004 Justin Erenkrantz and Greg Stein
   2  *
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 #ifndef SERF_BUCKET_TYPES_H
  17 #define SERF_BUCKET_TYPES_H
  18
  19 #include <apr_mmap.h>
  20
  21 /* this header and serf.h refer to each other, so take a little extra care */
  22 #ifndef SERF_H
  23 #include "serf.h"
  24 #endif
  25
  26 #include "serf_declare.h"
  27
  28
  29 /**
  30  * @file serf_bucket_types.h
  31  * @brief serf-supported bucket types
  32  */
  33 /* ### this whole file needs docco ... */
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /* ==================================================================== */
  40
  41
  42 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_request;
  43 #define SERF_BUCKET_IS_REQUEST(b) SERF_BUCKET_CHECK((b), request)
  44
  45 SERF_DECLARE(serf_bucket_t *) serf_bucket_request_create(
  46     const char *method,
  47     const char *URI,
  48     serf_bucket_t *body,
  49     serf_bucket_alloc_t *allocator);
  50
  51 SERF_DECLARE(serf_bucket_t *) serf_bucket_request_get_headers(
  52     serf_bucket_t *request);
  53
  54 SERF_DECLARE(void) serf_bucket_request_become(serf_bucket_t *bucket,
  55                                               const char *method,
  56                                               const char *uri,
  57                                               serf_bucket_t *body);
  58
  59 /* ==================================================================== */
  60
  61
  62 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_response;
  63 #define SERF_BUCKET_IS_RESPONSE(b) SERF_BUCKET_CHECK((b), response)
  64
  65 SERF_DECLARE(serf_bucket_t *) serf_bucket_response_create(
  66     serf_bucket_t *stream,
  67     serf_bucket_alloc_t *allocator);
  68
  69 #define SERF_HTTP_VERSION(major, minor)  ((major) * 1000 + (minor))
  70 #define SERF_HTTP_11 SERF_HTTP_VERSION(1, 1)
  71 #define SERF_HTTP_10 SERF_HTTP_VERSION(1, 0)
  72
  73 typedef struct {
  74     int version;
  75     int code;
  76     const char *reason;
  77 } serf_status_line;
  78
  79 /**
  80  * Return the Status-Line information, if available. This function
  81  * works like other bucket read functions: it may return APR_EAGAIN or
  82  * APR_EOF to signal the state of the bucket for reading. A return
  83  * value of APR_SUCCESS will always indicate that status line
  84  * information was returned; for other return values the caller must
  85  * check the version field in @a sline. A value of 0 means that the
  86  * data is not (yet) present.
  87  */
  88 SERF_DECLARE(apr_status_t) serf_bucket_response_status(
  89     serf_bucket_t *bkt,
  90     serf_status_line *sline);
  91
  92 /**
  93  * Wait for the HTTP headers to be processed for a @a response.
  94  *
  95  * If the headers are available, APR_SUCCESS is returned.
  96  * If the headers aren't available, APR_EAGAIN is returned.
  97  */
  98 SERF_DECLARE(apr_status_t) serf_bucket_response_wait_for_headers(
  99     serf_bucket_t *response);
 100
 101 /**
 102  * Get the headers bucket for @a response.
 103  */
 104 SERF_DECLARE(serf_bucket_t *) serf_bucket_response_get_headers(
 105     serf_bucket_t *response);
 106
 107 /**
 108  * Advise the response @a bucket that this was from a HEAD request and
 109  * that it should not expect to see a response body.
 110  */
 111 SERF_DECLARE(void) serf_bucket_response_set_head(serf_bucket_t *bucket);
 112
 113 /* ==================================================================== */
 114
 115
 116 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_aggregate;
 117 #define SERF_BUCKET_IS_AGGREGATE(b) SERF_BUCKET_CHECK((b), aggregate)
 118
 119 SERF_DECLARE(serf_bucket_t *) serf_bucket_aggregate_create(
 120     serf_bucket_alloc_t *allocator);
 121
 122 /** Transform @a bucket in-place into an aggregate bucket. */
 123 SERF_DECLARE(void) serf_bucket_aggregate_become(serf_bucket_t *bucket);
 124
 125 SERF_DECLARE(void) serf_bucket_aggregate_prepend(
 126     serf_bucket_t *aggregate_bucket,
 127     serf_bucket_t *prepend_bucket);
 128
 129 SERF_DECLARE(void) serf_bucket_aggregate_append(
 130     serf_bucket_t *aggregate_bucket,
 131     serf_bucket_t *append_bucket);
 132
 133 SERF_DECLARE(void) serf_bucket_aggregate_prepend_iovec(
 134     serf_bucket_t *aggregate_bucket,
 135     struct iovec *vecs,
 136     int vecs_count);
 137
 138 SERF_DECLARE(void) serf_bucket_aggregate_append_iovec(
 139     serf_bucket_t *aggregate_bucket,
 140     struct iovec *vecs,
 141     int vecs_count);
 142
 143 /* ==================================================================== */
 144
 145
 146 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_file;
 147 #define SERF_BUCKET_IS_FILE(b) SERF_BUCKET_CHECK((b), file)
 148
 149 SERF_DECLARE(serf_bucket_t *) serf_bucket_file_create(
 150     apr_file_t *file,
 151     serf_bucket_alloc_t *allocator);
 152
 153 SERF_DECLARE(apr_file_t *) serf_bucket_file_borrow(serf_bucket_t *bkt);
 154
 155
 156 /* ==================================================================== */
 157
 158
 159 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_socket;
 160 #define SERF_BUCKET_IS_SOCKET(b) SERF_BUCKET_CHECK((b), socket)
 161
 162 SERF_DECLARE(serf_bucket_t *) serf_bucket_socket_create(
 163     apr_socket_t *skt,
 164     serf_bucket_alloc_t *allocator);
 165
 166
 167 /* ==================================================================== */
 168
 169
 170 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_simple;
 171 #define SERF_BUCKET_IS_SIMPLE(b) SERF_BUCKET_CHECK((b), simple)
 172
 173 typedef void (*serf_simple_freefunc_t)(void *baton, const char *data);
 174
 175 SERF_DECLARE(serf_bucket_t *) serf_bucket_simple_create(
 176     const char *data, apr_size_t len,
 177     serf_simple_freefunc_t freefunc,
 178     void *freefunc_baton,
 179     serf_bucket_alloc_t *allocator);
 180
 181 /**
 182  * Equivalent to serf_bucket_simple_create, except that the bucket takes
 183  * ownership of a private copy of the data.
 184  */
 185 SERF_DECLARE(serf_bucket_t *) serf_bucket_simple_copy_create(
 186     const char *data, apr_size_t len,
 187     serf_bucket_alloc_t *allocator);
 188
 189 #define SERF_BUCKET_SIMPLE_STRING(s,a) \
 190     serf_bucket_simple_create(s, strlen(s), NULL, NULL, a);
 191
 192 #define SERF_BUCKET_SIMPLE_STRING_LEN(s,l,a) \
 193     serf_bucket_simple_create(s, l, NULL, NULL, a);
 194
 195 /* ==================================================================== */
 196
 197
 198 /* Note: apr_mmap_t is always defined, but if APR doesn't have mmaps, then
 199    the caller can never create an apr_mmap_t to pass to this function. */
 200
 201 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_mmap;
 202 #define SERF_BUCKET_IS_MMAP(b) SERF_BUCKET_CHECK((b), mmap)
 203
 204 SERF_DECLARE(serf_bucket_t *) serf_bucket_mmap_create(
 205     apr_mmap_t *mmap,
 206     serf_bucket_alloc_t *allocator);
 207
 208
 209 /* ==================================================================== */
 210
 211
 212 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_headers;
 213 #define SERF_BUCKET_IS_HEADERS(b) SERF_BUCKET_CHECK((b), headers)
 214
 215 SERF_DECLARE(serf_bucket_t *) serf_bucket_headers_create(
 216     serf_bucket_alloc_t *allocator);
 217
 218 /**
 219  * Set, default: value copied.
 220  *
 221  * Set the specified @a header within the bucket, copying the @a value
 222  * into space from this bucket's allocator. The header is NOT copied,
 223  * so it should remain in scope at least as long as the bucket.
 224  */
 225 SERF_DECLARE(void) serf_bucket_headers_set(
 226     serf_bucket_t *headers_bucket,
 227     const char *header,
 228     const char *value);
 229
 230 /**
 231  * Set, copies: header and value copied.
 232  *
 233  * Copy the specified @a header and @a value into the bucket, using space
 234  * from this bucket's allocator.
 235  */
 236 SERF_DECLARE(void) serf_bucket_headers_setc(
 237     serf_bucket_t *headers_bucket,
 238     const char *header,
 239     const char *value);
 240
 241 /**
 242  * Set, no copies.
 243  *
 244  * Set the specified @a header and @a value into the bucket, without
 245  * copying either attribute. Both attributes should remain in scope at
 246  * least as long as the bucket.
 247  */
 248 SERF_DECLARE(void) serf_bucket_headers_setn(
 249     serf_bucket_t *headers_bucket,
 250     const char *header,
 251     const char *value);
 252
 253 /**
 254  * Set, extended: fine grained copy control of header and value.
 255  *
 256  * Set the specified @a header, with length @a header_size with the
 257  * @a value, and length @a value_size, into the bucket. The header will
 258  * be copied if @a header_copy is set, and the value is copied if
 259  * @a value_copy is set. If the values are not copied, then they should
 260  * remain in scope at least as long as the bucket.
 261  */
 262 SERF_DECLARE(void) serf_bucket_headers_setx(
 263     serf_bucket_t *headers_bucket,
 264     const char *header, apr_size_t header_size, int header_copy,
 265     const char *value, apr_size_t value_size, int value_copy);
 266
 267 SERF_DECLARE(const char *) serf_bucket_headers_get(
 268     serf_bucket_t *headers_bucket,
 269     const char *header);
 270
 271 /**
 272  * @param baton opaque baton as passed to @see serf_bucket_headers_do
 273  * @param key The header key from this iteration through the table
 274  * @param value The header value from this iteration through the table
 275  */
 276 typedef int (serf_bucket_headers_do_callback_fn_t)(
 277     void *baton,
 278     const char *key,
 279     const char *value);
 280
 281 /**
 282  * @param headers_bucket headers to iterate over
 283  * @param func callback routine to invoke for every header in the bucket
 284  * @param baton baton to pass on each invocation to func
 285  */
 286 SERF_DECLARE(void) serf_bucket_headers_do(
 287     serf_bucket_t *headers_bucket,
 288     serf_bucket_headers_do_callback_fn_t func,
 289     void *baton);
 290
 291
 292 /* ==================================================================== */
 293
 294
 295 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_chunk;
 296 #define SERF_BUCKET_IS_CHUNK(b) SERF_BUCKET_CHECK((b), chunk)
 297
 298 SERF_DECLARE(serf_bucket_t *) serf_bucket_chunk_create(
 299     serf_bucket_t *stream,
 300     serf_bucket_alloc_t *allocator);
 301
 302
 303 /* ==================================================================== */
 304
 305
 306 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_dechunk;
 307 #define SERF_BUCKET_IS_DECHUNK(b) SERF_BUCKET_CHECK((b), dechunk)
 308
 309 SERF_DECLARE(serf_bucket_t *) serf_bucket_dechunk_create(
 310     serf_bucket_t *stream,
 311     serf_bucket_alloc_t *allocator);
 312
 313
 314 /* ==================================================================== */
 315
 316
 317 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_deflate;
 318 #define SERF_BUCKET_IS_DEFLATE(b) SERF_BUCKET_CHECK((b), deflate)
 319
 320 #define SERF_DEFLATE_GZIP 0
 321 #define SERF_DEFLATE_DEFLATE 1
 322
 323 SERF_DECLARE(serf_bucket_t *) serf_bucket_deflate_create(
 324     serf_bucket_t *stream,
 325     serf_bucket_alloc_t *allocator,
 326     int format);
 327
 328
 329 /* ==================================================================== */
 330
 331
 332 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_limit;
 333 #define SERF_BUCKET_IS_LIMIT(b) SERF_BUCKET_CHECK((b), limit)
 334
 335 SERF_DECLARE(serf_bucket_t *) serf_bucket_limit_create(
 336     serf_bucket_t *stream,
 337     apr_size_t limit,
 338     serf_bucket_alloc_t *allocator);
 339
 340
 341 /* ==================================================================== */
 342
 343
 344 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_ssl_encrypt;
 345 #define SERF_BUCKET_IS_SSL_ENCRYPT(b) SERF_BUCKET_CHECK((b), ssl_encrypt)
 346
 347 typedef struct serf_ssl_context_t serf_ssl_context_t;
 348
 349 typedef apr_status_t (*serf_ssl_need_client_cert_t)(void *data,
 350                                                     const char **cert_path);
 351
 352 typedef apr_status_t (*serf_ssl_need_cert_password_t)(void *data,
 353                                                       const char *cert_path,
 354                                                       const char **password);
 355
 356 SERF_DECLARE(void)
 357 serf_ssl_client_cert_provider_set(serf_ssl_context_t *context,
 358                                   serf_ssl_need_client_cert_t callback,
 359                                   void *data,
 360                                   void *cache_pool);
 361
 362 SERF_DECLARE(void)
 363 serf_ssl_client_cert_password_set(serf_ssl_context_t *context,
 364                                   serf_ssl_need_cert_password_t callback,
 365                                   void *data,
 366                                   void *cache_pool);
 367
 368 SERF_DECLARE(serf_bucket_t *) serf_bucket_ssl_encrypt_create(
 369     serf_bucket_t *stream,
 370     serf_ssl_context_t *ssl_context,
 371     serf_bucket_alloc_t *allocator);
 372
 373 SERF_DECLARE(serf_ssl_context_t *) serf_bucket_ssl_encrypt_context_get(
 374     serf_bucket_t *bucket);
 375
 376 /* ==================================================================== */
 377
 378
 379 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_ssl_decrypt;
 380 #define SERF_BUCKET_IS_SSL_DECRYPT(b) SERF_BUCKET_CHECK((b), ssl_decrypt)
 381
 382 SERF_DECLARE(serf_bucket_t *) serf_bucket_ssl_decrypt_create(
 383     serf_bucket_t *stream,
 384     serf_ssl_context_t *ssl_context,
 385     serf_bucket_alloc_t *allocator);
 386
 387 SERF_DECLARE(serf_ssl_context_t *) serf_bucket_ssl_decrypt_context_get(
 388     serf_bucket_t *bucket);
 389
 390
 391 /* ==================================================================== */
 392
 393
 394 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_barrier;
 395 #define SERF_BUCKET_IS_BARRIER(b) SERF_BUCKET_CHECK((b), barrier)
 396
 397 SERF_DECLARE(serf_bucket_t *) serf_bucket_barrier_create(
 398     serf_bucket_t *stream,
 399     serf_bucket_alloc_t *allocator);
 400
 401
 402 /* ==================================================================== */
 403
 404 /* ### do we need a PIPE bucket type? they are simple apr_file_t objects */
 405
 406
 407 #ifdef __cplusplus
 408 }
 409 #endif
 410
 411 #endif  /* !SERF_BUCKET_TYPES_H */