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 #include <apr_hash.h>
  21
  22 /* this header and serf.h refer to each other, so take a little extra care */
  23 #ifndef SERF_H
  24 #include "serf.h"
  25 #endif
  26
  27 #include "serf_declare.h"
  28
  29
  30 /**
  31  * @file serf_bucket_types.h
  32  * @brief serf-supported bucket types
  33  */
  34 /* ### this whole file needs docco ... */
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /* ==================================================================== */
  41
  42
  43 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_request;
  44 #define SERF_BUCKET_IS_REQUEST(b) SERF_BUCKET_CHECK((b), request)
  45
  46 SERF_DECLARE(serf_bucket_t *) serf_bucket_request_create(
  47     const char *method,
  48     const char *URI,
  49     serf_bucket_t *body,
  50     serf_bucket_alloc_t *allocator);
  51
  52 SERF_DECLARE(serf_bucket_t *) serf_bucket_request_get_headers(
  53     serf_bucket_t *request);
  54
  55 SERF_DECLARE(void) serf_bucket_request_become(serf_bucket_t *bucket,
  56                                               const char *method,
  57                                               const char *uri,
  58                                               serf_bucket_t *body);
  59
  60 /**
  61  * Sets the root url of the remote host. If this request contains a relative
  62  * url, it will be prefixed with the root url to form an absolute url.
  63  * @a bucket is the request bucket. @a root_url is the absolute url of the
  64  * root of the remote host, without the closing '/'.
  65  */
  66 SERF_DECLARE(void) serf_bucket_request_set_root(serf_bucket_t *bucket,
  67                                                 const char *root_url);
  68
  69 /* ==================================================================== */
  70
  71
  72 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_response;
  73 #define SERF_BUCKET_IS_RESPONSE(b) SERF_BUCKET_CHECK((b), response)
  74
  75 SERF_DECLARE(serf_bucket_t *) serf_bucket_response_create(
  76     serf_bucket_t *stream,
  77     serf_bucket_alloc_t *allocator);
  78
  79 #define SERF_HTTP_VERSION(major, minor)  ((major) * 1000 + (minor))
  80 #define SERF_HTTP_11 SERF_HTTP_VERSION(1, 1)
  81 #define SERF_HTTP_10 SERF_HTTP_VERSION(1, 0)
  82
  83 typedef struct {
  84     int version;
  85     int code;
  86     const char *reason;
  87 } serf_status_line;
  88
  89 /**
  90  * Return the Status-Line information, if available. This function
  91  * works like other bucket read functions: it may return APR_EAGAIN or
  92  * APR_EOF to signal the state of the bucket for reading. A return
  93  * value of APR_SUCCESS will always indicate that status line
  94  * information was returned; for other return values the caller must
  95  * check the version field in @a sline. A value of 0 means that the
  96  * data is not (yet) present.
  97  */
  98 SERF_DECLARE(apr_status_t) serf_bucket_response_status(
  99     serf_bucket_t *bkt,
 100     serf_status_line *sline);
 101
 102 /**
 103  * Wait for the HTTP headers to be processed for a @a response.
 104  *
 105  * If the headers are available, APR_SUCCESS is returned.
 106  * If the headers aren't available, APR_EAGAIN is returned.
 107  */
 108 SERF_DECLARE(apr_status_t) serf_bucket_response_wait_for_headers(
 109     serf_bucket_t *response);
 110
 111 /**
 112  * Get the headers bucket for @a response.
 113  */
 114 SERF_DECLARE(serf_bucket_t *) serf_bucket_response_get_headers(
 115     serf_bucket_t *response);
 116
 117 /**
 118  * Advise the response @a bucket that this was from a HEAD request and
 119  * that it should not expect to see a response body.
 120  */
 121 SERF_DECLARE(void) serf_bucket_response_set_head(serf_bucket_t *bucket);
 122
 123 /* ==================================================================== */
 124
 125
 126 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_aggregate;
 127 #define SERF_BUCKET_IS_AGGREGATE(b) SERF_BUCKET_CHECK((b), aggregate)
 128
 129 SERF_DECLARE(serf_bucket_t *) serf_bucket_aggregate_create(
 130     serf_bucket_alloc_t *allocator);
 131
 132 /** Transform @a bucket in-place into an aggregate bucket. */
 133 SERF_DECLARE(void) serf_bucket_aggregate_become(serf_bucket_t *bucket);
 134
 135 SERF_DECLARE(void) serf_bucket_aggregate_prepend(
 136     serf_bucket_t *aggregate_bucket,
 137     serf_bucket_t *prepend_bucket);
 138
 139 SERF_DECLARE(void) serf_bucket_aggregate_append(
 140     serf_bucket_t *aggregate_bucket,
 141     serf_bucket_t *append_bucket);
 142
 143 SERF_DECLARE(void) serf_bucket_aggregate_prepend_iovec(
 144     serf_bucket_t *aggregate_bucket,
 145     struct iovec *vecs,
 146     int vecs_count);
 147
 148 SERF_DECLARE(void) serf_bucket_aggregate_append_iovec(
 149     serf_bucket_t *aggregate_bucket,
 150     struct iovec *vecs,
 151     int vecs_count);
 152
 153 /* ==================================================================== */
 154
 155
 156 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_file;
 157 #define SERF_BUCKET_IS_FILE(b) SERF_BUCKET_CHECK((b), file)
 158
 159 SERF_DECLARE(serf_bucket_t *) serf_bucket_file_create(
 160     apr_file_t *file,
 161     serf_bucket_alloc_t *allocator);
 162
 163 SERF_DECLARE(apr_file_t *) serf_bucket_file_borrow(serf_bucket_t *bkt);
 164
 165
 166 /* ==================================================================== */
 167
 168
 169 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_socket;
 170 #define SERF_BUCKET_IS_SOCKET(b) SERF_BUCKET_CHECK((b), socket)
 171
 172 SERF_DECLARE(serf_bucket_t *) serf_bucket_socket_create(
 173     apr_socket_t *skt,
 174     serf_bucket_alloc_t *allocator);
 175
 176 /**
 177  * Call @a progress_func every time bytes are read from the socket, pass
 178  * the number of bytes read.
 179  *
 180  * When using serf's bytes read & written progress indicator, pass
 181  * @a serf_context_progress_delta for progress_func and the serf_context for
 182  * progress_baton.
 183  */
 184 SERF_DECLARE(void) serf_bucket_socket_set_read_progress_cb(
 185     serf_bucket_t *bucket,
 186     const serf_progress_t progress_func,
 187     void *progress_baton);
 188
 189 /* ==================================================================== */
 190
 191
 192 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_simple;
 193 #define SERF_BUCKET_IS_SIMPLE(b) SERF_BUCKET_CHECK((b), simple)
 194
 195 typedef void (*serf_simple_freefunc_t)(void *baton, const char *data);
 196
 197 SERF_DECLARE(serf_bucket_t *) serf_bucket_simple_create(
 198     const char *data, apr_size_t len,
 199     serf_simple_freefunc_t freefunc,
 200     void *freefunc_baton,
 201     serf_bucket_alloc_t *allocator);
 202
 203 /**
 204  * Equivalent to serf_bucket_simple_create, except that the bucket takes
 205  * ownership of a private copy of the data.
 206  */
 207 SERF_DECLARE(serf_bucket_t *) serf_bucket_simple_copy_create(
 208     const char *data, apr_size_t len,
 209     serf_bucket_alloc_t *allocator);
 210
 211 #define SERF_BUCKET_SIMPLE_STRING(s,a) \
 212     serf_bucket_simple_create(s, strlen(s), NULL, NULL, a);
 213
 214 #define SERF_BUCKET_SIMPLE_STRING_LEN(s,l,a) \
 215     serf_bucket_simple_create(s, l, NULL, NULL, a);
 216
 217 /* ==================================================================== */
 218
 219
 220 /* Note: apr_mmap_t is always defined, but if APR doesn't have mmaps, then
 221    the caller can never create an apr_mmap_t to pass to this function. */
 222
 223 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_mmap;
 224 #define SERF_BUCKET_IS_MMAP(b) SERF_BUCKET_CHECK((b), mmap)
 225
 226 SERF_DECLARE(serf_bucket_t *) serf_bucket_mmap_create(
 227     apr_mmap_t *mmap,
 228     serf_bucket_alloc_t *allocator);
 229
 230
 231 /* ==================================================================== */
 232
 233
 234 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_headers;
 235 #define SERF_BUCKET_IS_HEADERS(b) SERF_BUCKET_CHECK((b), headers)
 236
 237 SERF_DECLARE(serf_bucket_t *) serf_bucket_headers_create(
 238     serf_bucket_alloc_t *allocator);
 239
 240 /**
 241  * Set, default: value copied.
 242  *
 243  * Set the specified @a header within the bucket, copying the @a value
 244  * into space from this bucket's allocator. The header is NOT copied,
 245  * so it should remain in scope at least as long as the bucket.
 246  */
 247 SERF_DECLARE(void) serf_bucket_headers_set(
 248     serf_bucket_t *headers_bucket,
 249     const char *header,
 250     const char *value);
 251
 252 /**
 253  * Set, copies: header and value copied.
 254  *
 255  * Copy the specified @a header and @a value into the bucket, using space
 256  * from this bucket's allocator.
 257  */
 258 SERF_DECLARE(void) serf_bucket_headers_setc(
 259     serf_bucket_t *headers_bucket,
 260     const char *header,
 261     const char *value);
 262
 263 /**
 264  * Set, no copies.
 265  *
 266  * Set the specified @a header and @a value into the bucket, without
 267  * copying either attribute. Both attributes should remain in scope at
 268  * least as long as the bucket.
 269  *
 270  * @note In the case where a header already exists this will result
 271  *       in a reallocation and copy, @see serf_bucket_headers_setn.
 272  */
 273 SERF_DECLARE(void) serf_bucket_headers_setn(
 274     serf_bucket_t *headers_bucket,
 275     const char *header,
 276     const char *value);
 277
 278 /**
 279  * Set, extended: fine grained copy control of header and value.
 280  *
 281  * Set the specified @a header, with length @a header_size with the
 282  * @a value, and length @a value_size, into the bucket. The header will
 283  * be copied if @a header_copy is set, and the value is copied if
 284  * @a value_copy is set. If the values are not copied, then they should
 285  * remain in scope at least as long as the bucket.
 286  *
 287  * If @a headers_bucket already contains a header with the same name
 288  * as @a header, then append @a value to the existing value,
 289  * separating with a comma (as per RFC 2616, section 4.2).  In this
 290  * case, the new value must be allocated and the header re-used, so
 291  * behave as if @a value_copy were true and @a header_copy false.
 292  */
 293 SERF_DECLARE(void) serf_bucket_headers_setx(
 294     serf_bucket_t *headers_bucket,
 295     const char *header, apr_size_t header_size, int header_copy,
 296     const char *value, apr_size_t value_size, int value_copy);
 297
 298 SERF_DECLARE(const char *) serf_bucket_headers_get(
 299     serf_bucket_t *headers_bucket,
 300     const char *header);
 301
 302 /**
 303  * @param baton opaque baton as passed to @see serf_bucket_headers_do
 304  * @param key The header key from this iteration through the table
 305  * @param value The header value from this iteration through the table
 306  */
 307 typedef int (serf_bucket_headers_do_callback_fn_t)(
 308     void *baton,
 309     const char *key,
 310     const char *value);
 311
 312 /**
 313  * @param headers_bucket headers to iterate over
 314  * @param func callback routine to invoke for every header in the bucket
 315  * @param baton baton to pass on each invocation to func
 316  */
 317 SERF_DECLARE(void) serf_bucket_headers_do(
 318     serf_bucket_t *headers_bucket,
 319     serf_bucket_headers_do_callback_fn_t func,
 320     void *baton);
 321
 322
 323 /* ==================================================================== */
 324
 325
 326 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_chunk;
 327 #define SERF_BUCKET_IS_CHUNK(b) SERF_BUCKET_CHECK((b), chunk)
 328
 329 SERF_DECLARE(serf_bucket_t *) serf_bucket_chunk_create(
 330     serf_bucket_t *stream,
 331     serf_bucket_alloc_t *allocator);
 332
 333
 334 /* ==================================================================== */
 335
 336
 337 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_dechunk;
 338 #define SERF_BUCKET_IS_DECHUNK(b) SERF_BUCKET_CHECK((b), dechunk)
 339
 340 SERF_DECLARE(serf_bucket_t *) serf_bucket_dechunk_create(
 341     serf_bucket_t *stream,
 342     serf_bucket_alloc_t *allocator);
 343
 344
 345 /* ==================================================================== */
 346
 347
 348 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_deflate;
 349 #define SERF_BUCKET_IS_DEFLATE(b) SERF_BUCKET_CHECK((b), deflate)
 350
 351 #define SERF_DEFLATE_GZIP 0
 352 #define SERF_DEFLATE_DEFLATE 1
 353
 354 SERF_DECLARE(serf_bucket_t *) serf_bucket_deflate_create(
 355     serf_bucket_t *stream,
 356     serf_bucket_alloc_t *allocator,
 357     int format);
 358
 359
 360 /* ==================================================================== */
 361
 362
 363 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_limit;
 364 #define SERF_BUCKET_IS_LIMIT(b) SERF_BUCKET_CHECK((b), limit)
 365
 366 SERF_DECLARE(serf_bucket_t *) serf_bucket_limit_create(
 367     serf_bucket_t *stream,
 368     apr_size_t limit,
 369     serf_bucket_alloc_t *allocator);
 370
 371
 372 /* ==================================================================== */
 373 #define SERF_SSL_CERT_NOTYETVALID       1
 374 #define SERF_SSL_CERT_EXPIRED           2
 375 #define SERF_SSL_CERT_UNKNOWNCA         4
 376 #define SERF_SSL_CERT_SELF_SIGNED       8
 377 #define SERF_SSL_CERT_UNKNOWN_FAILURE  16
 378
 379 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_ssl_encrypt;
 380 #define SERF_BUCKET_IS_SSL_ENCRYPT(b) SERF_BUCKET_CHECK((b), ssl_encrypt)
 381
 382 typedef struct serf_ssl_context_t serf_ssl_context_t;
 383 typedef struct serf_ssl_certificate_t serf_ssl_certificate_t;
 384
 385 typedef apr_status_t (*serf_ssl_need_client_cert_t)(void *data,
 386                                                     const char **cert_path);
 387
 388 typedef apr_status_t (*serf_ssl_need_cert_password_t)(void *data,
 389                                                       const char *cert_path,
 390                                                       const char **password);
 391
 392 typedef apr_status_t
 393 (*serf_ssl_need_server_cert_t)(void *data,
 394                                int failures,
 395                                const serf_ssl_certificate_t *cert);
 396
 397 SERF_DECLARE(void)
 398 serf_ssl_client_cert_provider_set(serf_ssl_context_t *context,
 399                                   serf_ssl_need_client_cert_t callback,
 400                                   void *data,
 401                                   void *cache_pool);
 402
 403 SERF_DECLARE(void)
 404 serf_ssl_client_cert_password_set(serf_ssl_context_t *context,
 405                                   serf_ssl_need_cert_password_t callback,
 406                                   void *data,
 407                                   void *cache_pool);
 408 /**
 409  * Set a callback to override the default SSL server certificate validation
 410  * algorithm.
 411  */
 412 SERF_DECLARE(void)
 413 serf_ssl_server_cert_callback_set(serf_ssl_context_t *context,
 414                                   serf_ssl_need_server_cert_t callback,
 415                                   void *data);
 416
 417 /**
 418  * Use the default root CA certificates as included with the OpenSSL library.
 419  */
 420 SERF_DECLARE(apr_status_t)
 421 serf_ssl_use_default_certificates(serf_ssl_context_t *context);
 422
 423 /**
 424  * Extract the fields of the issuer in a table with keys (E, CN, OU, O, L,
 425  * ST and C). The returned table will be allocated in @a pool.
 426  */
 427 SERF_DECLARE(apr_hash_t *)
 428 serf_ssl_cert_issuer(const serf_ssl_certificate_t *cert, apr_pool_t *pool);
 429
 430 /**
 431  * Extract the fields of the subject in a table with keys (E, CN, OU, O, L,
 432  * ST and C). The returned table will be allocated in @a pool.
 433  */
 434 SERF_DECLARE(apr_hash_t *)
 435 serf_ssl_cert_subject(const serf_ssl_certificate_t *cert, apr_pool_t *pool);
 436
 437 /**
 438  * Extract the fields of the certificate in a table with keys (sha1, notBefore,
 439  * notAfter). The returned table will be allocated in @a pool.
 440  */
 441 SERF_DECLARE(apr_hash_t *)
 442 serf_ssl_cert_certificate(const serf_ssl_certificate_t *cert, apr_pool_t *pool);
 443
 444 /**
 445  * Load a CA certificate file from a path @a file_path. If the file was loaded
 446  * and parsed correctly, a certificate @a cert will be created and returned.
 447  * This certificate object will be alloced in @a pool.
 448  */
 449 SERF_DECLARE(apr_status_t)
 450 serf_ssl_load_cert_file(serf_ssl_certificate_t **cert, const char *file_path,
 451                         apr_pool_t *pool);
 452
 453 /**
 454  * Adds the certificate @a cert to the list of trusted certificates in
 455  * @a ssl_ctx that will be used for verification.
 456  * See also @a serf_ssl_load_cert_file.
 457  */
 458 SERF_DECLARE(apr_status_t)
 459 serf_ssl_trust_cert(serf_ssl_context_t *ssl_ctx, serf_ssl_certificate_t *cert);
 460
 461 SERF_DECLARE(serf_bucket_t *) serf_bucket_ssl_encrypt_create(
 462     serf_bucket_t *stream,
 463     serf_ssl_context_t *ssl_context,
 464     serf_bucket_alloc_t *allocator);
 465
 466 SERF_DECLARE(serf_ssl_context_t *) serf_bucket_ssl_encrypt_context_get(
 467     serf_bucket_t *bucket);
 468
 469 /* ==================================================================== */
 470
 471
 472 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_ssl_decrypt;
 473 #define SERF_BUCKET_IS_SSL_DECRYPT(b) SERF_BUCKET_CHECK((b), ssl_decrypt)
 474
 475 SERF_DECLARE(serf_bucket_t *) serf_bucket_ssl_decrypt_create(
 476     serf_bucket_t *stream,
 477     serf_ssl_context_t *ssl_context,
 478     serf_bucket_alloc_t *allocator);
 479
 480 SERF_DECLARE(serf_ssl_context_t *) serf_bucket_ssl_decrypt_context_get(
 481     serf_bucket_t *bucket);
 482
 483
 484 /* ==================================================================== */
 485
 486
 487 SERF_DECLARE_DATA extern const serf_bucket_type_t serf_bucket_type_barrier;
 488 #define SERF_BUCKET_IS_BARRIER(b) SERF_BUCKET_CHECK((b), barrier)
 489
 490 SERF_DECLARE(serf_bucket_t *) serf_bucket_barrier_create(
 491     serf_bucket_t *stream,
 492     serf_bucket_alloc_t *allocator);
 493
 494
 495 /* ==================================================================== */
 496
 497 /* ### do we need a PIPE bucket type? they are simple apr_file_t objects */
 498
 499
 500 #ifdef __cplusplus
 501 }
 502 #endif
 503
 504 #endif  /* !SERF_BUCKET_TYPES_H */