/* ====================================================================

 *    Licensed to the Apache Software Foundation (ASF) under one

 *    or more contributor license agreements.  See the NOTICE file

 *    distributed with this work for additional information

 *    regarding copyright ownership.  The ASF licenses this file

 *    to you under the Apache License, Version 2.0 (the

 *    "License"); you may not use this file except in compliance

 *    with the License.  You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 *    Unless required by applicable law or agreed to in writing,

 *    software distributed under the License is distributed on an

 *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

 *    KIND, either express or implied.  See the License for the

 *    specific language governing permissions and limitations

 *    under the License.

 * ====================================================================

 */

#ifndef SERF_BUCKET_TYPES_H

#define SERF_BUCKET_TYPES_H

#include <apr_mmap.h>

#include <apr_hash.h>

/* this header and serf.h refer to each other, so take a little extra care */

#ifndef SERF_H

#include "serf.h"

#endif

/**

 * @file serf_bucket_types.h

 * @brief serf-supported bucket types

 */

/* ### this whole file needs docco ... */

#ifdef __cplusplus

extern "C" {

#endif

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_request;

#define SERF_BUCKET_IS_REQUEST(b) SERF_BUCKET_CHECK((b), request)

serf_bucket_t *serf_bucket_request_create(

    const char *method,

    const char *URI,

    serf_bucket_t *body,

    serf_bucket_alloc_t *allocator);

/* Send a Content-Length header with @a len. The @a body bucket should

   contain precisely that much data.  */

void serf_bucket_request_set_CL(

    serf_bucket_t *bucket,

    apr_int64_t len);

serf_bucket_t *serf_bucket_request_get_headers(

    serf_bucket_t *request);

void serf_bucket_request_become(

    serf_bucket_t *bucket,

    const char *method,

    const char *uri,

    serf_bucket_t *body);

/**

 * Sets the root url of the remote host. If this request contains a relative

 * url, it will be prefixed with the root url to form an absolute url.

 * @a bucket is the request bucket. @a root_url is the absolute url of the

 * root of the remote host, without the closing '/'.

 */

void serf_bucket_request_set_root(

    serf_bucket_t *bucket,

    const char *root_url);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_response;

#define SERF_BUCKET_IS_RESPONSE(b) SERF_BUCKET_CHECK((b), response)

serf_bucket_t *serf_bucket_response_create(

    serf_bucket_t *stream,

    serf_bucket_alloc_t *allocator);

#define SERF_HTTP_VERSION(major, minor)  ((major) * 1000 + (minor))

#define SERF_HTTP_11 SERF_HTTP_VERSION(1, 1)

#define SERF_HTTP_10 SERF_HTTP_VERSION(1, 0)

#define SERF_HTTP_VERSION_MAJOR(shv) ((int)shv / 1000)

#define SERF_HTTP_VERSION_MINOR(shv) ((int)shv % 1000)

typedef struct {

    int version;

    int code;

    const char *reason;

} serf_status_line;

/**

 * Return the Status-Line information, if available. This function

 * works like other bucket read functions: it may return APR_EAGAIN or

 * APR_EOF to signal the state of the bucket for reading. A return

 * value of APR_SUCCESS will always indicate that status line

 * information was returned; for other return values the caller must

 * check the version field in @a sline. A value of 0 means that the

 * data is not (yet) present.

 */

apr_status_t serf_bucket_response_status(

    serf_bucket_t *bkt,

    serf_status_line *sline);

/**

 * Wait for the HTTP headers to be processed for a @a response.

 *

 * If the headers are available, APR_SUCCESS is returned.

 * If the headers aren't available, APR_EAGAIN is returned.

 */

apr_status_t serf_bucket_response_wait_for_headers(

    serf_bucket_t *response);

/**

 * Get the headers bucket for @a response.

 */

serf_bucket_t *serf_bucket_response_get_headers(

    serf_bucket_t *response);

/**

 * Advise the response @a bucket that this was from a HEAD request and

 * that it should not expect to see a response body.

 */

void serf_bucket_response_set_head(

    serf_bucket_t *bucket);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_response_body;

#define SERF_BUCKET_IS_RESPONSE_BODY(b) SERF_BUCKET_CHECK((b), response_body)

serf_bucket_t *serf_bucket_response_body_create(

    serf_bucket_t *stream,

    apr_uint64_t limit,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_bwtp_frame;

#define SERF_BUCKET_IS_BWTP_FRAME(b) SERF_BUCKET_CHECK((b), bwtp_frame)

extern const serf_bucket_type_t serf_bucket_type_bwtp_incoming_frame;

#define SERF_BUCKET_IS_BWTP_INCOMING_FRAME(b) SERF_BUCKET_CHECK((b), bwtp_incoming_frame)

int serf_bucket_bwtp_frame_get_channel(

    serf_bucket_t *hdr);

int serf_bucket_bwtp_frame_get_type(

    serf_bucket_t *hdr);

const char *serf_bucket_bwtp_frame_get_phrase(

    serf_bucket_t *hdr);

serf_bucket_t *serf_bucket_bwtp_frame_get_headers(

    serf_bucket_t *hdr);

serf_bucket_t *serf_bucket_bwtp_channel_open(

    int channel,

    const char *URI,

    serf_bucket_alloc_t *allocator);

serf_bucket_t *serf_bucket_bwtp_channel_close(

    int channel,

    serf_bucket_alloc_t *allocator);

serf_bucket_t *serf_bucket_bwtp_header_create(

    int channel,

    const char *phrase,

    serf_bucket_alloc_t *allocator);

serf_bucket_t *serf_bucket_bwtp_message_create(

    int channel,

    serf_bucket_t *body,

    serf_bucket_alloc_t *allocator);

serf_bucket_t *serf_bucket_bwtp_incoming_frame_create(

    serf_bucket_t *bkt,

    serf_bucket_alloc_t *allocator);

apr_status_t serf_bucket_bwtp_incoming_frame_wait_for_headers(

    serf_bucket_t *bkt);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_aggregate;

#define SERF_BUCKET_IS_AGGREGATE(b) SERF_BUCKET_CHECK((b), aggregate)

typedef apr_status_t (*serf_bucket_aggregate_eof_t)(

    void *baton,

    serf_bucket_t *aggregate_bucket);

/** serf_bucket_aggregate_cleanup will instantly destroy all buckets in

    the aggregate bucket that have been read completely. Whereas normally, 

    these buckets are destroyed on every read operation. */ 

void serf_bucket_aggregate_cleanup(

    serf_bucket_t *bucket,

    serf_bucket_alloc_t *allocator);

serf_bucket_t *serf_bucket_aggregate_create(

    serf_bucket_alloc_t *allocator);

/* Creates a stream bucket.

   A stream bucket is like an aggregate bucket, but:

   - it doesn't destroy its child buckets on cleanup

   - one can always keep adding child buckets, the handler FN should return

     APR_EOF when no more buckets will be added.

  Note: keep this factory function internal for now. If it turns out this

  bucket type is useful outside serf, we should make it an actual separate

  type.

  */

serf_bucket_t *serf__bucket_stream_create(

    serf_bucket_alloc_t *allocator,

    serf_bucket_aggregate_eof_t fn,

    void *baton);

/** Transform @a bucket in-place into an aggregate bucket. */

void serf_bucket_aggregate_become(

    serf_bucket_t *bucket);

void serf_bucket_aggregate_prepend(

    serf_bucket_t *aggregate_bucket,

    serf_bucket_t *prepend_bucket);

void serf_bucket_aggregate_append(

    serf_bucket_t *aggregate_bucket,

    serf_bucket_t *append_bucket);

void serf_bucket_aggregate_hold_open(

    serf_bucket_t *aggregate_bucket,

    serf_bucket_aggregate_eof_t fn,

    void *baton);

void serf_bucket_aggregate_prepend_iovec(

    serf_bucket_t *aggregate_bucket,

    struct iovec *vecs,

    int vecs_count);

void serf_bucket_aggregate_append_iovec(

    serf_bucket_t *aggregate_bucket,

    struct iovec *vecs,

    int vecs_count);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_file;

#define SERF_BUCKET_IS_FILE(b) SERF_BUCKET_CHECK((b), file)

serf_bucket_t *serf_bucket_file_create(

    apr_file_t *file,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_socket;

#define SERF_BUCKET_IS_SOCKET(b) SERF_BUCKET_CHECK((b), socket)

serf_bucket_t *serf_bucket_socket_create(

    apr_socket_t *skt,

    serf_bucket_alloc_t *allocator);

/**

 * Call @a progress_func every time bytes are read from the socket, pass

 * the number of bytes read.

 *

 * When using serf's bytes read & written progress indicator, pass 

 * @a serf_context_progress_delta for progress_func and the serf_context for

 * progress_baton.

 */

void serf_bucket_socket_set_read_progress_cb(

    serf_bucket_t *bucket,

    const serf_progress_t progress_func,

    void *progress_baton);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_simple;

#define SERF_BUCKET_IS_SIMPLE(b) SERF_BUCKET_CHECK((b), simple)

typedef void (*serf_simple_freefunc_t)(

    void *baton,

    const char *data);

serf_bucket_t *serf_bucket_simple_create(

    const char *data,

    apr_size_t len,

    serf_simple_freefunc_t freefunc,

    void *freefunc_baton,

    serf_bucket_alloc_t *allocator);

/**

 * Equivalent to serf_bucket_simple_create, except that the bucket takes

 * ownership of a private copy of the data.

 */

serf_bucket_t *serf_bucket_simple_copy_create(

    const char *data,

    apr_size_t len,

    serf_bucket_alloc_t *allocator);

/**

 * Equivalent to serf_bucket_simple_create, except that the bucket assumes

 * responsibility for freeing the data on this allocator without making

 * a copy.  It is assumed that data was created by a call from allocator.

 */

serf_bucket_t *serf_bucket_simple_own_create(

    const char *data,

    apr_size_t len,

    serf_bucket_alloc_t *allocator);

#define SERF_BUCKET_SIMPLE_STRING(s,a) \

    serf_bucket_simple_create(s, strlen(s), NULL, NULL, a);

#define SERF_BUCKET_SIMPLE_STRING_LEN(s,l,a) \

    serf_bucket_simple_create(s, l, NULL, NULL, a);

/* ==================================================================== */

/* Note: apr_mmap_t is always defined, but if APR doesn't have mmaps, then

   the caller can never create an apr_mmap_t to pass to this function. */

extern const serf_bucket_type_t serf_bucket_type_mmap;

#define SERF_BUCKET_IS_MMAP(b) SERF_BUCKET_CHECK((b), mmap)

serf_bucket_t *serf_bucket_mmap_create(

    apr_mmap_t *mmap,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_headers;

#define SERF_BUCKET_IS_HEADERS(b) SERF_BUCKET_CHECK((b), headers)

serf_bucket_t *serf_bucket_headers_create(

    serf_bucket_alloc_t *allocator);

/**

 * Set, default: value copied.

 *

 * Set the specified @a header within the bucket, copying the @a value

 * into space from this bucket's allocator. The header is NOT copied,

 * so it should remain in scope at least as long as the bucket.

 */

void serf_bucket_headers_set(

    serf_bucket_t *headers_bucket,

    const char *header,

    const char *value);

/**

 * Set, copies: header and value copied.

 *

 * Copy the specified @a header and @a value into the bucket, using space

 * from this bucket's allocator.

 */

void serf_bucket_headers_setc(

    serf_bucket_t *headers_bucket,

    const char *header,

    const char *value);

/**

 * Set, no copies.

 *

 * Set the specified @a header and @a value into the bucket, without

 * copying either attribute. Both attributes should remain in scope at

 * least as long as the bucket.

 *

 * @note In the case where a header already exists this will result

 *       in a reallocation and copy, @see serf_bucket_headers_setn.

 */

void serf_bucket_headers_setn(

    serf_bucket_t *headers_bucket,

    const char *header,

    const char *value);

/**

 * Set, extended: fine grained copy control of header and value.

 *

 * Set the specified @a header, with length @a header_size with the

 * @a value, and length @a value_size, into the bucket. The header will

 * be copied if @a header_copy is set, and the value is copied if

 * @a value_copy is set. If the values are not copied, then they should

 * remain in scope at least as long as the bucket.

 *

 * If @a headers_bucket already contains a header with the same name

 * as @a header, then append @a value to the existing value,

 * separating with a comma (as per RFC 2616, section 4.2).  In this

 * case, the new value must be allocated and the header re-used, so

 * behave as if @a value_copy were true and @a header_copy false.

 */

void serf_bucket_headers_setx(

    serf_bucket_t *headers_bucket,

    const char *header,

    apr_size_t header_size,

    int header_copy,

    const char *value,

    apr_size_t value_size,

    int value_copy);

const char *serf_bucket_headers_get(

    serf_bucket_t *headers_bucket,

    const char *header);

/**

 * @param baton opaque baton as passed to @see serf_bucket_headers_do

 * @param key The header key from this iteration through the table

 * @param value The header value from this iteration through the table

 */

typedef int (serf_bucket_headers_do_callback_fn_t)(

    void *baton,

    const char *key,

    const char *value);

/**

 * Iterates over all headers of the message and invokes the callback 

 * function with header key and value. Stop iterating when no more

 * headers are available or when the callback function returned a 

 * non-0 value.

 *

 * @param headers_bucket headers to iterate over

 * @param func callback routine to invoke for every header in the bucket

 * @param baton baton to pass on each invocation to func

 */

void serf_bucket_headers_do(

    serf_bucket_t *headers_bucket,

    serf_bucket_headers_do_callback_fn_t func,

    void *baton);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_chunk;

#define SERF_BUCKET_IS_CHUNK(b) SERF_BUCKET_CHECK((b), chunk)

serf_bucket_t *serf_bucket_chunk_create(

    serf_bucket_t *stream,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_dechunk;

#define SERF_BUCKET_IS_DECHUNK(b) SERF_BUCKET_CHECK((b), dechunk)

serf_bucket_t *serf_bucket_dechunk_create(

    serf_bucket_t *stream,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_deflate;

#define SERF_BUCKET_IS_DEFLATE(b) SERF_BUCKET_CHECK((b), deflate)

#define SERF_DEFLATE_GZIP 0

#define SERF_DEFLATE_DEFLATE 1

serf_bucket_t *serf_bucket_deflate_create(

    serf_bucket_t *stream,

    serf_bucket_alloc_t *allocator,

    int format);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_limit;

#define SERF_BUCKET_IS_LIMIT(b) SERF_BUCKET_CHECK((b), limit)

serf_bucket_t *serf_bucket_limit_create(

    serf_bucket_t *stream,

    apr_uint64_t limit,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

#define SERF_SSL_CERT_NOTYETVALID       1

#define SERF_SSL_CERT_EXPIRED           2

#define SERF_SSL_CERT_UNKNOWNCA         4

#define SERF_SSL_CERT_SELF_SIGNED       8

#define SERF_SSL_CERT_UNKNOWN_FAILURE  16

#define SERF_SSL_CERT_REVOKED          32

extern const serf_bucket_type_t serf_bucket_type_ssl_encrypt;

#define SERF_BUCKET_IS_SSL_ENCRYPT(b) SERF_BUCKET_CHECK((b), ssl_encrypt)

typedef struct serf_ssl_context_t serf_ssl_context_t;

typedef struct serf_ssl_certificate_t serf_ssl_certificate_t;

typedef apr_status_t (*serf_ssl_need_client_cert_t)(

    void *data,

    const char **cert_path);

typedef apr_status_t (*serf_ssl_need_cert_password_t)(

    void *data,

    const char *cert_path,

    const char **password);

typedef apr_status_t (*serf_ssl_need_server_cert_t)(

    void *data, 

    int failures,

    const serf_ssl_certificate_t *cert);

typedef apr_status_t (*serf_ssl_server_cert_chain_cb_t)(

    void *data,

    int failures,

    int error_depth,

    const serf_ssl_certificate_t * const * certs,

    apr_size_t certs_len);

void serf_ssl_client_cert_provider_set(

    serf_ssl_context_t *context,

    serf_ssl_need_client_cert_t callback,

    void *data,

    void *cache_pool);

void serf_ssl_client_cert_password_set(

    serf_ssl_context_t *context,

    serf_ssl_need_cert_password_t callback,

    void *data,

    void *cache_pool);

/**

 * Set a callback to override the default SSL server certificate validation 

 * algorithm.

 */

void serf_ssl_server_cert_callback_set(

    serf_ssl_context_t *context,

    serf_ssl_need_server_cert_t callback,

    void *data);

/**

 * Set callbacks to override the default SSL server certificate validation 

 * algorithm for the current certificate or the entire certificate chain. 

 */

void serf_ssl_server_cert_chain_callback_set(

    serf_ssl_context_t *context,

    serf_ssl_need_server_cert_t cert_callback,

    serf_ssl_server_cert_chain_cb_t cert_chain_callback,

    void *data);

/**

 * Use the default root CA certificates as included with the OpenSSL library.

 */

apr_status_t serf_ssl_use_default_certificates(

    serf_ssl_context_t *context);

/**

 * Allow SNI indicators to be sent to the server.

 */

apr_status_t serf_ssl_set_hostname(

    serf_ssl_context_t *context, const char *hostname);

/**

 * Return the depth of the certificate.

 */

int serf_ssl_cert_depth(

    const serf_ssl_certificate_t *cert);

/**

 * Extract the fields of the issuer in a table with keys (E, CN, OU, O, L, 

 * ST and C). The returned table will be allocated in @a pool.

 */

apr_hash_t *serf_ssl_cert_issuer(

    const serf_ssl_certificate_t *cert,

    apr_pool_t *pool);

/**

 * Extract the fields of the subject in a table with keys (E, CN, OU, O, L, 

 * ST and C). The returned table will be allocated in @a pool.

 */

apr_hash_t *serf_ssl_cert_subject(

    const serf_ssl_certificate_t *cert,

    apr_pool_t *pool);

/**

 * Extract the fields of the certificate in a table with keys (sha1, notBefore,

 * notAfter, subjectAltName). The returned table will be allocated in @a pool.

 */

apr_hash_t *serf_ssl_cert_certificate(

    const serf_ssl_certificate_t *cert,

    apr_pool_t *pool);

/**

 * Export a certificate to base64-encoded, zero-terminated string.

 * The returned string is allocated in @a pool. Returns NULL on failure.

 */

const char *serf_ssl_cert_export(

    const serf_ssl_certificate_t *cert,

    apr_pool_t *pool);

/**

 * Load a CA certificate file from a path @a file_path. If the file was loaded

 * and parsed correctly, a certificate @a cert will be created and returned.

 * This certificate object will be alloced in @a pool.

 */

apr_status_t serf_ssl_load_cert_file(

    serf_ssl_certificate_t **cert,

    const char *file_path,

    apr_pool_t *pool);

/**

 * Adds the certificate @a cert to the list of trusted certificates in 

 * @a ssl_ctx that will be used for verification. 

 * See also @a serf_ssl_load_cert_file.

 */

apr_status_t serf_ssl_trust_cert(

    serf_ssl_context_t *ssl_ctx,

    serf_ssl_certificate_t *cert);

/**

 * Enable or disable SSL compression on a SSL session.

 * @a enabled = 1 to enable compression, 0 to disable compression.

 * Default = disabled.

 */

apr_status_t serf_ssl_use_compression(

    serf_ssl_context_t *ssl_ctx,

    int enabled);

serf_bucket_t *serf_bucket_ssl_encrypt_create(

    serf_bucket_t *stream,

    serf_ssl_context_t *ssl_context,

    serf_bucket_alloc_t *allocator);

serf_ssl_context_t *serf_bucket_ssl_encrypt_context_get(

    serf_bucket_t *bucket);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_ssl_decrypt;

#define SERF_BUCKET_IS_SSL_DECRYPT(b) SERF_BUCKET_CHECK((b), ssl_decrypt)

serf_bucket_t *serf_bucket_ssl_decrypt_create(

    serf_bucket_t *stream,

    serf_ssl_context_t *ssl_context,

    serf_bucket_alloc_t *allocator);

serf_ssl_context_t *serf_bucket_ssl_decrypt_context_get(

    serf_bucket_t *bucket);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_barrier;

#define SERF_BUCKET_IS_BARRIER(b) SERF_BUCKET_CHECK((b), barrier)

serf_bucket_t *serf_bucket_barrier_create(

    serf_bucket_t *stream,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

extern const serf_bucket_type_t serf_bucket_type_iovec;

#define SERF_BUCKET_IS_IOVEC(b) SERF_BUCKET_CHECK((b), iovec)

serf_bucket_t *serf_bucket_iovec_create(

    struct iovec vecs[],

    int len,

    serf_bucket_alloc_t *allocator);

/* ==================================================================== */

/* ### do we need a PIPE bucket type? they are simple apr_file_t objects */

#ifdef __cplusplus

}

#endif

#endif	/* !SERF_BUCKET_TYPES_H */