ABI
Tracker

(serf)



Headers diff: 1.3.10 vs current



 serf.h (1.3.10)   serf.h (current) 
skipping to change at line 33 skipping to change at line 33
/** /**
* @file serf.h * @file serf.h
* @brief Main serf header file * @brief Main serf header file
*/ */
#include <apr.h> #include <apr.h>
#include <apr_errno.h> #include <apr_errno.h>
#include <apr_allocator.h> #include <apr_allocator.h>
#include <apr_pools.h> #include <apr_pools.h>
#include <apr_hash.h>
#include <apr_network_io.h> #include <apr_network_io.h>
#include <apr_time.h> #include <apr_time.h>
#include <apr_poll.h> #include <apr_poll.h>
#include <apr_uri.h> #include <apr_uri.h>
#include <apr_version.h>
#if !APR_VERSION_AT_LEAST(1, 3, 0)
#error "The APR version must be 1.3.0 or newer"
#endif
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/* Forward declare some structures */ /* Forward declare some structures */
typedef struct serf_context_t serf_context_t; typedef struct serf_context_t serf_context_t;
typedef struct serf_bucket_t serf_bucket_t; typedef struct serf_bucket_t serf_bucket_t;
typedef struct serf_bucket_type_t serf_bucket_type_t; typedef struct serf_bucket_type_t serf_bucket_type_t;
typedef struct serf_bucket_alloc_t serf_bucket_alloc_t; typedef struct serf_bucket_alloc_t serf_bucket_alloc_t;
typedef struct serf_connection_t serf_connection_t; typedef struct serf_connection_t serf_connection_t;
typedef struct serf_listener_t serf_listener_t; typedef struct serf_listener_t serf_listener_t;
typedef struct serf_incoming_t serf_incoming_t; typedef struct serf_incoming_t serf_incoming_t;
typedef struct serf_incoming_request_t serf_incoming_request_t; typedef struct serf_incoming_request_t serf_incoming_request_t;
typedef struct serf_request_t serf_request_t; typedef struct serf_request_t serf_request_t;
typedef struct serf_config_t serf_config_t;
/** /**
* @defgroup serf high-level constructs * @defgroup serf high-level constructs
* @ingroup serf * @ingroup serf
* @{ * @{
*/ */
/** /**
* Serf-specific error codes * Serf-specific error codes
*/ */
#define SERF_ERROR_RANGE 100 #define SERF_ERROR_RANGE 100
skipping to change at line 94 skipping to change at line 101
#define SERF_ERROR_DECOMPRESSION_FAILED (SERF_ERROR_START + 4) #define SERF_ERROR_DECOMPRESSION_FAILED (SERF_ERROR_START + 4)
/* This code is for when a response received from a http server is not in /* This code is for when a response received from a http server is not in
* http-compliant syntax. */ * http-compliant syntax. */
#define SERF_ERROR_BAD_HTTP_RESPONSE (SERF_ERROR_START + 5) #define SERF_ERROR_BAD_HTTP_RESPONSE (SERF_ERROR_START + 5)
/* The server sent less data than what was announced. */ /* The server sent less data than what was announced. */
#define SERF_ERROR_TRUNCATED_HTTP_RESPONSE (SERF_ERROR_START + 6) #define SERF_ERROR_TRUNCATED_HTTP_RESPONSE (SERF_ERROR_START + 6)
/* The proxy server returned an error while setting up the SSL tunnel. */ /* The proxy server returned an error while setting up the SSL tunnel. */
#define SERF_ERROR_SSLTUNNEL_SETUP_FAILED (SERF_ERROR_START + 7) #define SERF_ERROR_SSLTUNNEL_SETUP_FAILED (SERF_ERROR_START + 7)
/* The server unexpectedly closed the connection prematurely. */ /* The server unexpectedly closed the connection prematurely. */
#define SERF_ERROR_ABORTED_CONNECTION (SERF_ERROR_START + 8) #define SERF_ERROR_ABORTED_CONNECTION (SERF_ERROR_START + 8)
/* Generic 'The line too long'. Used internally. */
#define SERF_ERROR_LINE_TOO_LONG (SERF_ERROR_START + 9)
/* The HTTP response status line too long. */
#define SERF_ERROR_STATUS_LINE_TOO_LONG (SERF_ERROR_START + 10)
/* The HTTP response header too long. */
#define SERF_ERROR_RESPONSE_HEADER_TOO_LONG (SERF_ERROR_START + 11)
/* The connection to the server timed out. */
#define SERF_ERROR_CONNECTION_TIMEDOUT (SERF_ERROR_START + 12)
/* The stream returned less data than was expected */
#define SERF_ERROR_TRUNCATED_STREAM (SERF_ERROR_START + 13)
/* The stream is empty */
#define SERF_ERROR_EMPTY_STREAM (SERF_ERROR_START + 14)
/* An empty read was returned. */
#define SERF_ERROR_EMPTY_READ (SERF_ERROR_START + 15)
/* Http-2 stream errors, mapped into our error range */
#define SERF_ERROR_HTTP2_NO_ERROR (SERF_ERROR_START + 50)
#define SERF_ERROR_HTTP2_PROTOCOL_ERROR (SERF_ERROR_START + 51)
#define SERF_ERROR_HTTP2_INTERNAL_ERROR (SERF_ERROR_START + 52)
#define SERF_ERROR_HTTP2_FLOW_CONTROL_ERROR (SERF_ERROR_START + 53)
#define SERF_ERROR_HTTP2_SETTINGS_TIMEOUT (SERF_ERROR_START + 54)
#define SERF_ERROR_HTTP2_STREAM_CLOSED (SERF_ERROR_START + 55)
#define SERF_ERROR_HTTP2_FRAME_SIZE_ERROR (SERF_ERROR_START + 56)
#define SERF_ERROR_HTTP2_REFUSED_STREAM (SERF_ERROR_START + 57)
#define SERF_ERROR_HTTP2_CANCEL (SERF_ERROR_START + 58)
#define SERF_ERROR_HTTP2_COMPRESSION_ERROR (SERF_ERROR_START + 59)
#define SERF_ERROR_HTTP2_CONNECT_ERROR (SERF_ERROR_START + 60)
#define SERF_ERROR_HTTP2_ENHANCE_YOUR_CALM (SERF_ERROR_START + 61)
#define SERF_ERROR_HTTP2_INADEQUATE_SECURITY (SERF_ERROR_START + 62)
#define SERF_ERROR_HTTP2_HTTP_1_1_REQUIRED (SERF_ERROR_START + 63)
/* SSL certificates related errors */ /* SSL certificates related errors */
#define SERF_ERROR_SSL_CERT_FAILED (SERF_ERROR_START + 70) #define SERF_ERROR_SSL_CERT_FAILED (SERF_ERROR_START + 70)
/* SSL communications related errors */ /* SSL communications related errors */
#define SERF_ERROR_SSL_COMM_FAILED (SERF_ERROR_START + 71) #define SERF_ERROR_SSL_COMM_FAILED (SERF_ERROR_START + 71)
/* SSL handshake failed */
#define SERF_ERROR_SSL_SETUP_FAILED (SERF_ERROR_START + 72)
/* Serf-internal error code, raised when the server initiates SSL renegotia
tion
on a connection that uses HTTP pipelining. */
#define SERF_ERROR_SSL_NEGOTIATE_IN_PROGRESS (SERF_ERROR_START + 73)
/* OCSP responder says that the certificate is revoked. */
#define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED (SERF_ERROR_START + 74)
/* OCSP responder says that the certificate is unknown. */
#define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN (SERF_ERROR_START + 75)
/* The response from an OCSP responder was not valid. */
#define SERF_ERROR_SSL_OCSP_RESPONSE_INVALID (SERF_ERROR_START + 76)
#define SERF_OCSP_UNGOOD_ERROR(status) ((status) \
&& ((SERF_ERROR_SSL_OCSP_CERT_REVOKED == (status)) \
||(SERF_ERROR_SSL_OCSP_CERT_UNKNOWN == (status))))
/* General authentication related errors */ /* General authentication related errors */
#define SERF_ERROR_AUTHN_FAILED (SERF_ERROR_START + 90) #define SERF_ERROR_AUTHN_FAILED (SERF_ERROR_START + 90)
/* None of the available authn mechanisms for the request are supported */ /* None of the available authn mechanisms for the request are supported */
#define SERF_ERROR_AUTHN_NOT_SUPPORTED (SERF_ERROR_START + 91) #define SERF_ERROR_AUTHN_NOT_SUPPORTED (SERF_ERROR_START + 91)
/* Authn was requested by the server but the header lacked some attribute */ /* Authn was requested by the server but the header lacked some attribute */
#define SERF_ERROR_AUTHN_MISSING_ATTRIBUTE (SERF_ERROR_START + 92) #define SERF_ERROR_AUTHN_MISSING_ATTRIBUTE (SERF_ERROR_START + 92)
/* Authentication handler initialization related errors */ /* Authentication handler initialization related errors */
#define SERF_ERROR_AUTHN_INITALIZATION_FAILED (SERF_ERROR_START + 93) #define SERF_ERROR_AUTHN_INITALIZATION_FAILED (SERF_ERROR_START + 93)
/* The user credentials were rejected by the server */
#define SERF_ERROR_AUTHN_CREDENTIALS_REJECTED (SERF_ERROR_START + 94)
/* Error code reserved for use in the test suite. */ /* Error code reserved for use in the test suite. */
#define SERF_ERROR_ISSUE_IN_TESTSUITE (SERF_ERROR_START + 99) #define SERF_ERROR_ISSUE_IN_TESTSUITE (SERF_ERROR_START + 99)
/* This macro groups errors potentially raised when reading a http response . */ /* This macro groups errors potentially raised when reading a http response . */
#define SERF_BAD_RESPONSE_ERROR(status) ((status) \ #define SERF_BAD_RESPONSE_ERROR(status) ((status) \
&& ((SERF_ERROR_DECOMPRESSION_FAILED == (status)) \ && ((SERF_ERROR_DECOMPRESSION_FAILED == (status)) \
||(SERF_ERROR_BAD_HTTP_RESPONSE == (status)) \ ||(SERF_ERROR_BAD_HTTP_RESPONSE == (status)) \
||(SERF_ERROR_TRUNCATED_HTTP_RESPONSE == (status)))) ||(SERF_ERROR_TRUNCATED_HTTP_RESPONSE == (status))))
/** /**
* Return a string that describes the specified error code. * Return a string that describes the specified error code.
* *
* If the error code is not one of the above Serf error codes, then * If the error code is not one of the above Serf error codes, then
* NULL will be returned. * NULL will be returned.
* *
* Note regarding lifetime: the string is a statically-allocated constant * Note regarding lifetime: the string is a statically-allocated constant
*/ */
const char *serf_error_string(apr_status_t errcode); const char *serf_error_string(apr_status_t errcode);
/** /**
* The source of an error callback invocation.
*
* @since New in 1.5.
*/
/* Bit masks for error sources. */
#define SERF_ERROR_CB_MASK 0x00ff
#define SERF_ERROR_CB_GLOBAL 0x0001
#define SERF_ERROR_CB_CONTEXT 0x0002
#define SERF_ERROR_CB_OUTGOING 0x0004
#define SERF_ERROR_CB_INCOMING 0x0008
#define SERF_ERROR_CB_REQUEST 0x0010
#define SERF_ERROR_CB_RESPONSE 0x0020
/* The following flag can be bitwise-combined with any of the above
values to indicate that the message originated an SSL context. */
#define SERF_ERROR_CB_SSL_CONTEXT 0x0100
/**
* A callback that, when set, will be called for out-of-band error reportin
g.
*
* A callback can be set on any of three levels: globally, for the context,
or
* the outgoing or incoming connection. Incoming and outgoing requests and
* responses do not have their own error handlers, but indicate with the so
urce
* flags where the message originated. The default implementations will wil
l
* send messages up this hierarchy until a custom callback is found, or the
* default global callback drops the message to the floor. This is the erro
r
* callback hierarchy:
* ```
* Level Registration function
*
* Global serf_error_callback_set()
* Context serf_context_error_callback_set()
* Connection serf_connection_error_callback_set()
* Incoming serf_incoming_error_callback_set()
* ```
* In addition, any of those handlers can be called from within an SSL
* processing context, which is indicated by the flag on the message source
.
*
* The @a baton is the object provided to the callback registration, and
* @a source is one of the @c SERF_ERROR_CB_* values, above.
*
* The @a message lasts only as long as the callback invocation. The caller
* must make a copy of the message it it wants to keep it for longer.
*
* It is possible that for a given error multiple strings will be returned
* in multiple callbacks. The caller may choose to handle all strings, or
* may choose to ignore all strings but the last most detailed one.
*
* @since New in 1.5.
*/
typedef apr_status_t (*serf_error_cb_t)(
void *baton,
unsigned source,
apr_status_t status,
const char *message);
/**
* Register the global error @a callback, replacing any previous version.
*
* @note This function is NOT thread-safe, and calls to the callback are no
t
* serialized. Users are responsible for making the registration and
* the callback implementation safe for their application.
*
* @since New in 1.5.
*/
void serf_global_error_callback_set(
serf_error_cb_t callback,
void *baton);
/**
* Register the context-specific error callback.
*
* Like serf_error_callback_set() except that it affects the given
* context @a ctx and, since contexts may not be accessed from multiple
* threads, serialization is not a concern.
*
* The lifetime of @a baton must be longer than the lifetime of the context
.
*
* @since New in 1.5.
*/
void serf_context_error_callback_set(
serf_context_t *ctx,
serf_error_cb_t callback,
void *baton);
/**
* Register the connection-specific error callback.
*
* Like serf_context_error_callback_set() but for connections.
*
* The lifetime of @a baton must be longer than the lifetime of the connect
ion.
*
* @since New in 1.5.
*/
void serf_connection_error_callback_set(
serf_connection_t *conn,
serf_error_cb_t callback,
void *baton);
/**
* Register the incoming-connection-specific error callback.
*
* Like serf_context_error_callback_set() but for incoming connections.
*
* The lifetime of @a baton must be longer than the lifetime of the
* incoming connection.
*
* @since New in 1.5.
*/
void serf_incoming_error_callback_set(
serf_incoming_t *client,
serf_error_cb_t callback,
void *baton);
/**
* Create a new context for serf operations. * Create a new context for serf operations.
* *
* A serf context defines a control loop which processes multiple * A serf context defines a control loop which processes multiple
* connections simultaneously. * connections simultaneously.
* *
* The context will be allocated within @a pool. * The context will be allocated within @a pool.
*/ */
serf_context_t *serf_context_create( serf_context_t *serf_context_create(
apr_pool_t *pool); apr_pool_t *pool);
skipping to change at line 163 skipping to change at line 338
/** /**
* Callback function. Remove the socket, identified by both @a pfd and * Callback function. Remove the socket, identified by both @a pfd and
* @a serf_baton from the externally managed poll set. * @a serf_baton from the externally managed poll set.
*/ */
typedef apr_status_t (*serf_socket_remove_t)( typedef apr_status_t (*serf_socket_remove_t)(
void *user_baton, void *user_baton,
apr_pollfd_t *pfd, apr_pollfd_t *pfd,
void *serf_baton); void *serf_baton);
/* Create a new context for serf operations. /**
* Create a new context for serf operations.
* *
* Use this function to make serf not use its internal control loop, but * Use this function to make serf not use its internal control loop, but
* instead rely on an external event loop. Serf will use the @a addf and @a rmf * instead rely on an external event loop. Serf will use the @a addf and @a rmf
* callbacks to notify of any event on a connection. The @a user_baton will be * callbacks to notify of any event on a connection. The @a user_baton will be
* passed through the addf and rmf callbacks. * passed through the addf and rmf callbacks.
* *
* The context will be allocated within @a pool. * The context will be allocated within @a pool.
*/ */
serf_context_t *serf_context_create_ex( serf_context_t *serf_context_create_ex(
void *user_baton, void *user_baton,
skipping to change at line 334 skipping to change at line 510
* *
* All temporary allocations should be made in @a pool. * All temporary allocations should be made in @a pool.
*/ */
typedef void (*serf_connection_closed_t)( typedef void (*serf_connection_closed_t)(
serf_connection_t *conn, serf_connection_t *conn,
void *closed_baton, void *closed_baton,
apr_status_t why, apr_status_t why,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Like serf_connection_closed_t, but applies to incoming connections.
*
* @since New in 1.5.
*/
typedef apr_status_t (*serf_incoming_closed_t)(
serf_incoming_t *incoming,
void *closed_baton,
apr_status_t why,
apr_pool_t *pool);
/**
* Response data has arrived and should be processed. * Response data has arrived and should be processed.
* *
* Whenever response data for @a request arrives (initially, or continued d ata * Whenever response data for @a request arrives (initially, or continued d ata
* arrival), this handler is invoked. The response data is available in the * arrival), this handler is invoked. The response data is available in the
* @a response bucket. The @a handler_baton is passed along from the baton * @a response bucket. The @a handler_baton is passed along from the baton
* provided by the request setup callback (@see serf_request_setup_t). * provided by the request setup callback (@see serf_request_setup_t).
* *
* The handler MUST process data from the @a response bucket until the * The handler MUST process data from the @a response bucket until the
* bucket's read function states it would block (see APR_STATUS_IS_EAGAIN). * bucket's read function states it would block (see APR_STATUS_IS_EAGAIN).
* The handler is invoked only when new data arrives. If no further data * The handler is invoked only when new data arrives. If no further data
skipping to change at line 372 skipping to change at line 559
serf_request_t *request, serf_request_t *request,
serf_bucket_t *response, serf_bucket_t *response,
void *handler_baton, void *handler_baton,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Callback function to be implemented by the application, so that serf * Callback function to be implemented by the application, so that serf
* can handle server and proxy authentication. * can handle server and proxy authentication.
* code = 401 (server) or 407 (proxy). * code = 401 (server) or 407 (proxy).
* baton = the baton passed to serf_context_run. * baton = the baton passed to serf_context_run.
* authn_type = one of "Basic", "Digest". * authn_type = one of "Basic", "Digest", or the name of a user-defined
* authentication scheme if it uses this callback.
*
* @see SERF_AUTHN_CODE_HOST
* @see SERF_AUTHN_CODE_PROXY
*/ */
typedef apr_status_t (*serf_credentials_callback_t)( typedef apr_status_t (*serf_credentials_callback_t)(
char **username, char **username,
char **password, char **password,
serf_request_t *request, void *baton, serf_request_t *request, void *baton,
int code, const char *authn_type, int code, const char *authn_type,
const char *realm, const char *realm,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Create a new connection associated with the @a ctx serf context. * Create a new connection associated with the @a ctx serf context.
* *
* If no proxy server is configured, a connection will be created to * If no proxy server is configured, a connection will be created to
* (eventually) connect to the address specified by @a address. The address must * (eventually) connect to the address specified by @a address. The address must
* live at least as long as @a pool (thus, as long as the connection object ). * live at least as long as @a pool (thus, as long as the connection object ).
* If a proxy server is configured, @address will be ignored. * If a proxy server is configured, @a address will be ignored.
* *
* The connection object will be allocated within @a pool. Clearing or * The connection object will be allocated within @a pool. Clearing or
* destroying this pool will close the connection, and terminate any * destroying this pool will close the connection, and terminate any
* outstanding requests or responses. * outstanding requests or responses.
* *
* The @a setup callback will be invoked, and @a setup_baton passed to it,
* once the connection is actually established. @see serf_connection_setup_
t.
*
* When the connection is closed (upon request or because of an error), * When the connection is closed (upon request or because of an error),
* then the @a closed callback is invoked, and @a closed_baton is passed. * then the @a closed callback is invoked, and @a closed_baton is passed.
* *
* ### doc on setup(_baton). tweak below comment re: acceptor. * NULL may be passed for @a setup and @a closed; default implementations
* NULL may be passed for @a acceptor and @a closed; default implementation
s
* will be used. * will be used.
* *
* Note: the connection is not made immediately. It will be opened on * @note the connection is not made immediately. It will be opened
* the next call to @see serf_context_run. * asynchronously on the next call to serf_context_run().
*/ */
serf_connection_t *serf_connection_create( serf_connection_t *serf_connection_create(
serf_context_t *ctx, serf_context_t *ctx,
apr_sockaddr_t *address, apr_sockaddr_t *address,
serf_connection_setup_t setup, serf_connection_setup_t setup,
void *setup_baton, void *setup_baton,
serf_connection_closed_t closed, serf_connection_closed_t closed,
void *closed_baton, void *closed_baton,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Create a new connection associated with the @a ctx serf context. * Create a new connection associated with the @a ctx serf context.
* *
* A connection will be created to (eventually) connect to the address * A connection will be created to (eventually) connect to the address
* specified by @a address. The address must live at least as long as * specified by @a host_info (either directly or through a proxy), which
* @a pool (thus, as long as the connection object). * must live at least as long as @a pool (thus, as long as the connection
* * object). The @a host_info will also be used for setting request headers.
* The host address will be looked up based on the hostname in @a host_info
.
* *
* The connection object will be allocated within @a pool. Clearing or * The connection object will be allocated within @a pool. Clearing or
* destroying this pool will close the connection, and terminate any * destroying this pool will close the connection, and terminate any
* outstanding requests or responses. * outstanding requests or responses.
* *
* The @a setup callback will be invoked, and @a setup_baton passed to it,
* once the connection is actually established. @see serf_connection_setup_
t.
*
* When the connection is closed (upon request or because of an error), * When the connection is closed (upon request or because of an error),
* then the @a closed callback is invoked, and @a closed_baton is passed. * then the @a closed callback is invoked, and @a closed_baton is passed.
* *
* ### doc on setup(_baton). tweak below comment re: acceptor. * NULL may be passed for @a setup and @a closed; default implementations
* NULL may be passed for @a acceptor and @a closed; default implementation
s
* will be used. * will be used.
* *
* Note: the connection is not made immediately. It will be opened on * @note The connection is not made immediately. It will be opened
* the next call to @see serf_context_run. * asynchronously on the next call to serf_context_run().
*/ */
apr_status_t serf_connection_create2( apr_status_t serf_connection_create2(
serf_connection_t **conn, serf_connection_t **conn,
serf_context_t *ctx, serf_context_t *ctx,
apr_uri_t host_info, apr_uri_t host_info,
serf_connection_setup_t setup, serf_connection_setup_t setup,
void *setup_baton, void *setup_baton,
serf_connection_closed_t closed, serf_connection_closed_t closed,
void *closed_baton, void *closed_baton,
apr_pool_t *pool); apr_pool_t *pool);
/**
* Notification callback when an address has been resolved.
*
* The @a ctx and @a resolved_baton arguments are the same that were passed
* to serf_address_resolve_async().
*
* @a status contains the result of the address resolution. If it is not
* @c APR_SUCCESS, then @a host_address is invalid and should be ignored.
*
* The resolved @a host_address is ephemeral, allocated in @a pool and live
s
* only for the duration of the callback. If it is not consumed, it should
be
* copied to a more permanent pool, using for example apr_sockaddr_info_cop
y().
*
* All temporary allocations should be made in @a pool.
*
* @since New in 1.5.
*/
typedef void (*serf_address_resolved_t)(
serf_context_t *ctx,
void *resolved_baton,
apr_sockaddr_t *host_address,
apr_status_t status,
apr_pool_t *pool);
/**
* Asynchronously resolve an address.
*
* The address represented by @a host_info is intended to be used to create
* new connections in @a ctx; see, for example, serf_connection_create().
* However, unlike in the connection creation functions, the address will b
e
* resolved regardless of proxy configuration. In order to avoid unnecessar
y
* address resolution, use serf_connection_create_async(), which does take
* proxy configuration into account.
*
* The @a resolved callback will be called during a subsequent call to
* serf_context_run() or serf_context_prerun() and will receive the same
* @a ctx and @a resolved_baton that are provided here.
*
* The lifetime of all function arguments except @a pool must extend until
* either @a resolved is called or an error is reported.
*
* All temporary allocations should be made in @a pool.
*
* @since New in 1.5.
*/
apr_status_t serf_address_resolve_async(
serf_context_t *ctx,
apr_uri_t host_info,
serf_address_resolved_t resolved,
void *resolved_baton,
apr_pool_t *pool);
/**
* Notification callback when a connection has been created.
*
* The @a ctx and @a created_baton arguments are the same that were passed
* to serf_connection_create_async().
*
* @a status contains the result of the connection creation. If it is not
* @c APR_SUCCESS, then @a conn is invalid and should be ignored.
*
* The created @a conn is allocated in the pool that was passed to
* serf_connection_create_async(); this is @b not the same as @a pool.
*
* All temporary allocations should be made in @a pool.
*
* @since New in 1.5.
*/
typedef void (*serf_connection_created_t)(
serf_context_t *ctx,
void *created_baton,
serf_connection_t *conn,
apr_status_t status,
apr_pool_t *pool);
/**
* Asynchronously create a new connection associated with
* the @a ctx serf context.
*
* Like serf_connection_create2() except that address resolution is perform
ed
* asynchronously, similarly to serf_address_resolve_async(). Address resol
ution
* will be skipped if a proxy is configured; in this case, the function bec
omes
* synchronous and effectively equivalent to serf_connection_create2().
*
* The @a created callback with @a created_baton is called when the connect
ion
* is created but before it is opened. Note that depending on the configura
tion
* of @a ctx and @a host_info, the connection may be created and this callb
ack
* be invoked synchronously during the scope of this function call.
*
* @since New in 1.5.
*/
apr_status_t serf_connection_create_async(
serf_context_t *ctx,
apr_uri_t host_info,
serf_connection_created_t created,
void *created_baton,
serf_connection_setup_t setup,
void *setup_baton,
serf_connection_closed_t closed,
void *closed_baton,
apr_pool_t *pool);
typedef apr_status_t (*serf_accept_client_t)( typedef apr_status_t (*serf_accept_client_t)(
serf_context_t *ctx, serf_context_t *ctx,
serf_listener_t *l, serf_listener_t *l,
void *accept_baton, void *accept_baton,
apr_socket_t *insock, apr_socket_t *insock,
apr_pool_t *pool); apr_pool_t *pool);
apr_status_t serf_listener_create( apr_status_t serf_listener_create(
serf_listener_t **listener, serf_listener_t **listener,
serf_context_t *ctx, serf_context_t *ctx,
const char *host, const char *host,
apr_uint16_t port, apr_uint16_t port,
void *accept_baton, void *accept_baton,
serf_accept_client_t accept_func, serf_accept_client_t accept_func,
apr_pool_t *pool); apr_pool_t *pool);
typedef apr_status_t (*serf_incoming_request_cb_t)( typedef apr_status_t (*serf_incoming_request_handler_t)(
serf_context_t *ctx, serf_incoming_request_t *req,
serf_bucket_t *request,
void *handler_baton,
apr_pool_t *pool);
typedef apr_status_t (*serf_incoming_response_setup_t)(
serf_bucket_t **resp_bkt,
serf_incoming_request_t *req,
void *setup_baton,
serf_bucket_alloc_t *allocator,
apr_pool_t *pool);
typedef apr_status_t (*serf_incoming_request_setup_t)(
serf_bucket_t **req_bkt,
serf_bucket_t *stream,
serf_incoming_request_t *req, serf_incoming_request_t *req,
void *request_baton, void *request_baton,
serf_incoming_request_handler_t *handler,
void **handler_baton,
serf_incoming_response_setup_t *response_setup,
void **response_setup_baton,
apr_pool_t *pool); apr_pool_t *pool);
/* ### Deprecated: can't do anything with request */
typedef apr_status_t(*serf_incoming_request_cb_t)(
serf_context_t *ctx,
serf_incoming_request_t *req,
void *request_baton,
apr_pool_t *pool);
/* ### Deprecated: Misses ssl support and actual
request handling. */
apr_status_t serf_incoming_create( apr_status_t serf_incoming_create(
serf_incoming_t **client, serf_incoming_t **client,
serf_context_t *ctx, serf_context_t *ctx,
apr_socket_t *insock, apr_socket_t *insock,
void *request_baton, void *request_baton,
serf_incoming_request_cb_t request, serf_incoming_request_cb_t request,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Creates a new client associated with @a ctx for socket @a insock. The cl
ient
* takes responsibility for @a client_pool and will destroy it after the
* connection is closed. Typically this would be the same pool as where the
* incoming socket @a insock is allocated in.
*
* This non-standard behavior is needed to support listeners inside the sam
e
* @a ctx instance without leaking memory for each used connections. Caller
s
* might want to create a specific client pool if they use a non-standard
* listening pattern.
*
* Once the connection is setup @a setup will be called with @a setup_baton
* to setup the connection's bucket support.
*
* When the connection closed @a closed will be called with @a closed_baton
to
* notify that the client and its pool are about to be destroyed.
*
* Once the connection is fully setup incoming requests will be routed to @
a
* req_setup with @a req_setup_baton, to handle processing.
*
* @since New in 1.5.
*/
apr_status_t serf_incoming_create2(
serf_incoming_t **client,
serf_context_t *ctx,
apr_socket_t *insock,
serf_connection_setup_t setup,
void *setup_baton,
serf_incoming_closed_t closed,
void *closed_baton,
serf_incoming_request_setup_t req_setup,
void *req_setup_baton,
apr_pool_t *client_pool);
/**
* Allows creating a response before the request is completely
* read. Will call the response create function if it hasn't
* been called yet.
*
* @since New in 1.5.
*/
apr_status_t serf_incoming_response_create(
serf_incoming_request_t *request);
/**
* Reset the connection, but re-open the socket again. * Reset the connection, but re-open the socket again.
*/ */
apr_status_t serf_connection_reset( apr_status_t serf_connection_reset(
serf_connection_t *conn); serf_connection_t *conn);
/** /**
* Close the connection associated with @a conn and cancel all pending requ ests. * Close the connection associated with @a conn and cancel all pending requ ests.
* *
* The closed callback passed to serf_connection_create() will be invoked * The closed callback passed to serf_connection_create() will be invoked
* with APR_SUCCESS. * with APR_SUCCESS.
skipping to change at line 510 skipping to change at line 877
serf_connection_t *conn, serf_connection_t *conn,
unsigned int max_requests); unsigned int max_requests);
void serf_connection_set_async_responses( void serf_connection_set_async_responses(
serf_connection_t *conn, serf_connection_t *conn,
serf_response_acceptor_t acceptor, serf_response_acceptor_t acceptor,
void *acceptor_baton, void *acceptor_baton,
serf_response_handler_t handler, serf_response_handler_t handler,
void *handler_baton); void *handler_baton);
typedef enum serf_connection_framing_type_t {
SERF_CONNECTION_FRAMING_TYPE_NONE = 0,
SERF_CONNECTION_FRAMING_TYPE_HTTP1,
SERF_CONNECTION_FRAMING_TYPE_HTTP2,
SERF_CONNECTION_FRAMING_TYPE_FCGI
} serf_connection_framing_type_t;
/**
* Sets the connection framing on the connection to the specified type. The
* NONE type specifies that the framing type is undetermined yet and no
* requests should be written to the connection until the framing type is
* set. Connections default to HTTP1 framing.
*
* @since New in 1.5.
*/
void serf_connection_set_framing_type(
serf_connection_t *conn,
serf_connection_framing_type_t framing_type);
/**
* @since New in 1.5.
*/
void serf_incoming_set_framing_type(
serf_incoming_t *client,
serf_connection_framing_type_t framing_type);
/** /**
* Setup the @a request for delivery on its connection. * Setup the @a request for delivery on its connection.
* *
* Right before this is invoked, @a pool will be built within the * Right before this is invoked, @a pool will be built within the
* connection's pool for the request to use. The associated response will * connection's pool for the request to use. The associated response will
* be allocated within that subpool. An associated bucket allocator will * be allocated within that subpool. An associated bucket allocator will
* be built. These items may be fetched from the request object through * be built. These items may be fetched from the request object through
* @see serf_request_get_pool or @see serf_request_get_alloc. * @see serf_request_get_pool or @see serf_request_get_alloc.
* *
* The content of the request is specified by the @a req_bkt bucket. When * The content of the request is specified by the @a req_bkt bucket. When
skipping to change at line 574 skipping to change at line 967
* with @see serf_request_cancel. * with @see serf_request_cancel.
* *
* Invoking any calls other than @see serf_request_cancel before the setup * Invoking any calls other than @see serf_request_cancel before the setup
* callback executes is not supported. * callback executes is not supported.
*/ */
serf_request_t *serf_connection_priority_request_create( serf_request_t *serf_connection_priority_request_create(
serf_connection_t *conn, serf_connection_t *conn,
serf_request_setup_t setup, serf_request_setup_t setup,
void *setup_baton); void *setup_baton);
/** Returns detected network latency for the @a conn connection. Negative /**
* value means that latency is unknwon. * The default request priority
*
* @since New in 1.5.
*/
#define SERF_REQUEST_PRIORITY_DEFAULT 0x1000
/**
* Updates the request's priority information. Some protocol implementation
s,
* such as HTTP/2 may use this information for response scheduling. The
* actual behavior depends on the server, intermediate proxies and of cours
e
* the protocol implementation.
*
* It is recommended to prioritize a request before sending it to the serve
r,
* as that avoids race conditions and receiving unwanted results.
*
* If @a depends_on is set, then the request is marked as dependent on
* @a depends_on, and the result of @a request will only be received if
* no progress can be made on @a depends_on itself.
*
* @a priority is used to relatively prioritize multiple dependencies on th
e
* same target. Passing 0 will keep the original priority. In case of HTTP/
2
* this value is mapped to a 8 bit value by ignoring the lowest 8 bits.
*
* By default a request is created at priority SERF_REQUEST_PRIORITY_DEFAUL
T.
*
* If @a exclusive is set to TRUE, then all existing dependencies on @a
* depends_on will be updated to now depend on @a request, to make @a
* request the only dependency of @a request. When FALSE, request will just
* be added as a dependency.
*
* @since New in 1.5.
*/
void serf_connection_request_prioritize(serf_request_t *request,
serf_request_t *depends_on,
apr_uint16_t priority,
int exclusive);
/**
* Returns detected network latency for the @a conn connection. Negative
* value means that latency is unknown.
*/ */
apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn); apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn);
/** Check if a @a request has been completely written. /**
* Returns the number of requests waiting to be sent over connection CONN.
*
* @since New in 1.5.
*/
unsigned int serf_connection_queued_requests(serf_connection_t *conn);
/**
* Returns the total number of requests for which a response hasn't been
* received yet on connection CONN. This includes requests:
* - that are queued but not sent.
* - that have been sent but no response has been completely received yet.
*
* @since New in 1.5.
*/
unsigned int serf_connection_pending_requests(serf_connection_t *conn);
/**
* Check if a @a request has been completely written.
* *
* Returns APR_SUCCESS if the request was written completely on the connect ion. * Returns APR_SUCCESS if the request was written completely on the connect ion.
* Returns APR_EBUSY if the request is not yet or partially written. * Returns APR_EBUSY if the request is not yet or partially written.
*/ */
apr_status_t serf_request_is_written( apr_status_t serf_request_is_written(
serf_request_t *request); serf_request_t *request);
/** /**
* Cancel the request specified by the @a request object. * Cancel the request specified by the @a request object.
* *
skipping to change at line 646 skipping to change at line 1096
* with the @a ctx serf context. * with the @a ctx serf context.
* *
* The next connection will be created to connect to the proxy server * The next connection will be created to connect to the proxy server
* specified by @a address. The address must live at least as long as the * specified by @a address. The address must live at least as long as the
* serf context. * serf context.
*/ */
void serf_config_proxy( void serf_config_proxy(
serf_context_t *ctx, serf_context_t *ctx,
apr_sockaddr_t *address); apr_sockaddr_t *address);
/* Supported authentication types. */
#define SERF_AUTHN_NONE 0x00
#define SERF_AUTHN_BASIC 0x01
#define SERF_AUTHN_DIGEST 0x02
#define SERF_AUTHN_NTLM 0x04
#define SERF_AUTHN_NEGOTIATE 0x08
#define SERF_AUTHN_ALL 0xFF
/** /**
* Define the authentication handlers that serf will try on incoming reques ts. * Define the authentication handlers that serf will try on incoming reques ts.
*
* @see @c SERF_AUTHN_ALL etc.
*/ */
void serf_config_authn_types( void serf_config_authn_types(
serf_context_t *ctx, serf_context_t *ctx,
int authn_types); int authn_types);
/** /**
* Set the credentials callback handler. * Set the credentials callback handler.
*/ */
void serf_config_credentials_callback( void serf_config_credentials_callback(
serf_context_t *ctx, serf_context_t *ctx,
skipping to change at line 689 skipping to change at line 1133
apr_socket_t *skt, apr_socket_t *skt,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/** /**
* Create a bucket of type 'request bucket'. * Create a bucket of type 'request bucket'.
* This is basically a wrapper around @a serf_bucket_request_create, which * This is basically a wrapper around @a serf_bucket_request_create, which
* initializes the bucket using request, connection and/or context specific * initializes the bucket using request, connection and/or context specific
* settings. * settings.
* *
* This function will set following header(s): * This function will set following header(s):
* - Host: if the connection was created with @a serf_connection_create2. * - Host: if the connection was created serf_connection_create2()
* or serf_connection_create_async()
*/ */
serf_bucket_t *serf_request_bucket_request_create( serf_bucket_t *serf_request_bucket_request_create(
serf_request_t *request, serf_request_t *request,
const char *method, const char *method,
const char *uri, const char *uri,
serf_bucket_t *body, serf_bucket_t *body,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/** @} */ /** @} */
/** /**
* @defgroup serf authentication
* @ingroup serf
* @{
*
* Interaction during authentication handshake for user-defined schemes:
* ```
* scheme serf peer
* | | |
* | +------> request ------->+
* | | |
* | +<---- authenticate <----+ (401 or 407)
* +<------ init-conn <------+ |
* | | |
* | (pipelining off) <--+ (optional) |
* | (get credentials) <--+ (optional) |
* | | |
* +<-------- handle <-------+ |
* | | |
* | (reset pipelining) <--+ (optional) |
* | | |
* +<---- setup-requiest <---+ |
* | | |
* | (reset pipelining) <--+ (optional) |
* | +---> request + authn -->+
* | | |
* | +<------ response <------+
* +<-- validate-response <--+ |
* | | |
* | (reset pipelining) <--+ (optional) |
* | | |
* ```
*/
/* Supported authentication types. */
#define SERF_AUTHN_NONE 0x00 /**< Authentication type: None */
#define SERF_AUTHN_BASIC 0x01 /**< Authentication type: Basic */
#define SERF_AUTHN_DIGEST 0x02 /**< Authentication type: Digest */
#define SERF_AUTHN_NTLM 0x04 /**< Authentication type: NTLM */
#define SERF_AUTHN_NEGOTIATE 0x08 /**< Authentication type: Negotiate */
#define SERF_AUTHN_ALL ~0x00 /**< All authentication types */
/* For user-defined authentication callbacks: these the sources of an
authentication callback. */
#define SERF_AUTHN_CODE_HOST 401 /**< Authentication request from a host *
/
#define SERF_AUTHN_CODE_PROXY 407 /**< Authentication requset from a proxy
*/
/* Flags returned from the init-connection callback. */
#define SERF_AUTHN_FLAG_NONE 0x00 /**< Authn flags: None */
#define SERF_AUTHN_FLAG_PIPE 0x01 /**< Authn flags: Allow pipelining */
#define SERF_AUTHN_FLAG_CREDS 0x02 /**< Authn flags: Require credentials */
/**
* Callback for user-defined authentication scheme providers.
*
* Called to initialize the connection for this authentication scheme. Retu
rn
* the connection-specific @a authn_baton allocated from @a result_pool, th
at
* will be passed to the other callbacks when called for the same connectio
n.
*
* @a baton is the user data pointer passed to serf_authn_register_scheme()
.
*
* @a code is the HTTP status code from the response that caused the call t
o
* this callback; either @c SERF_AUTHN_CODE_HOST when the peer is a server,
or
* @c SERF_AUTHN_CODE_PROXY when proxy authentication is required.
*
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
typedef apr_status_t
(*serf_authn_init_conn_func_t)(void **authn_baton,
void *baton, int code,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Callback for user-defined authentication scheme providers.
*
* Return a unique identifier of the server (or service) in @a realm_name,
* allocated from @a result_pool.
*
* @a baton is the user data pointer passed to serf_authn_register_scheme()
.
*
* @a authn_baton is the pointer returned from the init-connection callback
.
*
* @a authn_header and @a authn_parameters come from the authentication hea
der
* (WWW-Authenticate or Proxy-Authenticate) recevied in a server response.
*
* @a authn_header is the header value, i.e., "scheme <parameters>";
*
* @a authn_parameters is a dictionary of the authentication parameters
* and their values, e.g., `realm="Wonderland"`. The keys are always folded
* to lower case. If the parameter is a single token, it is returned in the
* dictionary as the value of the empty string key ("").
* @see https://www.rfc-editor.org/rfc/rfc9110.html#section-11.2
*
* If the scheme flag @a SERF_AUTHN_FLAG_PIPE is *not* set, pipelining will
be
* disabled on the connection after this callback succeeds.
*
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
typedef apr_status_t
(*serf_authn_get_realm_func_t)(const char **realm_name,
void *baton,
void *authn_baton,
const char *authn_header,
apr_hash_t *authn_parameters,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Callback for user-defined authentication scheme providers.
*
* Called after the init-conn function has succeeded to prepare (cache) the
* credentials for this connection, usually in @a auth_baton.
*
* @a baton, @a authn_baton, @a authn_header and @a authn_parameters have t
he
* same meaning as in the get-realm function; @a code is the same as in the
* init-conn function.
*
* @a response_header is either "Authorization" or "Proxy-Authorization",
* depending on the type of the peer for the authentication handshake.
*
* @a username and @a password are optional (may ba null), provided by the
* credentials callback, which is called automatically if the scheme flag
* @c SERF_AUTHN_FLAG_CREDS is set.
*
* @a request is the pending request and @a response is the response that
* caused this callback to be called.
*
* If the scheme flag @c SERF_AUTHN_FLAG_PIPE is *not* set, return a boolea
n
* value in @a reset_pipelining to indicate whether pipelining on @a conn
* should be restored to the value before the init-conn callback was invoke
d.
* The value of this flag is set to @c false by the caller, so the
* implementation does not have to modify it if the pipelining state should
* remain unchanged. This parameter has the same meaning in the
* serf_authn_setup_request_func_t and serf_authn_validate_response_func_t
* callbacks and will only take effect the first time its value @c true.
*
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
typedef apr_status_t
(*serf_authn_handle_func_t)(int *reset_pipelining,
void *baton,
void *authn_baton,
int code,
const char *authn_header,
apr_hash_t *authn_parameters,
const char *response_header,
const char *username,
const char *password,
serf_request_t *request,
serf_bucket_t *response,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Callback for user-defined authentication scheme providers.
*
* Called every time a new authenticated @a request is being prepared for t
he
* connection @a conn, in order to add credentials etc. to the request.
*
* @a baton and @a authn_baton are the same as in the handle function.
*
* @a method and @a uri are the requests attributes and @a headers are the
* request headers where the credentials are usually set.
*
* For the meaning of @a reset_pipelining, see serf_authn_handle_func_t.
*
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
typedef apr_status_t
(*serf_authn_setup_request_func_t)(int *reset_pipelining,
void *baton,
void *authn_baton,
serf_connection_t *conn,
serf_request_t *request,
const char *method,
const char *uri,
serf_bucket_t *headers,
apr_pool_t *scratch_pool);
/**
* Callback for user-defined authentication scheme providers.
*
* Called every time a @a response with status @a code to the authenticated
@a
* request is received from the connection @a conn.
*
* @a baton and @a authn_baton are the same as in the setup-request functio
n
*
* @a authn_info_parameters is a dictionary with the same structure as the
* `authn_parameters` argument to `serf_authn_get_realm_func_t`; except tha
t
* they're extracted from the Authentication-Info or Proxy-Authentication-I
nfo
* response header. This argument will be NULL @a response does not contai
n
* one of those headers.
*
* For the meaning of @a reset_pipelining, see serf_authn_handle_func_t.
*
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
typedef apr_status_t
(*serf_authn_validate_response_func_t)(int *reset_pipelining,
void *baton,
void *authn_baton,
int code,
serf_connection_t *conn,
apr_hash_t *authn_info_parameters,
serf_request_t *request,
serf_bucket_t *response,
apr_pool_t *scratch_pool);
/**
* Register an autehtication scheme.
*
* The @a name is the name of the authentication scheme as it appears in th
e
* authorization headers. It must be a valid token as defined in RFC-9110
* (see reference, below).
*
* @a baton will be passed unchanged to the callbacks.
*
* @a flags is a bitmask of @c APR_AUTHN_FLAG_* constants that define the
* scheme's requirements; e.g., whether the credentials callback should be
* invoked, or whether pipelining should be disabled while the authenticati
on
* handshake is in progress.
*
* @a init_conn, @a handle, @a setup_request and @a validate_response are t
he
* callbacks that implement the authentication handshake for this scheme.
*
* The number returned in @a type can be used as a bit mask in
* serf_config_authn_types(). If an error occurs during registration,
* @a type will be set to @c SERF_AUTHN_NONE.
*
* The @a ctx is used only for logging.
*
* Internal structures related to this provider will be allocated from @a
* result_pool, so take care that it lives as long as the autehtication sch
eme
* is registered. Ideally, this pool should have a longer lifetime than any
of
* the pools used in calls to the serf_contex_create() family of functions.
*
* @see https://www.rfc-editor.org/rfc/rfc9110#section-11.1
* @since New in 1.5
*/
apr_status_t serf_authn_register_scheme(
int *type,
serf_context_t *ctx,
const char *name, void *baton, int flags,
serf_authn_init_conn_func_t init_conn,
serf_authn_get_realm_func_t get_realm,
serf_authn_handle_func_t handle,
serf_authn_setup_request_func_t setup_request,
serf_authn_validate_response_func_t validate_response,
apr_pool_t *result_pool);
/**
* Unregister an uthentication scheme.
*
* Removes the scheme, identified by @a type that was returned from and
* @a name that was supplied to serf_authn_register_scheme(), from the
* list of supported authentication schemes. Uses @a scratch_pool for
* temporary allocations; this pool can be destroyed after the function
* has returned.
*
* The @a ctx is used only for logging.
*
* NOTE: Unregistering a scheme should be avoided, unless you can be absolu
tely
* sure that there are no outstanding requests, responses, connection
s or
* contexts that refer to it. There is no internal reference counting
or
* other mechanism to ensure that the scheme remains accessible while
it's
* in use. So in short: *do not* use this function at all.
*
* @since New in 1.5
*/
apr_status_t serf_authn_unregister_scheme(serf_context_t *ctx,
int type,
const char *name,
apr_pool_t *scratch_pool);
/** @} */
/**
* @defgroup serf buckets * @defgroup serf buckets
* @ingroup serf * @ingroup serf
* @{ * @{
*/ */
/** Pass as REQUESTED to the read function of a bucket to read, consume, /** Pass as REQUESTED to the read function of a bucket to read, consume,
* and return all available data. * and return all available data.
*/ */
#define SERF_READ_ALL_AVAIL ((apr_size_t)-1) #define SERF_READ_ALL_AVAIL ((apr_size_t)-1)
skipping to change at line 735 skipping to change at line 1467
* Note: an alternative to using this symbol would be for callers to see * Note: an alternative to using this symbol would be for callers to see
* the SERF_NEWLINE_CR return value, and know that some "end of buffer" was * the SERF_NEWLINE_CR return value, and know that some "end of buffer" was
* reached. While this works well for @see serf_util_readline, it does not * reached. While this works well for @see serf_util_readline, it does not
* necessary work as well for buckets (there is no obvious "end of buffer", * necessary work as well for buckets (there is no obvious "end of buffer",
* although there is an "end of bucket"). The other problem with that * although there is an "end of bucket"). The other problem with that
* alternative is that developers might miss the condition. This symbol * alternative is that developers might miss the condition. This symbol
* calls out the possibility and ensures that callers will watch for it. * calls out the possibility and ensures that callers will watch for it.
*/ */
#define SERF_NEWLINE_CRLF_SPLIT 0x0010 #define SERF_NEWLINE_CRLF_SPLIT 0x0010
/**
* Used to indicate that length of remaining data in bucket is unknown. See
* serf_bucket_type_t->get_remaining().
*
* @since New in 1.5.
*/
#define SERF_LENGTH_UNKNOWN ((apr_uint64_t) -1)
struct serf_bucket_type_t { struct serf_bucket_type_t {
/** name of this bucket type */ /** name of this bucket type */
const char *name; const char *name;
/** /**
* Read (and consume) up to @a requested bytes from @a bucket. * Read (and consume) up to @a requested bytes from @a bucket.
* *
* A pointer to the data will be returned in @a data, and its length * A pointer to the data will be returned in @a data, and its length
* is specified by @a len. * is specified by @a len.
* *
* The data will exist until one of two conditions occur: * The data will exist until one of two conditions occur:
* *
* 1) this bucket is destroyed * 1) this bucket is destroyed
* 2) another call to any read function or to peek() * 2) another call to any read function, get_remaining() or to peek()
* *
* If an application needs the data to exist for a longer duration, * If an application needs the data to exist for a longer duration,
* then it must make a copy. * then it must make a copy.
*/ */
apr_status_t (*read)(serf_bucket_t *bucket, apr_size_t requested, apr_status_t (*read)(serf_bucket_t *bucket, apr_size_t requested,
const char **data, apr_size_t *len); const char **data, apr_size_t *len);
/** /**
* Read (and consume) a line of data from @a bucket. * Read (and consume) a line of data from @a bucket.
* *
* The acceptable forms of a newline are given by @a acceptable, and * The acceptable forms of a newline are given by @a acceptable, and
* the type found is returned in @a found. If a newline is not present * the type found is returned in @a found. If a newline is not present
* in the returned data, then SERF_NEWLINE_NONE is stored into @a found . * in the returned data, then SERF_NEWLINE_NONE is stored into @a found .
* *
* A pointer to the data is returned in @a data, and its length is * A pointer to the data is returned in @a data, and its length is
* specified by @a len. The data will include the newline, if present. * specified by @a len. The data will include the newline, if present.
* *
* Note that there is no way to limit the amount of data returned * Note that there is no way to limit the amount of data returned
* by this function. * by this function. @see serf_bucket_limited_readline().
* *
* The lifetime of the data is the same as that of the @see read * The lifetime of the data is the same as that of the @see read
* function above. * function above.
*/ */
apr_status_t (*readline)(serf_bucket_t *bucket, int acceptable, apr_status_t (*readline)(serf_bucket_t *bucket, int acceptable,
int *found, int *found,
const char **data, apr_size_t *len); const char **data, apr_size_t *len);
/** /**
* Read a set of pointer/length pairs from the bucket. * Read a set of pointer/length pairs from the bucket.
skipping to change at line 871 skipping to change at line 1611
* APR_EAGAIN will never be returned. * APR_EAGAIN will never be returned.
*/ */
apr_status_t (*peek)(serf_bucket_t *bucket, apr_status_t (*peek)(serf_bucket_t *bucket,
const char **data, apr_size_t *len); const char **data, apr_size_t *len);
/** /**
* Destroy @a bucket, along with any associated resources. * Destroy @a bucket, along with any associated resources.
*/ */
void (*destroy)(serf_bucket_t *bucket); void (*destroy)(serf_bucket_t *bucket);
/* The following members are valid only if read_bucket equals to
* serf_buckets_are_v2() (or in a future spec _v3, etc.). */
/* Real pointer to read_bucket() method when read_bucket is
* serf_buckets_are_v2().
*
* @since New in 1.5 / Buckets v2.
*/
serf_bucket_t * (*read_bucket_v2)(serf_bucket_t *bucket,
const serf_bucket_type_t *type);
/* Returns length of remaining data to be read in @a bucket. Returns
* SERF_LENGTH_UNKNOWN if length is unknown.
*
* @since New in 1.5 / Buckets v2.
*/
apr_uint64_t (*get_remaining)(serf_bucket_t *bucket);
/* Provides a reference to a config object containing all configuration
* values relevant for this bucket.
*
* @since New in 1.5 / Buckets v2
*/
apr_status_t (*set_config)(serf_bucket_t *bucket, serf_config_t *config
);
/* ### apr buckets have 'copy', 'split', and 'setaside' functions. /* ### apr buckets have 'copy', 'split', and 'setaside' functions.
### not sure whether those will be needed in this bucket model. ### not sure whether those will be needed in this bucket model.
*/ */
}; };
/** /**
* Should the use and lifecycle of buckets be tracked? * Should the use and lifecycle of buckets be tracked?
* *
* When tracking, the system will ensure several semantic requirements * When tracking, the system will ensure several semantic requirements
* of bucket use: * of bucket use:
skipping to change at line 897 skipping to change at line 1662
* - buckets should not be destroyed before they return APR_EOF unless * - buckets should not be destroyed before they return APR_EOF unless
* the connection is closed for some reason. * the connection is closed for some reason.
* *
* Undefine this symbol to avoid the tracking (and a performance gain). * Undefine this symbol to avoid the tracking (and a performance gain).
* *
* ### we may want to examine when/how we provide this. should it always * ### we may want to examine when/how we provide this. should it always
* ### be compiled in? and apps select it before including this header? * ### be compiled in? and apps select it before including this header?
*/ */
/* #define SERF_DEBUG_BUCKET_USE */ /* #define SERF_DEBUG_BUCKET_USE */
/* Predefined value for read_bucket vtable member to declare v2 buckets
* vtable.
*
* @since New in 1.5.
*/
serf_bucket_t * serf_buckets_are_v2(serf_bucket_t *bucket,
const serf_bucket_type_t *type);
/** Gets the serf bucket type of the bucket if the bucket implements at lea
st
* buckets version, or if not a bucket type providing a default implementat
ion
*
* @since New in 1.5.
*/
const serf_bucket_type_t *serf_get_type(serf_bucket_t *bucket,
int min_version);
/* Internal macros for tracking bucket use. */ /* Internal macros for tracking bucket use. */
#ifdef SERF_DEBUG_BUCKET_USE #ifdef SERF_DEBUG_BUCKET_USE
#define SERF__RECREAD(b,s) serf_debug__record_read(b,s) #define SERF__RECREAD(b,s) serf_debug__record_read(b,s)
#else #else
#define SERF__RECREAD(b,s) (s) #define SERF__RECREAD(b,s) (s)
#endif #endif
#define serf_bucket_read(b,r,d,l) SERF__RECREAD(b, (b)->type->read(b,r,d,l) ) #define serf_bucket_read(b,r,d,l) SERF__RECREAD(b, (b)->type->read(b,r,d,l) )
#define serf_bucket_readline(b,a,f,d,l) \ #define serf_bucket_readline(b,a,f,d,l) \
SERF__RECREAD(b, (b)->type->readline(b,a,f,d,l)) SERF__RECREAD(b, (b)->type->readline(b,a,f,d,l))
#define serf_bucket_read_iovec(b,r,s,v,u) \ #define serf_bucket_read_iovec(b,r,s,v,u) \
SERF__RECREAD(b, (b)->type->read_iovec(b,r,s,v,u)) SERF__RECREAD(b, (b)->type->read_iovec(b,r,s,v,u))
#define serf_bucket_read_for_sendfile(b,r,h,f,o,l) \ #define serf_bucket_read_for_sendfile(b,r,h,f,o,l) \
SERF__RECREAD(b, (b)->type->read_for_sendfile(b,r,h,f,o,l)) SERF__RECREAD(b, (b)->type->read_for_sendfile(b,r,h,f,o,l))
#define serf_bucket_read_bucket(b,t) ((b)->type->read_bucket(b,t)) #define serf_bucket_read_bucket(b,t) ((b)->type->read_bucket(b,t))
#define serf_bucket_peek(b,d,l) ((b)->type->peek(b,d,l)) #define serf_bucket_peek(b,d,l) ((b)->type->peek(b,d,l))
#define serf_bucket_destroy(b) ((b)->type->destroy(b)) #define serf_bucket_destroy(b) ((b)->type->destroy(b))
#define serf_bucket_get_remaining(b) (serf_get_type(b, 2)->get_remaining(b)
)
#define serf_bucket_set_config(b,c) (serf_get_type(b, 2)->set_config(b, c))
/** /**
* Check whether a real error occurred. Note that bucket read functions * Check whether a real error occurred. Note that bucket read functions
* can return EOF and EAGAIN as part of their "normal" operation, so they * can return EOF and EAGAIN as part of their "normal" operation, so they
* should not be considered an error. * should not be considered an error.
*/ */
#define SERF_BUCKET_READ_ERROR(status) ((status) \ #define SERF_BUCKET_READ_ERROR(status) ((status) \
&& !APR_STATUS_IS_EOF(status) \ && !APR_STATUS_IS_EOF(status) \
&& !APR_STATUS_IS_EAGAIN(status) \ && !APR_STATUS_IS_EAGAIN(status) \
&& (SERF_ERROR_WAIT_CONN != status) ) && (SERF_ERROR_WAIT_CONN != status) )
skipping to change at line 942 skipping to change at line 1725
/** the allocator used for this bucket (needed at destroy time) */ /** the allocator used for this bucket (needed at destroy time) */
serf_bucket_alloc_t *allocator; serf_bucket_alloc_t *allocator;
}; };
/** /**
* Generic macro to construct "is TYPE" macros. * Generic macro to construct "is TYPE" macros.
*/ */
#define SERF_BUCKET_CHECK(b, btype) ((b)->type == &serf_bucket_type_ ## bty pe) #define SERF_BUCKET_CHECK(b, btype) ((b)->type == &serf_bucket_type_ ## bty pe)
/** @} */
/** /**
* Notification callback for a block that was not returned to the bucket * Notification callback for a block that was not returned to the bucket
* allocator when its pool was destroyed. * allocator when its pool was destroyed.
* *
* The block of memory is given by @a block. The baton provided when the * The block of memory is given by @a block. The baton provided when the
* allocator was constructed is passed as @a unfreed_baton. * allocator was constructed is passed as @a unfreed_baton.
*/ */
typedef void (*serf_unfreed_func_t)( typedef void (*serf_unfreed_func_t)(
void *unfreed_baton, void *unfreed_baton,
void *block); void *block);
skipping to change at line 1000 skipping to change at line 1785
* Since it is entirely possible for a line to be broken by APR_EAGAIN, * Since it is entirely possible for a line to be broken by APR_EAGAIN,
* this structure can be used to accumulate the data until a complete line * this structure can be used to accumulate the data until a complete line
* has been read from a bucket. * has been read from a bucket.
*/ */
/* This limit applies to the line buffer functions. If an application needs /* This limit applies to the line buffer functions. If an application needs
* longer lines, then they will need to manually handle line buffering. * longer lines, then they will need to manually handle line buffering.
*/ */
#define SERF_LINEBUF_LIMIT 8000 #define SERF_LINEBUF_LIMIT 8000
typedef struct { typedef struct serf_linebuf_t {
/* Current state of the buffer. */ /* Current state of the buffer. */
enum { enum {
SERF_LINEBUF_EMPTY, SERF_LINEBUF_EMPTY,
SERF_LINEBUF_READY, SERF_LINEBUF_READY,
SERF_LINEBUF_PARTIAL, SERF_LINEBUF_PARTIAL,
SERF_LINEBUF_CRLF_SPLIT SERF_LINEBUF_CRLF_SPLIT
} state; } state;
/* How much of the buffer have we used? */ /* How much of the buffer have we used? */
apr_size_t used; apr_size_t used;
/* The line is read into this buffer, minus CR/LF */ /* The line is read into this buffer, minus CR/LF.
*
* NOTE: Before serf 1.4 buffer IS NOT NUL terminated
* and @a used should be used to find line length.
*
* Since serf 1.4 buffer is always NUL terminated.
**/
char line[SERF_LINEBUF_LIMIT]; char line[SERF_LINEBUF_LIMIT];
} serf_linebuf_t; } serf_linebuf_t;
/** /**
* Initialize the @a linebuf structure. * Initialize the @a linebuf structure.
*/ */
void serf_linebuf_init(serf_linebuf_t *linebuf); void serf_linebuf_init(serf_linebuf_t *linebuf);
/** /**
skipping to change at line 1036 skipping to change at line 1827
* acceptable for this fetch. * acceptable for this fetch.
* *
* ### we should return a data/len pair so that we can avoid a copy, * ### we should return a data/len pair so that we can avoid a copy,
* ### rather than having callers look into our state and line buffer. * ### rather than having callers look into our state and line buffer.
*/ */
apr_status_t serf_linebuf_fetch( apr_status_t serf_linebuf_fetch(
serf_linebuf_t *linebuf, serf_linebuf_t *linebuf,
serf_bucket_t *bucket, serf_bucket_t *bucket,
int acceptable); int acceptable);
/** @} */ /*** Configuration store declarations ***/
/* Internal functions for bucket use and lifecycle tracking */ typedef const apr_uint32_t serf_config_key_t;
/* The left-most byte of the int32 key holds the category (bit flags).
The other bytes are a number representing the key.
Serf will not use the second byte for its own keys, so applications can
use this byte to define custom keys.
*/
typedef enum serf_config_categories_t {
SERF_CONFIG_PER_CONTEXT = 0x10000000,
SERF_CONFIG_PER_HOST = 0x20000000,
SERF_CONFIG_PER_CONNECTION = 0x40000000
} serf_config_categories_t;
#define SERF_CONFIG_HOST_NAME (SERF_CONFIG_PER_HOST | 0x000001)
#define SERF_CONFIG_HOST_PORT (SERF_CONFIG_PER_HOST | 0x000002)
#define SERF_CONFIG_CONN_LOCALIP (SERF_CONFIG_PER_CONNECTION | 0x000001)
#define SERF_CONFIG_CONN_REMOTEIP (SERF_CONFIG_PER_CONNECTION | 0x000002)
#define SERF_CONFIG_CONN_PIPELINING (SERF_CONFIG_PER_CONNECTION | 0x000003)
#define SERF_CONFIG_CTX_LOGBATON (SERF_CONFIG_PER_CONTEXT | 0x000001)
/* Configuration values stored in the configuration store:
Category Key Value Type
-------- --- ----------
Context logbaton log_baton_t *
Context proxyauthn apr_hash_t * (not implemented)
Connection localip const char *
Connection remoteip const char *
Host hostname const char *
Host hostport const char *
Host authn apr_hash_t * (not implemented)
*/
/**
* Set a value of type const char * for configuration item CATEGORY+KEY.
*
* @since New in 1.5.
*/
apr_status_t serf_config_set_string(serf_config_t *config,
serf_config_key_t key,
const char *value);
/**
* Copy a value of type const char * and set it for configuration item
* CATEGORY+KEY.
*
* @since New in 1.5.
*/
apr_status_t serf_config_set_stringc(serf_config_t *config,
serf_config_key_t key,
const char *value);
/**
* Set a value of generic type for configuration item CATEGORY+KEY.
* See @a serf_set_config_string for COPY_FLAGS description.
*
* @since New in 1.5.
*/
apr_status_t serf_config_set_stringf(serf_config_t *config,
serf_config_key_t key,
apr_pool_t *scratch_pool,
const char *fmt, ...);
/**
* Set a value of generic type for configuration item CATEGORY+KEY.
* See @a serf_set_config_string for COPY_FLAGS description.
*
* @since New in 1.5.
*/
apr_status_t serf_config_set_object(serf_config_t *config,
serf_config_key_t key,
void *value);
/**
* Get the value for configuration item CATEGORY+KEY. The value's type will
* be fixed, see the above table.
* Returns APR_EINVAL when getting a key from a category that this config
* object doesn't contain, APR_SUCCESS otherwise.
*
* @since New in 1.5.
*/
apr_status_t serf_config_get_string(serf_config_t *config,
serf_config_key_t key,
const char **value);
apr_status_t serf_config_get_object(serf_config_t *config,
serf_config_key_t key,
void **value);
/**
* Remove the value for configuration item CATEGORY+KEY from the configurat
ion
* store.
*
* @since New in 1.5.
*/
apr_status_t serf_config_remove_value(serf_config_t *config,
serf_config_key_t key);
/*** Serf logging API ***/
/* Ordered list of log levels, more detailed log levels include less
detailed levels. (e.g. level DEBUG also logs ERROR, WARNING & INFO messa
ges).
*/
#define SERF_LOG_ERROR 0x0001
#define SERF_LOG_WARNING 0x0002
#define SERF_LOG_INFO 0x0004
#define SERF_LOG_DEBUG 0x0008
#define SERF_LOG_NONE 0x0000
/* List of components, used as a mask. */
#define SERF_LOGCOMP_ALL_MSG 0xFFFF /* All components, including message
content */
#define SERF_LOGCOMP_RAWMSG 0x0100 /* logs requests and responses directl
y on
the socket layer. */
#define SERF_LOGCOMP_SSLMSG 0x0200 /* logs decrypted requests and respons
es. */
#define SERF_LOGCOMP_ALL 0x00FF /* All components, no message content
*/
#define SERF_LOGCOMP_SSL 0x0001 /* The SSL component */
#define SERF_LOGCOMP_AUTHN 0x0002 /* Authentication components */
#define SERF_LOGCOMP_CONN 0x0004 /* Connection-related events */
#define SERF_LOGCOMP_COMPR 0x0008 /* The compression (deflate) component
*/
#define SERF_LOGCOMP_PROTOCOL 0x0010 /* The protocol components */
#define SERF_LOGCOMP_NONE 0x0000
typedef struct serf_log_output_t serf_log_output_t;
typedef struct serf_log_layout_t serf_log_layout_t;
/* The default log layout. It's format is:
[TIMESTAMP] [LOG LEVEL] [l:LOCALIP:PORT r:REMOTEIP:PORT] FILENAME MESSAG
E
*/
#define SERF_LOG_DEFAULT_LAYOUT ((serf_log_layout_t *)NULL)
/* TODO: it's not yet possible to define custom layouts */
/**
* Create a stream output for log info. This can be used with one of the
* standard streams stderr or stdout.
* LAYOUT should be SERF_LOG_DEFAULT_LAYOUT (there's no alternative for now
).
* The lifetime of POOL should be at least the same as that of CTX, but it
can
* be used by multiple contexts.
*
* @since New in 1.5.
*/
apr_status_t serf_logging_create_stream_output(serf_log_output_t **output,
serf_context_t *ctx,
apr_uint32_t level,
apr_uint32_t comp_mask,
serf_log_layout_t *layout,
FILE *fp,
apr_pool_t *pool);
/**
* Define an output handler for a log level and a (set of) log component(s)
.
* OUTPUT is the object returned by one of the serf_logging_create_XXX_outp
ut
* factory functions.
*
* @since New in 1.5.
*/
apr_status_t serf_logging_add_output(serf_context_t *ctx,
const serf_log_output_t *output);
/* Internal functions for bucket use and lifecycle tracking.
### Some of these are directly or via Macros used by third party
### applications, such as Apache Subversion */
apr_status_t serf_debug__record_read( apr_status_t serf_debug__record_read(
const serf_bucket_t *bucket, const serf_bucket_t *bucket,
apr_status_t status); apr_status_t status);
void serf_debug__entered_loop( void serf_debug__entered_loop(
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
void serf_debug__closed_conn( void serf_debug__closed_conn(
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
void serf_debug__bucket_destroy( void serf_debug__bucket_destroy(
const serf_bucket_t *bucket); const serf_bucket_t *bucket);
void serf_debug__bucket_alloc_check( void serf_debug__bucket_alloc_check(
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* Version info */ /* Version info */
#define SERF_MAJOR_VERSION 1 #define SERF_MAJOR_VERSION 2
#define SERF_MINOR_VERSION 3 #define SERF_MINOR_VERSION 0
#define SERF_PATCH_VERSION 10 #define SERF_PATCH_VERSION 0
/* Version number string */ /* Version number string */
#define SERF_VERSION_STRING APR_STRINGIFY(SERF_MAJOR_VERSION) "." \ #define SERF_VERSION_STRING APR_STRINGIFY(SERF_MAJOR_VERSION) "." \
APR_STRINGIFY(SERF_MINOR_VERSION) "." \ APR_STRINGIFY(SERF_MINOR_VERSION) "." \
APR_STRINGIFY(SERF_PATCH_VERSION) APR_STRINGIFY(SERF_PATCH_VERSION)
/** /**
* Check at compile time if the Serf version is at least a certain * Check at compile time if the Serf version is at least a certain
* level. * level.
* @param major The major version component of the version checked * @param major The major version component of the version checked
skipping to change at line 1082 skipping to change at line 2036
(((major) < SERF_MAJOR_VERSION) \ (((major) < SERF_MAJOR_VERSION) \
|| ((major) == SERF_MAJOR_VERSION && (minor) < SERF_MINOR_VERSION) \ || ((major) == SERF_MAJOR_VERSION && (minor) < SERF_MINOR_VERSION) \
|| ((major) == SERF_MAJOR_VERSION && (minor) == SERF_MINOR_VERSION && \ || ((major) == SERF_MAJOR_VERSION && (minor) == SERF_MINOR_VERSION && \
(patch) <= SERF_PATCH_VERSION)) (patch) <= SERF_PATCH_VERSION))
/** /**
* Returns the version of the library the application has linked/loaded. * Returns the version of the library the application has linked/loaded.
* Values are returned in @a major, @a minor, and @a patch. * Values are returned in @a major, @a minor, and @a patch.
* *
* Applications will want to use this function to verify compatibility, * Applications will want to use this function to verify compatibility,
* expecially while serf has not reached a 1.0 milestone. APIs and * especially while serf has not reached a 1.0 milestone. APIs and
* semantics may change drastically until the library hits 1.0. * semantics may change drastically until the library hits 1.0.
*/ */
void serf_lib_version( void serf_lib_version(
int *major, int *major,
int *minor, int *minor,
int *patch); int *patch);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
 End of changes. 43 change blocks. 
42 lines changed or deleted 1072 lines changed or added


 serf_bucket_types.h (1.3.10)   serf_bucket_types.h (current) 
skipping to change at line 62 skipping to change at line 62
/* Send a Content-Length header with @a len. The @a body bucket should /* Send a Content-Length header with @a len. The @a body bucket should
contain precisely that much data. */ contain precisely that much data. */
void serf_bucket_request_set_CL( void serf_bucket_request_set_CL(
serf_bucket_t *bucket, serf_bucket_t *bucket,
apr_int64_t len); apr_int64_t len);
serf_bucket_t *serf_bucket_request_get_headers( serf_bucket_t *serf_bucket_request_get_headers(
serf_bucket_t *request); serf_bucket_t *request);
/**
* Transform @a bucket in-place into a request bucket.
*
* It is callers responsibility to free resources held by the original
* bucket.
*/
void serf_bucket_request_become( void serf_bucket_request_become(
serf_bucket_t *bucket, serf_bucket_t *bucket,
const char *method, const char *method,
const char *uri, const char *uri,
serf_bucket_t *body); serf_bucket_t *body);
/** /**
* Sets the root url of the remote host. If this request contains a relativ e * Sets the root url of the remote host. If this request contains a relativ e
* url, it will be prefixed with the root url to form an absolute url. * 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 * @a bucket is the request bucket. @a root_url is the absolute url of the
* root of the remote host, without the closing '/'. * root of the remote host, without the closing '/'.
*/ */
void serf_bucket_request_set_root( void serf_bucket_request_set_root(
serf_bucket_t *bucket, serf_bucket_t *bucket,
const char *root_url); const char *root_url);
/* ==================================================================== */ /* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_incoming_request;
#define SERF_BUCKET_IS_INCOMING_REQUEST(b) \
SERF_BUCKET_CHECK((b), incoming_request)
serf_bucket_t *serf_bucket_incoming_request_create(
serf_bucket_t *body,
serf_bucket_alloc_t *allocator);
/* All output arguments optional. Waits for the request line to have arrive
d
with the normal read responses. */
/* ### Add RESULT_POOL argument? */
apr_status_t serf_bucket_incoming_request_read(
serf_bucket_t **headers,
const char **method,
const char **path,
int *http_version,
serf_bucket_t *request);
apr_status_t serf_bucket_incoming_request_wait_for_headers(
serf_bucket_t *response);
/* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_response; extern const serf_bucket_type_t serf_bucket_type_response;
#define SERF_BUCKET_IS_RESPONSE(b) SERF_BUCKET_CHECK((b), response) #define SERF_BUCKET_IS_RESPONSE(b) SERF_BUCKET_CHECK((b), response)
serf_bucket_t *serf_bucket_response_create( serf_bucket_t *serf_bucket_response_create(
serf_bucket_t *stream, serf_bucket_t *stream,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
#define SERF_HTTP_VERSION(major, minor) ((major) * 1000 + (minor)) #define SERF_HTTP_VERSION(major, minor) ((major) * 1000 + (minor))
#define SERF_HTTP_11 SERF_HTTP_VERSION(1, 1) #define SERF_HTTP_11 SERF_HTTP_VERSION(1, 1)
#define SERF_HTTP_10 SERF_HTTP_VERSION(1, 0) #define SERF_HTTP_10 SERF_HTTP_VERSION(1, 0)
/** @since New in 1.5. */
#define SERF_HTTP_20 SERF_HTTP_VERSION(2, 0)
#define SERF_HTTP_VERSION_MAJOR(shv) ((int)shv / 1000) #define SERF_HTTP_VERSION_MAJOR(shv) ((int)shv / 1000)
#define SERF_HTTP_VERSION_MINOR(shv) ((int)shv % 1000) #define SERF_HTTP_VERSION_MINOR(shv) ((int)shv % 1000)
typedef struct { typedef struct serf_status_line {
int version; int version;
int code; int code;
const char *reason; const char *reason;
} serf_status_line; } serf_status_line;
/** /**
* Return the Status-Line information, if available. This function * Return the Status-Line information, if available. This function
* works like other bucket read functions: it may return APR_EAGAIN or * 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 * APR_EOF to signal the state of the bucket for reading. A return
* value of APR_SUCCESS will always indicate that status line * value of APR_SUCCESS will always indicate that status line
skipping to change at line 122 skipping to change at line 153
/** /**
* Wait for the HTTP headers to be processed for a @a response. * Wait for the HTTP headers to be processed for a @a response.
* *
* If the headers are available, APR_SUCCESS is returned. * If the headers are available, APR_SUCCESS is returned.
* If the headers aren't available, APR_EAGAIN is returned. * If the headers aren't available, APR_EAGAIN is returned.
*/ */
apr_status_t serf_bucket_response_wait_for_headers( apr_status_t serf_bucket_response_wait_for_headers(
serf_bucket_t *response); serf_bucket_t *response);
/** /**
* Wait for the first HTTP headers to be processed for a @a response.
* If 1XX informational responses are received before the actual headers
* this function will return APR_SUCCESS as soon as such a set is processed
,
* while serf_bucket_response_wait_for_headers() will wait until the
* actual headers to be available.
*
* If @a wait_for_next is TRUE, the function will wait for the next set
* of informational header instead of returning success for the first set.
*
* @since New in 1.5.
*/
apr_status_t serf_bucket_response_wait_for_some_headers(
serf_bucket_t *response,
int wait_for_next);
/**
* Get the headers bucket for @a response. * Get the headers bucket for @a response.
*/ */
serf_bucket_t *serf_bucket_response_get_headers( serf_bucket_t *serf_bucket_response_get_headers(
serf_bucket_t *response); serf_bucket_t *response);
/** /**
* Advise the response @a bucket that this was from a HEAD request and * Advise the response @a bucket that this was from a HEAD request and
* that it should not expect to see a response body. * that it should not expect to see a response body.
*/ */
void serf_bucket_response_set_head( void serf_bucket_response_set_head(
serf_bucket_t *bucket); serf_bucket_t *bucket);
/**
* Ask the response @a bucket, to decode content based on the value of the
* 'Content- Encoding' header, or not. The default setting of a response
* bucket is to decode when the header is found.
*/
void serf_bucket_response_decode_content(
serf_bucket_t *bucket,
int decode);
/* ==================================================================== */ /* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_response_body; extern const serf_bucket_type_t serf_bucket_type_response_body;
#define SERF_BUCKET_IS_RESPONSE_BODY(b) SERF_BUCKET_CHECK((b), response_bod y) #define SERF_BUCKET_IS_RESPONSE_BODY(b) SERF_BUCKET_CHECK((b), response_bod y)
serf_bucket_t *serf_bucket_response_body_create( serf_bucket_t *serf_bucket_response_body_create(
serf_bucket_t *stream, serf_bucket_t *stream,
apr_uint64_t limit, apr_uint64_t limit,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* ==================================================================== */ /* ==================================================================== */
/** @since New in 1.5 */
extern const serf_bucket_type_t serf_bucket_type_outgoing_response;
/** @since New in 1.5 */
#define SERF_BUCKET_IS_OUTGOING_RESPONSE(b) \
SERF_BUCKET_CHECK((b), outgoing_response)
/** @since New in 1.5 */
serf_bucket_t *serf_bucket_outgoing_response_create(
serf_bucket_t *body,
int status,
const char *reason,
int http_version,
serf_bucket_alloc_t *allocator);
/** @since New in 1.5 */
serf_bucket_t *serf_bucket_outgoing_response_get_headers(
serf_bucket_t *outgoing_response);
/** @since New in 1.5 */
void serf_bucket_outgoing_response_prepare(
serf_bucket_t *outgoing_response,
int http_version,
int allow_chunking);
/* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_bwtp_frame; extern const serf_bucket_type_t serf_bucket_type_bwtp_frame;
#define SERF_BUCKET_IS_BWTP_FRAME(b) SERF_BUCKET_CHECK((b), 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; 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_i ncoming_frame) #define SERF_BUCKET_IS_BWTP_INCOMING_FRAME(b) SERF_BUCKET_CHECK((b), bwtp_i ncoming_frame)
int serf_bucket_bwtp_frame_get_channel( int serf_bucket_bwtp_frame_get_channel(
serf_bucket_t *hdr); serf_bucket_t *hdr);
skipping to change at line 209 skipping to change at line 290
/** serf_bucket_aggregate_cleanup will instantly destroy all buckets in /** serf_bucket_aggregate_cleanup will instantly destroy all buckets in
the aggregate bucket that have been read completely. Whereas normally, the aggregate bucket that have been read completely. Whereas normally,
these buckets are destroyed on every read operation. */ these buckets are destroyed on every read operation. */
void serf_bucket_aggregate_cleanup( void serf_bucket_aggregate_cleanup(
serf_bucket_t *bucket, serf_bucket_t *bucket,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
serf_bucket_t *serf_bucket_aggregate_create( serf_bucket_t *serf_bucket_aggregate_create(
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* Creates a stream bucket. /** Transform @a bucket in-place into an aggregate bucket.
A stream bucket is like an aggregate bucket, but: *
- it doesn't destroy its child buckets on cleanup * It is callers responsibility to free resources held by the original
- one can always keep adding child buckets, the handler FN should return * bucket */
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( void serf_bucket_aggregate_become(
serf_bucket_t *bucket); serf_bucket_t *bucket);
void serf_bucket_aggregate_prepend( void serf_bucket_aggregate_prepend(
serf_bucket_t *aggregate_bucket, serf_bucket_t *aggregate_bucket,
serf_bucket_t *prepend_bucket); serf_bucket_t *prepend_bucket);
void serf_bucket_aggregate_append( void serf_bucket_aggregate_append(
serf_bucket_t *aggregate_bucket, serf_bucket_t *aggregate_bucket,
serf_bucket_t *append_bucket); serf_bucket_t *append_bucket);
skipping to change at line 318 skipping to change at line 387
* Equivalent to serf_bucket_simple_create, except that the bucket assumes * Equivalent to serf_bucket_simple_create, except that the bucket assumes
* responsibility for freeing the data on this allocator without making * responsibility for freeing the data on this allocator without making
* a copy. It is assumed that data was created by a call from allocator. * a copy. It is assumed that data was created by a call from allocator.
*/ */
serf_bucket_t *serf_bucket_simple_own_create( serf_bucket_t *serf_bucket_simple_own_create(
const char *data, const char *data,
apr_size_t len, apr_size_t len,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
#define SERF_BUCKET_SIMPLE_STRING(s,a) \ #define SERF_BUCKET_SIMPLE_STRING(s,a) \
serf_bucket_simple_create(s, strlen(s), NULL, NULL, a); serf_bucket_simple_create(s, strlen(s), NULL, NULL, a)
#define SERF_BUCKET_SIMPLE_STRING_LEN(s,l,a) \ #define SERF_BUCKET_SIMPLE_STRING_LEN(s,l,a) \
serf_bucket_simple_create(s, l, NULL, NULL, 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 /* 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. */ the caller can never create an apr_mmap_t to pass to this function. */
extern const serf_bucket_type_t serf_bucket_type_mmap; extern const serf_bucket_type_t serf_bucket_type_mmap;
#define SERF_BUCKET_IS_MMAP(b) SERF_BUCKET_CHECK((b), mmap) #define SERF_BUCKET_IS_MMAP(b) SERF_BUCKET_CHECK((b), mmap)
serf_bucket_t *serf_bucket_mmap_create( serf_bucket_t *serf_bucket_mmap_create(
skipping to change at line 465 skipping to change at line 534
#define SERF_BUCKET_IS_DEFLATE(b) SERF_BUCKET_CHECK((b), deflate) #define SERF_BUCKET_IS_DEFLATE(b) SERF_BUCKET_CHECK((b), deflate)
#define SERF_DEFLATE_GZIP 0 #define SERF_DEFLATE_GZIP 0
#define SERF_DEFLATE_DEFLATE 1 #define SERF_DEFLATE_DEFLATE 1
serf_bucket_t *serf_bucket_deflate_create( serf_bucket_t *serf_bucket_deflate_create(
serf_bucket_t *stream, serf_bucket_t *stream,
serf_bucket_alloc_t *allocator, serf_bucket_alloc_t *allocator,
int format); int format);
serf_bucket_t *serf_bucket_deflate_compress_create(
serf_bucket_t *stream,
int memlevel,
int format,
serf_bucket_alloc_t *allocator);
/* ==================================================================== */ /* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_limit; extern const serf_bucket_type_t serf_bucket_type_limit;
#define SERF_BUCKET_IS_LIMIT(b) SERF_BUCKET_CHECK((b), limit) #define SERF_BUCKET_IS_LIMIT(b) SERF_BUCKET_CHECK((b), limit)
serf_bucket_t *serf_bucket_limit_create( serf_bucket_t *serf_bucket_limit_create(
serf_bucket_t *stream, serf_bucket_t *stream,
apr_uint64_t limit, apr_uint64_t limit,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* ==================================================================== */ /* ==================================================================== */
#define SERF_SSL_CERT_NOTYETVALID 1 #define SERF_SSL_CERT_NOTYETVALID 0x0001
#define SERF_SSL_CERT_EXPIRED 2 #define SERF_SSL_CERT_EXPIRED 0x0002
#define SERF_SSL_CERT_UNKNOWNCA 4 #define SERF_SSL_CERT_UNKNOWNCA 0x0004
#define SERF_SSL_CERT_SELF_SIGNED 8 #define SERF_SSL_CERT_SELF_SIGNED 0x0008
#define SERF_SSL_CERT_UNKNOWN_FAILURE 16 #define SERF_SSL_CERT_UNKNOWN_FAILURE 0x0010
#define SERF_SSL_CERT_REVOKED 32 #define SERF_SSL_CERT_REVOKED 0x0020
#define SERF_SSL_CERT_UNABLE_TO_GET_CRL 0x0040
#define SERF_SSL_CERT_INVALID_HOST 0x0080
extern const serf_bucket_type_t serf_bucket_type_ssl_encrypt; #define SERF_SSL_OCSP_RESPONDER_TRYLATER 0x0100
#define SERF_BUCKET_IS_SSL_ENCRYPT(b) SERF_BUCKET_CHECK((b), ssl_encrypt) #define SERF_SSL_OCSP_RESPONDER_ERROR 0x0200
#define SERF_SSL_OCSP_RESPONDER_UNKNOWN_FAILURE 0x0400
#define SERF_SSL_SIGNATURE_FAILURE 0x0800
typedef struct serf_ssl_context_t serf_ssl_context_t; typedef struct serf_ssl_context_t serf_ssl_context_t;
typedef struct serf_ssl_certificate_t serf_ssl_certificate_t; typedef struct serf_ssl_certificate_t serf_ssl_certificate_t;
typedef apr_status_t (*serf_ssl_need_client_cert_t)( typedef apr_status_t (*serf_ssl_need_client_cert_t)(
void *data, void *data,
const char **cert_path); const char **cert_path);
typedef apr_status_t (*serf_ssl_need_cert_password_t)( typedef apr_status_t (*serf_ssl_need_cert_password_t)(
void *data, void *data,
const char *cert_path, const char *cert_path,
const char **password); const char **password);
typedef apr_status_t (*serf_ssl_need_cert_uri_t)(
void *data,
const char **cert_uri);
/**
* Callback type for server certificate status info and OCSP responses.
* Note that CERT can be NULL in case its called from the OCSP callback.
*/
typedef apr_status_t (*serf_ssl_need_server_cert_t)( typedef apr_status_t (*serf_ssl_need_server_cert_t)(
void *data, void *data,
int failures, int failures,
const serf_ssl_certificate_t *cert); const serf_ssl_certificate_t *cert);
typedef apr_status_t (*serf_ssl_server_cert_chain_cb_t)( typedef apr_status_t (*serf_ssl_server_cert_chain_cb_t)(
void *data, void *data,
int failures, int failures,
int error_depth, int error_depth,
const serf_ssl_certificate_t * const * certs, const serf_ssl_certificate_t * const * certs,
apr_size_t certs_len); apr_size_t certs_len);
/**
* Set a callback to provide a filesystem path to a PKCS12 file.
*
* This has been replaced by serf_ssl_cert_uri_set(). On Unix
* platforms the same path from serf_ssl_client_cert_provider_set()
* can be passed to serf_ssl_cert_uri_set(). On Windows the drive
* letter will be interpreted by serf_ssl_cert_uri_set() as a scheme,
* so the same path will not work, and will need to be escaped as
* a file URL instead.
*/
void serf_ssl_client_cert_provider_set( void serf_ssl_client_cert_provider_set(
serf_ssl_context_t *context, serf_ssl_context_t *context,
serf_ssl_need_client_cert_t callback, serf_ssl_need_client_cert_t callback,
void *data, void *data,
void *cache_pool); void *cache_pool);
/**
* Set a callback to provide the password corresponding to the URL of
* the client certificate store.
*
* If the serf_ssl_client_cert_provider_set callback is set, this
* password will also be used to decode the PKCS12 file.
*/
void serf_ssl_client_cert_password_set( void serf_ssl_client_cert_password_set(
serf_ssl_context_t *context, serf_ssl_context_t *context,
serf_ssl_need_cert_password_t callback, serf_ssl_need_cert_password_t callback,
void *data, void *data,
void *cache_pool); void *cache_pool);
/** /**
* Set a callback to provide the URL of the client certificate store.
*
* In the absence of a scheme the default scheme is file:, and the file
* can point to PKCS12, PEM or other supported certificates and keys.
*
* With the correct OpenSSL provider configured, URLs can be provided
* for pkcs11, tpm2, and other certificate stores.
*
* On Windows, file paths must be escaped as file: URLs to prevent the
* drive letter being intepreted as a scheme.
*/
void serf_ssl_cert_uri_set(
serf_ssl_context_t *context,
serf_ssl_need_cert_uri_t callback,
void *data,
void *cache_pool);
/**
* Set a callback to override the default SSL server certificate validation * Set a callback to override the default SSL server certificate validation
* algorithm. * algorithm.
*/ */
void serf_ssl_server_cert_callback_set( void serf_ssl_server_cert_callback_set(
serf_ssl_context_t *context, serf_ssl_context_t *context,
serf_ssl_need_server_cert_t callback, serf_ssl_need_server_cert_t callback,
void *data); void *data);
/** /**
* Set callbacks to override the default SSL server certificate validation * Set callbacks to override the default SSL server certificate validation
skipping to change at line 553 skipping to change at line 676
*/ */
apr_status_t serf_ssl_use_default_certificates( apr_status_t serf_ssl_use_default_certificates(
serf_ssl_context_t *context); serf_ssl_context_t *context);
/** /**
* Allow SNI indicators to be sent to the server. * Allow SNI indicators to be sent to the server.
*/ */
apr_status_t serf_ssl_set_hostname( apr_status_t serf_ssl_set_hostname(
serf_ssl_context_t *context, const char *hostname); serf_ssl_context_t *context, const char *hostname);
typedef apr_status_t (*serf_ssl_protocol_result_cb_t)(
void *data,
const char *protocol);
/**
* Enables ALPN negotiation with the server. Setups that the supported prot
ocols
* will be sent to the server, and enables handling the response via a call
back.
*
* SUPPORTED_PROTOCOLS is a comma separated list of protocols. No whitespac
e
* should be added as the values are used literally. E.g. "h2,http/1.1,h2-1
6"
*
* Returns APR_ENOTIMPL when the ssl library doesn't implement ALPN.
*
* If successful CALLBACK will be called as soon as the protocol is negotia
ted
* or directly after the secured stream is connected.
*
* @since New in 1.5.
*/
apr_status_t serf_ssl_negotiate_protocol(
serf_ssl_context_t *context,
const char *protocols,
serf_ssl_protocol_result_cb_t callback,
void *callback_data);
/** /**
* Return the depth of the certificate. * Return the depth of the certificate.
*/ */
int serf_ssl_cert_depth( int serf_ssl_cert_depth(
const serf_ssl_certificate_t *cert); const serf_ssl_certificate_t *cert);
/** /**
* Extract the fields of the issuer in a table with keys (E, CN, OU, O, L, * 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. * ST and C). The returned table will be allocated in @a pool.
*/ */
skipping to change at line 576 skipping to change at line 723
/** /**
* Extract the fields of the subject in a table with keys (E, CN, OU, O, L, * 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. * ST and C). The returned table will be allocated in @a pool.
*/ */
apr_hash_t *serf_ssl_cert_subject( apr_hash_t *serf_ssl_cert_subject(
const serf_ssl_certificate_t *cert, const serf_ssl_certificate_t *cert,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Extract the fields of the certificate in a table with keys (sha1, notBef * Extract the fields of the certificate in a table with keys
ore, * (sha1, notBefore, notAfter, subjectAltName, OCSP).
* notAfter, subjectAltName). The returned table will be allocated in @a po * The returned table will be allocated in @a pool.
ol.
*/ */
apr_hash_t *serf_ssl_cert_certificate( apr_hash_t *serf_ssl_cert_certificate(
const serf_ssl_certificate_t *cert, const serf_ssl_certificate_t *cert,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Export a certificate to base64-encoded, zero-terminated string. * Like serf_ssl_cert_export2() but uses a single pool for both the
* The returned string is allocated in @a pool. Returns NULL on failure. * result and temporary allocations.
*/ */
const char *serf_ssl_cert_export( const char *serf_ssl_cert_export(
const serf_ssl_certificate_t *cert, const serf_ssl_certificate_t *cert,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Export a certificate to base64-encoded, zero-terminated string.
* The returned string is allocated in @a result_pool.
* Uses @a scratch_pool for temporary allocations.
* Returns NULL on failure.
*
* @since New in 1.5.
*/
const char *serf_ssl_cert_export2(
const serf_ssl_certificate_t *cert,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Import a certificate from a base64-encoded, zero-terminated string.
* The returned certificate is allocated in @a result_pool.
* Uses @a scratch_pool for temporary allocations.
* Returns NULL on failure.
*
* @since New in 1.5.
*/
serf_ssl_certificate_t *serf_ssl_cert_import(
const char *encoded_cert,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Load a CA certificate file from a path @a file_path. If the file was loa ded * Load a CA certificate file from a path @a file_path. If the file was loa ded
* and parsed correctly, a certificate @a cert will be created and returned . * and parsed correctly, a certificate @a cert will be created and returned .
* This certificate object will be alloced in @a pool. * This certificate object will be alloced in @a pool.
*/ */
apr_status_t serf_ssl_load_cert_file( apr_status_t serf_ssl_load_cert_file(
serf_ssl_certificate_t **cert, serf_ssl_certificate_t **cert,
const char *file_path, const char *file_path,
apr_pool_t *pool); apr_pool_t *pool);
/** /**
* Adds the certificate @a cert to the list of trusted certificates in * Adds the certificate @a cert to the list of trusted certificates in
* @a ssl_ctx that will be used for verification. * @a ssl_ctx that will be used for verification.
* See also @a serf_ssl_load_cert_file. * See also @a serf_ssl_load_cert_file.
*/ */
apr_status_t serf_ssl_trust_cert( apr_status_t serf_ssl_trust_cert(
serf_ssl_context_t *ssl_ctx, serf_ssl_context_t *ssl_ctx,
serf_ssl_certificate_t *cert); serf_ssl_certificate_t *cert);
/** /**
* Load a CRL .pem file from @a file_path and enable CRL checking.
*
* @since New in 1.5.
*/
apr_status_t serf_ssl_add_crl_from_file(serf_ssl_context_t *ssl_ctx,
const char *file_path,
apr_pool_t *pool);
/**
* Enable or disable CRL checking of all server certificates.
* @a enabled = 1 to enable CRL checking, 0 to disable CRL checking.
* Default = disabled.
*
* @since New in 1.5.
*/
apr_status_t serf_ssl_check_crl(serf_ssl_context_t *ssl_ctx,
int enabled);
/**
* Enable or disable certificate status request (OCSP stapling) checking of
all
* server certificates.
* @a enabled = 1 to enable checking, 0 to disable checking.
* Default = disabled.
*
* @since New in 1.5.
*/
apr_status_t
serf_ssl_check_cert_status_request(serf_ssl_context_t *ssl_ctx, int enabled
);
/**
* Enable or disable SSL compression on a SSL session. * Enable or disable SSL compression on a SSL session.
* @a enabled = 1 to enable compression, 0 to disable compression. * @a enabled = 1 to enable compression, 0 to disable compression.
* Default = disabled. * Default = disabled.
*/ */
apr_status_t serf_ssl_use_compression( apr_status_t serf_ssl_use_compression(
serf_ssl_context_t *ssl_ctx, serf_ssl_context_t *ssl_ctx,
int enabled); int enabled);
/* ==================================================================== */
/**
* Internal representation of an OCSP request.
*
* @since New in 1.5.
*/
typedef struct serf_ssl_ocsp_request_t serf_ssl_ocsp_request_t;
/**
* Constructs an OCSP verification request for @a server_cert with
* issuer certificate @a issuer_cert. If @a generate_nonce is
* non-zero, the request will contain a random nonce.
*
* The request will be allocated from @a result_pool.
*
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure, e.g., if @a issuer_cert is not the
* issuer certificate of @a server_cert.
*
* @since New in 1.5.
*/
serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_create(
const serf_ssl_certificate_t *server_cert,
const serf_ssl_certificate_t *issuer_cert,
int generate_nonce,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Returns an pointer to the DER-encoded OCSP request
* body within the @a ocsp_request structure.
*
* The application must decide whether to use this data as the body of
* an HTTP POST request or Base64-encoded as part of the URI for a GET
* request; see RFC 2560, section A.1.1.
*
* @see serf_ssl_ocsp_request_body_size()
*
* @since New in 1.5.
*/
const void *serf_ssl_ocsp_request_body(
const serf_ssl_ocsp_request_t *ocsp_request);
/**
* Returns the size of the DER-encoded OCSP request body.
* @see serf_ssl_ocsp_request_body().
*
* @since New in 1.5.
*/
apr_size_t serf_ssl_ocsp_request_body_size(
const serf_ssl_ocsp_request_t *ocsp_request);
/**
* Export @a ocsp_request to a zero-terminated string,
* allocated from @a result_pool.
*
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
*
* @since New in 1.5.
*/
const char *serf_ssl_ocsp_request_export(
const serf_ssl_ocsp_request_t *ocsp_request,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Create an OCSP request from a previously exported zero-terminated
* string @a encoded_ocsp_request. The returned request will be
* allocated from @a result_pool.
*
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
*
* @since New in 1.5.
*/
serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_import(
const char *encoded_ocsp_request,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Internal representation of an OCSP response.
*
* @since New in 1.5.
*/
typedef struct serf_ssl_ocsp_response_t serf_ssl_ocsp_response_t;
/**
* Parse the body of an OCSP response in DER form, @a ocsp_response,
* of size @a ocsp_response_size, and construct an internal
* representation, allocated from @a result_pool.
*
* If @a failures is not @c NULL, it will be set as in
* #serf_ssl_need_server_cert_t.
*
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
*
* @since New in 1.5.
*/
serf_ssl_ocsp_response_t *serf_ssl_ocsp_response_parse(
const void *ocsp_response,
apr_size_t ocsp_response_size,
int *failures,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/**
* Check if the given @a ocsp_response is valid for the given
* @a ocsp_request in the provided @a ssl_ctx, as defined by
* the algorithm documented in RFC 2560, section 3.5.
*
* The OCSP responder and application wall clocks may be out of sync
* by @a clock_skew, and @a max_age is the acceptable age of the
* request. Their values are truncated to the nearest second.
*
* The returned value will be:
*
* - APR_SUCCESS,
* if all steps of the verification succeeded;
* - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED,
* if the certificate was revoked;
* - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN,
* if the responder knows nothing about the certificate;
* - SERF_ERROR_SSL_OCSP_RESPONSE_INVALID,
* if the response itself is invalid or not well-formed.
*
* The @a this_update and @a next_update output arguments are
* described in RFC 2560, section 2.4 and, when not @c NULL and if the
* verificateion succeeded, will be parsed from the response. Any of
* these times that are not present in the response will be set to the
* epoch, i.e., @c APR_TIME_C(0).
*
* Uses @a scratch_pool for temporary allocations.
*
* @since New in 1.5.
*/
apr_status_t serf_ssl_ocsp_response_verify(
serf_ssl_context_t *ssl_ctx,
const serf_ssl_ocsp_response_t *ocsp_response,
const serf_ssl_ocsp_request_t *ocsp_request,
apr_time_t clock_skew,
apr_time_t max_age,
apr_time_t *this_update,
apr_time_t *next_update,
apr_pool_t *scratch_pool);
/* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_ssl_encrypt;
#define SERF_BUCKET_IS_SSL_ENCRYPT(b) SERF_BUCKET_CHECK((b), ssl_encrypt)
/**
* Create an SSL encryption bucket that wraps @a stream.
*
* If @a ssl_context is not provided, a new one will be created.
*/
serf_bucket_t *serf_bucket_ssl_encrypt_create( serf_bucket_t *serf_bucket_ssl_encrypt_create(
serf_bucket_t *stream, serf_bucket_t *stream,
serf_ssl_context_t *ssl_context, serf_ssl_context_t *ssl_context,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/**
* Return the SSL context from an encryption bucket.
*/
serf_ssl_context_t *serf_bucket_ssl_encrypt_context_get( serf_ssl_context_t *serf_bucket_ssl_encrypt_context_get(
serf_bucket_t *bucket); serf_bucket_t *bucket);
/* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_ssl_decrypt; extern const serf_bucket_type_t serf_bucket_type_ssl_decrypt;
#define SERF_BUCKET_IS_SSL_DECRYPT(b) SERF_BUCKET_CHECK((b), ssl_decrypt) #define SERF_BUCKET_IS_SSL_DECRYPT(b) SERF_BUCKET_CHECK((b), ssl_decrypt)
/**
* Create an SSL encryption bucket that wraps @a stream.
*
* If @a ssl_context is not provided, a new one will be created.
*/
serf_bucket_t *serf_bucket_ssl_decrypt_create( serf_bucket_t *serf_bucket_ssl_decrypt_create(
serf_bucket_t *stream, serf_bucket_t *stream,
serf_ssl_context_t *ssl_context, serf_ssl_context_t *ssl_context,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/**
* Return the SSL context from an decryption bucket.
*/
serf_ssl_context_t *serf_bucket_ssl_decrypt_context_get( serf_ssl_context_t *serf_bucket_ssl_decrypt_context_get(
serf_bucket_t *bucket); serf_bucket_t *bucket);
/**
* Configure the SSL context to use the error cllback set on @a ctx.
*
* By default, new SSL contexts send error messages to the global
* error callback.
*
* @see serf_global_error_callback_set()
* @see serf_context_error_callback_set()
*
* @since New in 1.5.
*/
void serf_ssl_use_context_error_callback(serf_ssl_context_t *ssl_ctx,
serf_context_t *ctx);
/**
* Configure the SSL context to use the error callback set on @a conn.
*
* By default, new SSL contexts send error messages to the global
* error callback.
*
* @see serf_global_error_callback_set()
* @see serf_connection_error_callback_set()
*
* @since New in 1.5.
*/
void serf_ssl_use_connection_error_callback(serf_ssl_context_t *ssl_ctx,
serf_connection_t *conn);
/**
* Configure the SSL context to use the error callback set on @a client.
*
* By default, new SSL contexts send error messages to the global
* error callback.
*
* @see serf_global_error_callback_set()
* @see serf_incoming_error_callback_set()
*
* @since New in 1.5.
*/
void serf_ssl_use_incoming_error_callback(serf_ssl_context_t *ssl_ctx,
serf_incoming_t *client);
/* ==================================================================== */ /* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_barrier; extern const serf_bucket_type_t serf_bucket_type_barrier;
#define SERF_BUCKET_IS_BARRIER(b) SERF_BUCKET_CHECK((b), barrier) #define SERF_BUCKET_IS_BARRIER(b) SERF_BUCKET_CHECK((b), barrier)
serf_bucket_t *serf_bucket_barrier_create( serf_bucket_t *serf_bucket_barrier_create(
serf_bucket_t *stream, serf_bucket_t *stream,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* ==================================================================== */ /* ==================================================================== */
skipping to change at line 661 skipping to change at line 1079
extern const serf_bucket_type_t serf_bucket_type_iovec; extern const serf_bucket_type_t serf_bucket_type_iovec;
#define SERF_BUCKET_IS_IOVEC(b) SERF_BUCKET_CHECK((b), iovec) #define SERF_BUCKET_IS_IOVEC(b) SERF_BUCKET_CHECK((b), iovec)
serf_bucket_t *serf_bucket_iovec_create( serf_bucket_t *serf_bucket_iovec_create(
struct iovec vecs[], struct iovec vecs[],
int len, int len,
serf_bucket_alloc_t *allocator); serf_bucket_alloc_t *allocator);
/* ==================================================================== */ /* ==================================================================== */
extern const serf_bucket_type_t serf_bucket_type_copy;
#define SERF_BUCKET_IS_COPY(b) SERF_BUCKET_CHECK((b), copy)
serf_bucket_t *serf_bucket_copy_create(
serf_bucket_t *wrapped,
apr_size_t min_size,
serf_bucket_alloc_t *allocator);
/* ==================================================================== */
/* Reads a specific number of bytes from an inner bucket and forwards that
to a callback, before reading the rest of the bucket normally.
If the internal bucket is at EOF before the prefix length is read, the
callback is called with whatever is read before returning EOF.
*/
extern const serf_bucket_type_t serf_bucket_type_prefix;
#define SERF_BUCKET_IS_PREFIX(b) SERF_BUCKET_CHECK((b), prefix)
/* Callback for the prefix handler */
typedef apr_status_t (*serf_bucket_prefix_handler_t)(
void *baton,
serf_bucket_t *stream,
const char *data,
apr_size_t len);
serf_bucket_t *serf_bucket_prefix_create(
serf_bucket_t *stream,
apr_size_t prefix_len,
serf_bucket_prefix_handler_t handler,
void *handler_baton,
serf_bucket_alloc_t *allocator);
/* ==================================================================== */
/**
* Creates two buckets, *HEAD and *TAIL, which together contain the output
* of STREAM. If there is enough data in STREAM, HEAD will be a bucket of a
t
* least MIN_CHUNK_SIZE and will never be larger than MAX_CHUNK_SIZE.
*
* If STREAM is at EOF before MIN_CHUNK_SIZE, HEAD will contain the data,
* while TAIL is immediately at EOF.
*
* HEAD and TAIL will make sure that data read from TAIL will not break the
* data availability promises on HEAD. Passing an existing tail of this
* function as new stream may be handled specifically, but the read promise
s
* on all nodes ahead of stream will still hold.
*
* HEAD and TAIL are allocated in STREAM->allocator. STREAM will be
* destroyed when no longer referenced or after EOF.
*
* @since New in 1.5.
*/
void serf_bucket_split_create(serf_bucket_t **head,
serf_bucket_t **tail,
serf_bucket_t *stream,
apr_size_t min_chunk_size,
apr_size_t max_chunk_size);
/**
* Check if Serf bucket functions support Brotli (RFC 7932) format.
* Return non-zero if Brotli is supported and zero otherwise. If Brotli
* is not supported, the behavior of all related bucket functions such
* as @a serf_bucket_brotli_decompress_create is undefined.
*
* @since New in 1.5.
*/
int serf_bucket_is_brotli_supported(void);
/** @since New in 1.5. */
extern const serf_bucket_type_t serf_bucket_type_brotli_decompress;
/** @since New in 1.5. */
#define SERF_BUCKET_IS_BROTLI_DECOMPRESS(b) \
SERF_BUCKET_CHECK((b), brotli_decompress)
/** @since New in 1.5. */
serf_bucket_t *
serf_bucket_brotli_decompress_create(serf_bucket_t *stream,
serf_bucket_alloc_t *alloc);
/* ### do we need a PIPE bucket type? they are simple apr_file_t objects */ /* ### do we need a PIPE bucket type? they are simple apr_file_t objects */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif /* !SERF_BUCKET_TYPES_H */ #endif /* !SERF_BUCKET_TYPES_H */
 End of changes. 30 change blocks. 
35 lines changed or deleted 543 lines changed or added


 serf_bucket_util.h (1.3.10)   serf_bucket_util.h (current) 
skipping to change at line 63 skipping to change at line 63
* then return it in the iovec. * then return it in the iovec.
*/ */
apr_status_t serf_default_read_iovec( apr_status_t serf_default_read_iovec(
serf_bucket_t *bucket, serf_bucket_t *bucket,
apr_size_t requested, apr_size_t requested,
int vecs_size, int vecs_size,
struct iovec *vecs, struct iovec *vecs,
int *vecs_used); int *vecs_used);
/** /**
* Default implementation of the @see readline functionality.
*
* This function will use the @see read function, when possible optimized b
y
* the @a peek function to return the requested result.
*
* @since New in 1.5.
*/
apr_status_t serf_default_readline(serf_bucket_t *bucket, int acceptable,
int *found,
const char **data, apr_size_t *len);
/**
* Default implementation of the @see read_for_sendfile functionality. * Default implementation of the @see read_for_sendfile functionality.
* *
* This function will use the @see read function to get a block of memory, * This function will use the @see read function to get a block of memory,
* then return it as a header. No file will be returned. * then return it as a header. No file will be returned.
*/ */
apr_status_t serf_default_read_for_sendfile( apr_status_t serf_default_read_for_sendfile(
serf_bucket_t *bucket, serf_bucket_t *bucket,
apr_size_t requested, apr_size_t requested,
apr_hdtr_t *hdtr, apr_hdtr_t *hdtr,
apr_file_t **file, apr_file_t **file,
skipping to change at line 87 skipping to change at line 99
* Default implementation of the @see read_bucket functionality. * Default implementation of the @see read_bucket functionality.
* *
* This function will always return NULL, indicating that the @a type * This function will always return NULL, indicating that the @a type
* of bucket cannot be found within @a bucket. * of bucket cannot be found within @a bucket.
*/ */
serf_bucket_t *serf_default_read_bucket( serf_bucket_t *serf_default_read_bucket(
serf_bucket_t *bucket, serf_bucket_t *bucket,
const serf_bucket_type_t *type); const serf_bucket_type_t *type);
/** /**
* Default implementation of the @see peek functionality.
*
* This function will always state that there is no data available.
*
* @since New in 1.5.
*/
apr_status_t serf_default_peek(
serf_bucket_t *bucket,
const char **data,
apr_size_t *len);
/**
* Default implementation of the @see destroy functionality. * Default implementation of the @see destroy functionality.
* *
* This function will return the @a bucket to its allcoator. * This function will return the @a bucket to its allocator.
*/ */
void serf_default_destroy( void serf_default_destroy(
serf_bucket_t *bucket); serf_bucket_t *bucket);
/** /**
* Default implementation of the @see destroy functionality. * Default implementation of the @see destroy functionality.
* *
* This function will return the @a bucket, and the data member to its * This function will return the @a bucket, and the data member to its
* allocator. * allocator.
*/ */
void serf_default_destroy_and_data( void serf_default_destroy_and_data(
serf_bucket_t *bucket); serf_bucket_t *bucket);
/** /**
* Implementation of a limited @see readline functionality.
*
* This function will use the @see read function, when possible optimized b
y
* the @a peek function to return the requested result.
*
* @since New in 1.5.
*/
apr_status_t serf_bucket_limited_readline(serf_bucket_t *bucket, int accept
able,
apr_size_t requested, int *found,
const char **data, apr_size_t *le
n);
/**
* Default implementation of the @see get_remaining functionality.
*
* This function will just return SERF_LENGTH_UNKNOWN.
*
* @since New in 1.5.
*/
apr_uint64_t serf_default_get_remaining(
serf_bucket_t *bucket);
/**
* Default implementation of the @see set_config functionality.
*
* This function will not do anything, it should be used in buckets
* that have no use for the shared config, and do not wrap other bucket(s).
*
* @since New in 1.5.
*/
apr_status_t serf_default_ignore_config(serf_bucket_t *bucket,
serf_config_t *config);
/**
* Allocate @a size bytes of memory using @a allocator. * Allocate @a size bytes of memory using @a allocator.
* *
* Returns NULL of the requested memory size could not be allocated. * Returns NULL of the requested memory size could not be allocated.
*/ */
void *serf_bucket_mem_alloc( void *serf_bucket_mem_alloc(
serf_bucket_alloc_t *allocator, serf_bucket_alloc_t *allocator,
apr_size_t size); apr_size_t size);
/** /**
* Allocate @a size bytes of memory using @a allocator and set all of the * Allocate @a size bytes of memory using @a allocator and set all of the
skipping to change at line 223 skipping to change at line 280
apr_size_t *len); apr_size_t *len);
/** /**
* This structure is used as an intermediate data buffer for some "external " * This structure is used as an intermediate data buffer for some "external "
* source of data. It works as a scratch pad area for incoming data to be * source of data. It works as a scratch pad area for incoming data to be
* stored, and then returned as a ptr/len pair by the bucket read functions . * stored, and then returned as a ptr/len pair by the bucket read functions .
* *
* This structure should be initialized by calling @see serf_databuf_init. * This structure should be initialized by calling @see serf_databuf_init.
* Users should not bother to zero the structure beforehand. * Users should not bother to zero the structure beforehand.
*/ */
typedef struct { typedef struct serf_databuf_t {
/** The current data position within the buffer. */ /** The current data position within the buffer. */
const char *current; const char *current;
/** Amount of data remaining in the buffer. */ /** Amount of data remaining in the buffer. */
apr_size_t remaining; apr_size_t remaining;
/** Callback function. */ /** Callback function. */
serf_databuf_reader_t read; serf_databuf_reader_t read;
/** A baton to hold context-specific data. */ /** A baton to hold context-specific data. */
skipping to change at line 293 skipping to change at line 350
*/ */
apr_status_t serf_databuf_peek( apr_status_t serf_databuf_peek(
serf_databuf_t *databuf, serf_databuf_t *databuf,
const char **data, const char **data,
apr_size_t *len); apr_size_t *len);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif /* !SERF_BUCKET_UTIL_H */ #endif /* !SERF_BUCKET_UTIL_H */
 End of changes. 6 change blocks. 
2 lines changed or deleted 63 lines changed or added

This html diff was produced by rfcdiff 1.41.The latest version is available from http://tools.ietf.org/tools/rfcdiff/