1 /* Copyright 2002-2004 Justin Erenkrantz and Greg Stein
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
21 * @brief Main serf header file
25 #include <apr_errno.h>
26 #include <apr_allocator.h>
27 #include <apr_pools.h>
28 #include <apr_network_io.h>
37 /* Forward declare some structures */
38 typedef struct serf_context_t serf_context_t;
40 typedef struct serf_bucket_t serf_bucket_t;
41 typedef struct serf_bucket_type_t serf_bucket_type_t;
42 typedef struct serf_bucket_alloc_t serf_bucket_alloc_t;
44 typedef struct serf_connection_t serf_connection_t;
45 typedef struct serf_listener_t serf_listener_t;
46 typedef struct serf_incoming_t serf_incoming_t;
47 typedef struct serf_incoming_request_t serf_incoming_request_t;
49 typedef struct serf_request_t serf_request_t;
53 * @defgroup serf high-level constructs
59 * Serf-specific error codes
61 #define SERF_ERROR_RANGE 100
62 #define SERF_ERROR_START (APR_OS_START_USERERR + SERF_ERROR_RANGE)
64 /* This code is for when this is the last response on this connection:
65 * i.e. do not send any more requests on this connection or expect
68 #define SERF_ERROR_CLOSING (SERF_ERROR_START + 1)
69 /* This code is for when the connection terminated before the request
70 * could be processed on the other side.
72 #define SERF_ERROR_REQUEST_LOST (SERF_ERROR_START + 2)
73 /* This code is for when the connection is blocked - we can not proceed
74 * until something happens - generally due to SSL negotiation-like behavior
75 * where a write() is blocked until a read() is processed.
77 #define SERF_ERROR_WAIT_CONN (SERF_ERROR_START + 3)
78 /* This code is for when something went wrong during deflating compressed
79 * data e.g. a CRC error. */
80 #define SERF_ERROR_DECOMPRESSION_FAILED (SERF_ERROR_START + 4)
81 /* This code is for when a response received from a http server is not in
82 * http-compliant syntax. */
83 #define SERF_ERROR_BAD_HTTP_RESPONSE (SERF_ERROR_START + 5)
84 /* The server sent less data than what was announced. */
85 #define SERF_ERROR_TRUNCATED_HTTP_RESPONSE (SERF_ERROR_START + 6)
86 /* The proxy server returned an error while setting up the SSL tunnel. */
87 #define SERF_ERROR_SSLTUNNEL_SETUP_FAILED (SERF_ERROR_START + 7)
88 /* The server unexpectedly closed the connection prematurely. */
89 #define SERF_ERROR_ABORTED_CONNECTION (SERF_ERROR_START + 8)
91 /* SSL certificates related errors */
92 #define SERF_ERROR_SSL_CERT_FAILED (SERF_ERROR_START + 70)
94 /* SSL communications related errors */
95 #define SERF_ERROR_SSL_COMM_FAILED (SERF_ERROR_START + 71)
97 /* General authentication related errors */
98 #define SERF_ERROR_AUTHN_FAILED (SERF_ERROR_START + 90)
100 /* None of the available authn mechanisms for the request are supported */
101 #define SERF_ERROR_AUTHN_NOT_SUPPORTED (SERF_ERROR_START + 91)
103 /* Authn was requested by the server but the header lacked some attribute */
104 #define SERF_ERROR_AUTHN_MISSING_ATTRIBUTE (SERF_ERROR_START + 92)
106 /* Authentication handler initialization related errors */
107 #define SERF_ERROR_AUTHN_INITALIZATION_FAILED (SERF_ERROR_START + 93)
109 /* Error code reserved for use in the test suite. */
110 #define SERF_ERROR_ISSUE_IN_TESTSUITE (SERF_ERROR_START + 99)
112 /* This macro groups errors potentially raised when reading a http response. */
113 #define SERF_BAD_RESPONSE_ERROR(status) ((status) \
114 && ((SERF_ERROR_DECOMPRESSION_FAILED == (status)) \
115 ||(SERF_ERROR_BAD_HTTP_RESPONSE == (status)) \
116 ||(SERF_ERROR_TRUNCATED_HTTP_RESPONSE == (status))))
119 * Return a string that describes the specified error code.
121 * If the error code is not one of the above Serf error codes, then
122 * NULL will be returned.
124 * Note regarding lifetime: the string is a statically-allocated constant
126 const char *serf_error_string(apr_status_t errcode);
130 * Create a new context for serf operations.
132 * A serf context defines a control loop which processes multiple
133 * connections simultaneously.
135 * The context will be allocated within @a pool.
137 serf_context_t *serf_context_create(
141 * Callback function. Add a socket to the externally managed poll set.
143 * Both @a pfd and @a serf_baton should be used when calling serf_event_trigger
146 typedef apr_status_t (*serf_socket_add_t)(
152 * Callback function. Remove the socket, identified by both @a pfd and
153 * @a serf_baton from the externally managed poll set.
155 typedef apr_status_t (*serf_socket_remove_t)(
160 /* Create a new context for serf operations.
162 * Use this function to make serf not use its internal control loop, but
163 * instead rely on an external event loop. Serf will use the @a addf and @a rmf
164 * callbacks to notify of any event on a connection. The @a user_baton will be
165 * passed through the addf and rmf callbacks.
167 * The context will be allocated within @a pool.
169 serf_context_t *serf_context_create_ex(
171 serf_socket_add_t addf,
172 serf_socket_remove_t rmf,
176 * Make serf process events on a connection, identified by both @a pfd and
179 * Any outbound data is delivered, and incoming data is made available to
180 * the associated response handlers and their buckets.
182 * If any data is processed (incoming or outgoing), then this function will
183 * return with APR_SUCCESS.
185 apr_status_t serf_event_trigger(
188 const apr_pollfd_t *pfd);
190 /** @see serf_context_run should not block at all. */
191 #define SERF_DURATION_NOBLOCK 0
192 /** @see serf_context_run should run for (nearly) "forever". */
193 #define SERF_DURATION_FOREVER 2000000000 /* approx 1^31 */
196 * Run the main networking control loop.
198 * The set of connections defined by the serf context @a ctx are processed.
199 * Any outbound data is delivered, and incoming data is made available to
200 * the associated response handlers and their buckets. This function will
201 * block on the network for no longer than @a duration microseconds.
203 * If any data is processed (incoming or outgoing), then this function will
204 * return with APR_SUCCESS. Typically, the caller will just want to call it
205 * again to continue processing data.
207 * If no activity occurs within the specified timeout duration, then
208 * APR_TIMEUP is returned.
210 * All temporary allocations will be made in @a pool.
212 apr_status_t serf_context_run(
214 apr_short_interval_time_t duration,
218 apr_status_t serf_context_prerun(
219 serf_context_t *ctx);
222 * Callback function for progress information. @a progress indicates cumulative
223 * number of bytes read or written, for the whole context.
225 typedef void (*serf_progress_t)(
226 void *progress_baton,
231 * Sets the progress callback function. @a progress_func will be called every
232 * time bytes are read of or written on a socket.
234 void serf_context_set_progress_cb(
236 const serf_progress_t progress_func,
237 void *progress_baton);
242 * @defgroup serf connections and requests
248 * When a connection is established, the application needs to wrap some
249 * buckets around @a skt to enable serf to process incoming responses. This
250 * is the control point for assembling connection-level processing logic
251 * around the given socket.
253 * The @a setup_baton is the baton established at connection creation time.
255 * This callback corresponds to reading from the server. Since this is an
256 * on-demand activity, we use a callback. The corresponding write operation
257 * is based on the @see serf_request_deliver function, where the application
258 * can assemble the appropriate bucket(s) before delivery.
260 * The returned bucket should live at least as long as the connection itself.
261 * It is assumed that an appropriate allocator is passed in @a setup_baton.
262 * ### we may want to create a connection-level allocator and pass that
263 * ### along. however, that allocator would *only* be used for this
264 * ### callback. it may be wasteful to create a per-conn allocator, so this
265 * ### baton-based, app-responsible form might be best.
267 * Responsibility for the buckets is passed to the serf library. They will be
268 * destroyed when the connection is closed.
270 * All temporary allocations should be made in @a pool.
272 typedef apr_status_t (*serf_connection_setup_t)(
274 serf_bucket_t **read_bkt,
275 serf_bucket_t **write_bkt,
280 * ### need to update docco w.r.t socket. became "stream" recently.
281 * ### the stream does not have a barrier, this callback should generally
282 * ### add a barrier around the stream before incorporating it into a
283 * ### response bucket stack.
284 * ### should serf add the barrier automatically to protect its data
285 * ### structure? i.e. the passed bucket becomes owned rather than
286 * ### borrowed. that might suit overall semantics better.
287 * Accept an incoming response for @a request, and its @a socket. A bucket
288 * for the response should be constructed and returned. This is the control
289 * point for assembling the appropriate wrapper buckets around the socket to
290 * enable processing of the incoming response.
292 * The @a acceptor_baton is the baton provided when the specified request
295 * The request's pool and bucket allocator should be used for any allocations
296 * that need to live for the duration of the response. Care should be taken
297 * to bound the amount of memory stored in this pool -- to ensure that
298 * allocations are not proportional to the amount of data in the response.
300 * Responsibility for the bucket is passed to the serf library. It will be
301 * destroyed when the response has been fully read (the bucket returns an
302 * APR_EOF status from its read functions).
304 * All temporary allocations should be made in @a pool.
306 /* ### do we need to return an error? */
307 typedef serf_bucket_t * (*serf_response_acceptor_t)(
308 serf_request_t *request,
309 serf_bucket_t *stream,
310 void *acceptor_baton,
314 * Notification callback for when a connection closes.
316 * This callback is used to inform an application that the @a conn
317 * connection has been (abnormally) closed. The @a closed_baton is the
318 * baton provided when the connection was first opened. The reason for
319 * closure is given in @a why, and will be APR_SUCCESS if the application
320 * requested closure (by clearing the pool used to allocate this
321 * connection or calling serf_connection_close).
323 * All temporary allocations should be made in @a pool.
325 typedef void (*serf_connection_closed_t)(
326 serf_connection_t *conn,
332 * Response data has arrived and should be processed.
334 * Whenever response data for @a request arrives (initially, or continued data
335 * arrival), this handler is invoked. The response data is available in the
336 * @a response bucket. The @a handler_baton is passed along from the baton
337 * provided by the request setup callback (@see serf_request_setup_t).
339 * The handler MUST process data from the @a response bucket until the
340 * bucket's read function states it would block (see APR_STATUS_IS_EAGAIN).
341 * The handler is invoked only when new data arrives. If no further data
342 * arrives, and the handler does not process all available data, then the
343 * system can result in a deadlock around the unprocessed, but read, data.
345 * The handler should return APR_EOF when the response has been fully read.
346 * If calling the handler again would block, APR_EAGAIN should be returned.
347 * If the handler should be invoked again, simply return APR_SUCCESS.
349 * Note: if the connection closed (at the request of the application, or
350 * because of an (abnormal) termination) while a request is being delivered,
351 * or before a response arrives, then @a response will be NULL. This is the
352 * signal that the request was not delivered properly, and no further
353 * response should be expected (this callback will not be invoked again).
354 * If a request is injected into the connection (during this callback's
355 * execution, or otherwise), then the connection will be reopened.
357 * All temporary allocations should be made in @a pool.
359 typedef apr_status_t (*serf_response_handler_t)(
360 serf_request_t *request,
361 serf_bucket_t *response,
366 * Callback function to be implemented by the application, so that serf
367 * can handle server and proxy authentication.
368 * code = 401 (server) or 407 (proxy).
369 * baton = the baton passed to serf_context_run.
370 * authn_type = one of "Basic", "Digest".
372 typedef apr_status_t (*serf_credentials_callback_t)(
375 serf_request_t *request, void *baton,
376 int code, const char *authn_type,
381 * Create a new connection associated with the @a ctx serf context.
383 * If no proxy server is configured, a connection will be created to
384 * (eventually) connect to the address specified by @a address. The address must
385 * live at least as long as @a pool (thus, as long as the connection object).
386 * If a proxy server is configured, @address will be ignored.
388 * The connection object will be allocated within @a pool. Clearing or
389 * destroying this pool will close the connection, and terminate any
390 * outstanding requests or responses.
392 * When the connection is closed (upon request or because of an error),
393 * then the @a closed callback is invoked, and @a closed_baton is passed.
395 * ### doc on setup(_baton). tweak below comment re: acceptor.
396 * NULL may be passed for @a acceptor and @a closed; default implementations
399 * Note: the connection is not made immediately. It will be opened on
400 * the next call to @see serf_context_run.
402 serf_connection_t *serf_connection_create(
404 apr_sockaddr_t *address,
405 serf_connection_setup_t setup,
407 serf_connection_closed_t closed,
412 * Create a new connection associated with the @a ctx serf context.
414 * A connection will be created to (eventually) connect to the address
415 * specified by @a address. The address must live at least as long as
416 * @a pool (thus, as long as the connection object).
418 * The host address will be looked up based on the hostname in @a host_info.
420 * The connection object will be allocated within @a pool. Clearing or
421 * destroying this pool will close the connection, and terminate any
422 * outstanding requests or responses.
424 * When the connection is closed (upon request or because of an error),
425 * then the @a closed callback is invoked, and @a closed_baton is passed.
427 * ### doc on setup(_baton). tweak below comment re: acceptor.
428 * NULL may be passed for @a acceptor and @a closed; default implementations
431 * Note: the connection is not made immediately. It will be opened on
432 * the next call to @see serf_context_run.
434 apr_status_t serf_connection_create2(
435 serf_connection_t **conn,
438 serf_connection_setup_t setup,
440 serf_connection_closed_t closed,
445 typedef apr_status_t (*serf_accept_client_t)(
449 apr_socket_t *insock,
452 apr_status_t serf_listener_create(
453 serf_listener_t **listener,
458 serf_accept_client_t accept_func,
461 typedef apr_status_t (*serf_incoming_request_cb_t)(
463 serf_incoming_request_t *req,
467 apr_status_t serf_incoming_create(
468 serf_incoming_t **client,
470 apr_socket_t *insock,
472 serf_incoming_request_cb_t request,
479 * Reset the connection, but re-open the socket again.
481 apr_status_t serf_connection_reset(
482 serf_connection_t *conn);
485 * Close the connection associated with @a conn and cancel all pending requests.
487 * The closed callback passed to serf_connection_create() will be invoked
490 apr_status_t serf_connection_close(
491 serf_connection_t *conn);
494 * Sets the maximum number of outstanding requests @a max_requests on the
495 * connection @a conn. Setting max_requests to 0 means unlimited (the default).
496 * Ex.: setting max_requests to 1 means a request is sent when a response on the
497 * previous request was received and handled.
499 * In general, serf tends to take around 16KB per outstanding request.
501 void serf_connection_set_max_outstanding_requests(
502 serf_connection_t *conn,
503 unsigned int max_requests);
505 void serf_connection_set_async_responses(
506 serf_connection_t *conn,
507 serf_response_acceptor_t acceptor,
508 void *acceptor_baton,
509 serf_response_handler_t handler,
510 void *handler_baton);
513 * Setup the @a request for delivery on its connection.
515 * Right before this is invoked, @a pool will be built within the
516 * connection's pool for the request to use. The associated response will
517 * be allocated within that subpool. An associated bucket allocator will
518 * be built. These items may be fetched from the request object through
519 * @see serf_request_get_pool or @see serf_request_get_alloc.
521 * The content of the request is specified by the @a req_bkt bucket. When
522 * a response arrives, the @a acceptor callback will be invoked (along with
523 * the @a acceptor_baton) to produce a response bucket. That bucket will then
524 * be passed to @a handler, along with the @a handler_baton.
526 * The responsibility for the request bucket is passed to the request
527 * object. When the request is done with the bucket, it will be destroyed.
529 typedef apr_status_t (*serf_request_setup_t)(
530 serf_request_t *request,
532 serf_bucket_t **req_bkt,
533 serf_response_acceptor_t *acceptor,
534 void **acceptor_baton,
535 serf_response_handler_t *handler,
536 void **handler_baton,
540 * Construct a request object for the @a conn connection.
542 * When it is time to deliver the request, the @a setup callback will
543 * be invoked with the @a setup_baton passed into it to complete the
544 * construction of the request object.
546 * If the request has not (yet) been delivered, then it may be canceled
547 * with @see serf_request_cancel.
549 * Invoking any calls other than @see serf_request_cancel before the setup
550 * callback executes is not supported.
552 serf_request_t *serf_connection_request_create(
553 serf_connection_t *conn,
554 serf_request_setup_t setup,
558 * Construct a request object for the @a conn connection, add it in the
559 * list as the next to-be-written request before all unwritten requests.
561 * When it is time to deliver the request, the @a setup callback will
562 * be invoked with the @a setup_baton passed into it to complete the
563 * construction of the request object.
565 * If the request has not (yet) been delivered, then it may be canceled
566 * with @see serf_request_cancel.
568 * Invoking any calls other than @see serf_request_cancel before the setup
569 * callback executes is not supported.
571 serf_request_t *serf_connection_priority_request_create(
572 serf_connection_t *conn,
573 serf_request_setup_t setup,
577 /** Returns detected network latency for the @a conn connection. Negative
578 * value means that latency is unknwon.
580 apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn);
582 /** Check if a @a request has been completely written.
584 * Returns APR_SUCCESS if the request was written completely on the connection.
585 * Returns APR_EBUSY if the request is not yet or partially written.
587 apr_status_t serf_request_is_written(
588 serf_request_t *request);
591 * Cancel the request specified by the @a request object.
593 * If the request has been scheduled for delivery, then its response
594 * handler will be run, passing NULL for the response bucket.
596 * If the request has already been (partially or fully) delivered, then
597 * APR_EBUSY is returned and the request is *NOT* canceled. To properly
598 * cancel the request, the connection must be closed (by clearing or
599 * destroying its associated pool).
601 apr_status_t serf_request_cancel(
602 serf_request_t *request);
605 * Return the pool associated with @a request.
607 * WARNING: be very careful about the kinds of things placed into this
608 * pool. In particular, all allocation should be bounded in size, rather
609 * than proportional to any data stream.
611 apr_pool_t *serf_request_get_pool(
612 const serf_request_t *request);
615 * Return the bucket allocator associated with @a request.
617 serf_bucket_alloc_t *serf_request_get_alloc(
618 const serf_request_t *request);
621 * Return the connection associated with @a request.
623 serf_connection_t *serf_request_get_conn(
624 const serf_request_t *request);
627 * Update the @a handler and @a handler_baton for this @a request.
629 * This can be called after the request has started processing -
630 * subsequent data will be delivered to this new handler.
632 void serf_request_set_handler(
633 serf_request_t *request,
634 const serf_response_handler_t handler,
635 const void **handler_baton);
638 * Configure proxy server settings, to be used by all connections associated
639 * with the @a ctx serf context.
641 * The next connection will be created to connect to the proxy server
642 * specified by @a address. The address must live at least as long as the
645 void serf_config_proxy(
647 apr_sockaddr_t *address);
649 /* Supported authentication types. */
650 #define SERF_AUTHN_NONE 0x00
651 #define SERF_AUTHN_BASIC 0x01
652 #define SERF_AUTHN_DIGEST 0x02
653 #define SERF_AUTHN_NTLM 0x04
654 #define SERF_AUTHN_NEGOTIATE 0x08
655 #define SERF_AUTHN_ALL 0xFF
658 * Define the authentication handlers that serf will try on incoming requests.
660 void serf_config_authn_types(
665 * Set the credentials callback handler.
667 void serf_config_credentials_callback(
669 serf_credentials_callback_t cred_cb);
671 /* ### maybe some connection control functions for flood? */
673 /*** Special bucket creation functions ***/
676 * Create a bucket of type 'socket bucket'.
677 * This is basically a wrapper around @a serf_bucket_socket_create, which
678 * initializes the bucket using connection and/or context specific settings.
680 serf_bucket_t *serf_context_bucket_socket_create(
683 serf_bucket_alloc_t *allocator);
686 * Create a bucket of type 'request bucket'.
687 * This is basically a wrapper around @a serf_bucket_request_create, which
688 * initializes the bucket using request, connection and/or context specific
691 * This function will set following header(s):
692 * - Host: if the connection was created with @a serf_connection_create2.
694 serf_bucket_t *serf_request_bucket_request_create(
695 serf_request_t *request,
699 serf_bucket_alloc_t *allocator);
705 * @defgroup serf buckets
710 /** Pass as REQUESTED to the read function of a bucket to read, consume,
711 * and return all available data.
713 #define SERF_READ_ALL_AVAIL ((apr_size_t)-1)
715 /** Acceptable newline types for bucket->readline(). */
716 #define SERF_NEWLINE_CR 0x0001
717 #define SERF_NEWLINE_CRLF 0x0002
718 #define SERF_NEWLINE_LF 0x0004
719 #define SERF_NEWLINE_ANY 0x0007
721 /** Used to indicate that a newline is not present in the data buffer. */
722 /* ### should we make this zero? */
723 #define SERF_NEWLINE_NONE 0x0008
725 /** Used to indicate that a CR was found at the end of a buffer, and CRLF
726 * was acceptable. It may be that the LF is present, but it needs to be
729 * Note: an alternative to using this symbol would be for callers to see
730 * the SERF_NEWLINE_CR return value, and know that some "end of buffer" was
731 * reached. While this works well for @see serf_util_readline, it does not
732 * necessary work as well for buckets (there is no obvious "end of buffer",
733 * although there is an "end of bucket"). The other problem with that
734 * alternative is that developers might miss the condition. This symbol
735 * calls out the possibility and ensures that callers will watch for it.
737 #define SERF_NEWLINE_CRLF_SPLIT 0x0010
740 struct serf_bucket_type_t {
742 /** name of this bucket type */
746 * Read (and consume) up to @a requested bytes from @a bucket.
748 * A pointer to the data will be returned in @a data, and its length
749 * is specified by @a len.
751 * The data will exist until one of two conditions occur:
753 * 1) this bucket is destroyed
754 * 2) another call to any read function or to peek()
756 * If an application needs the data to exist for a longer duration,
757 * then it must make a copy.
759 apr_status_t (*read)(serf_bucket_t *bucket, apr_size_t requested,
760 const char **data, apr_size_t *len);
763 * Read (and consume) a line of data from @a bucket.
765 * The acceptable forms of a newline are given by @a acceptable, and
766 * the type found is returned in @a found. If a newline is not present
767 * in the returned data, then SERF_NEWLINE_NONE is stored into @a found.
769 * A pointer to the data is returned in @a data, and its length is
770 * specified by @a len. The data will include the newline, if present.
772 * Note that there is no way to limit the amount of data returned
775 * The lifetime of the data is the same as that of the @see read
778 apr_status_t (*readline)(serf_bucket_t *bucket, int acceptable,
780 const char **data, apr_size_t *len);
783 * Read a set of pointer/length pairs from the bucket.
785 * The size of the @a vecs array is specified by @a vecs_size. The
786 * bucket should fill in elements of the array, and return the number
787 * used in @a vecs_used.
789 * Each element of @a vecs should specify a pointer to a block of
790 * data and a length of that data.
792 * The total length of all data elements should not exceed the
793 * amount specified in @a requested.
795 * The lifetime of the data is the same as that of the @see read
798 apr_status_t (*read_iovec)(serf_bucket_t *bucket, apr_size_t requested,
799 int vecs_size, struct iovec *vecs,
803 * Read data from the bucket in a form suitable for apr_socket_sendfile()
805 * On input, hdtr->numheaders and hdtr->numtrailers specify the size
806 * of the hdtr->headers and hdtr->trailers arrays, respectively. The
807 * bucket should fill in the headers and trailers, up to the specified
808 * limits, and set numheaders and numtrailers to the number of iovecs
809 * filled in for each item.
811 * @a file should be filled in with a file that can be read. If a file
812 * is not available or appropriate, then NULL should be stored. The
813 * file offset for the data should be stored in @a offset, and the
814 * length of that data should be stored in @a len. If a file is not
815 * returned, then @a offset and @a len should be ignored.
817 * The file position is not required to correspond to @a offset, and
818 * the caller may manipulate it at will.
820 * The total length of all data elements, and the portion of the
821 * file should not exceed the amount specified in @a requested.
823 * The lifetime of the data is the same as that of the @see read
826 apr_status_t (*read_for_sendfile)(serf_bucket_t *bucket,
827 apr_size_t requested, apr_hdtr_t *hdtr,
828 apr_file_t **file, apr_off_t *offset,
832 * Look within @a bucket for a bucket of the given @a type. The bucket
833 * must be the "initial" data because it will be consumed by this
834 * function. If the given bucket type is available, then read and consume
835 * it, and return it to the caller.
837 * This function is usually used by readers that have custom handling
838 * for specific bucket types (e.g. looking for a file bucket to pass
839 * to apr_socket_sendfile).
841 * If a bucket of the given type is not found, then NULL is returned.
843 * The returned bucket becomes the responsibility of the caller. When
844 * the caller is done with the bucket, it should be destroyed.
846 serf_bucket_t * (*read_bucket)(serf_bucket_t *bucket,
847 const serf_bucket_type_t *type);
850 * Peek, but don't consume, the data in @a bucket.
852 * Since this function is non-destructive, the implicit read size is
853 * SERF_READ_ALL_AVAIL. The caller can then use whatever amount is
856 * The @a data parameter will point to the data, and @a len will
857 * specify how much data is available. The lifetime of the data follows
858 * the same rules as the @see read function above.
860 * Note: if the peek does not return enough data for your particular
861 * use, then you must read/consume some first, then peek again.
863 * If the returned data represents all available data, then APR_EOF
864 * will be returned. Since this function does not consume data, it
865 * can return the same data repeatedly rather than blocking; thus,
866 * APR_EAGAIN will never be returned.
868 apr_status_t (*peek)(serf_bucket_t *bucket,
869 const char **data, apr_size_t *len);
872 * Destroy @a bucket, along with any associated resources.
874 void (*destroy)(serf_bucket_t *bucket);
876 /* ### apr buckets have 'copy', 'split', and 'setaside' functions.
877 ### not sure whether those will be needed in this bucket model.
882 * Should the use and lifecycle of buckets be tracked?
884 * When tracking, the system will ensure several semantic requirements
887 * - if a bucket returns APR_EAGAIN, one of its read functions should
888 * not be called immediately. the context's run loop should be called.
889 * ### and for APR_EOF, too?
890 * - all buckets must be drained of input before returning to the
891 * context's run loop.
892 * - buckets should not be destroyed before they return APR_EOF unless
893 * the connection is closed for some reason.
895 * Undefine this symbol to avoid the tracking (and a performance gain).
897 * ### we may want to examine when/how we provide this. should it always
898 * ### be compiled in? and apps select it before including this header?
900 /* #define SERF_DEBUG_BUCKET_USE */
903 /* Internal macros for tracking bucket use. */
904 #ifdef SERF_DEBUG_BUCKET_USE
905 #define SERF__RECREAD(b,s) serf_debug__record_read(b,s)
907 #define SERF__RECREAD(b,s) (s)
910 #define serf_bucket_read(b,r,d,l) SERF__RECREAD(b, (b)->type->read(b,r,d,l))
911 #define serf_bucket_readline(b,a,f,d,l) \
912 SERF__RECREAD(b, (b)->type->readline(b,a,f,d,l))
913 #define serf_bucket_read_iovec(b,r,s,v,u) \
914 SERF__RECREAD(b, (b)->type->read_iovec(b,r,s,v,u))
915 #define serf_bucket_read_for_sendfile(b,r,h,f,o,l) \
916 SERF__RECREAD(b, (b)->type->read_for_sendfile(b,r,h,f,o,l))
917 #define serf_bucket_read_bucket(b,t) ((b)->type->read_bucket(b,t))
918 #define serf_bucket_peek(b,d,l) ((b)->type->peek(b,d,l))
919 #define serf_bucket_destroy(b) ((b)->type->destroy(b))
922 * Check whether a real error occurred. Note that bucket read functions
923 * can return EOF and EAGAIN as part of their "normal" operation, so they
924 * should not be considered an error.
926 #define SERF_BUCKET_READ_ERROR(status) ((status) \
927 && !APR_STATUS_IS_EOF(status) \
928 && !APR_STATUS_IS_EAGAIN(status) \
929 && (SERF_ERROR_WAIT_CONN != status))
932 struct serf_bucket_t {
934 /** the type of this bucket */
935 const serf_bucket_type_t *type;
937 /** bucket-private data */
940 /** the allocator used for this bucket (needed at destroy time) */
941 serf_bucket_alloc_t *allocator;
946 * Generic macro to construct "is TYPE" macros.
948 #define SERF_BUCKET_CHECK(b, btype) ((b)->type == &serf_bucket_type_ ## btype)
952 * Notification callback for a block that was not returned to the bucket
953 * allocator when its pool was destroyed.
955 * The block of memory is given by @a block. The baton provided when the
956 * allocator was constructed is passed as @a unfreed_baton.
958 typedef void (*serf_unfreed_func_t)(
963 * Create a new allocator for buckets.
965 * All buckets are associated with a serf bucket allocator. This allocator
966 * will be created within @a pool and will be destroyed when that pool is
967 * cleared or destroyed.
969 * When the allocator is destroyed, if any allocations were not explicitly
970 * returned (by calling serf_bucket_mem_free), then the @a unfreed callback
971 * will be invoked for each block. @a unfreed_baton will be passed to the
974 * If @a unfreed is NULL, then the library will invoke the abort() stdlib
975 * call. Any failure to return memory is a bug in the application, and an
976 * abort can assist with determining what kinds of memory were not freed.
978 serf_bucket_alloc_t *serf_bucket_allocator_create(
980 serf_unfreed_func_t unfreed,
981 void *unfreed_baton);
984 * Return the pool that was used for this @a allocator.
986 * WARNING: the use of this pool for allocations requires a very
987 * detailed understanding of pool behaviors, the bucket system,
988 * and knowledge of the bucket's use within the overall pattern
989 * of request/response behavior.
991 * See design-guide.txt for more information about pool usage.
993 apr_pool_t *serf_bucket_allocator_get_pool(
994 const serf_bucket_alloc_t *allocator);
998 * Utility structure for reading a complete line of input from a bucket.
1000 * Since it is entirely possible for a line to be broken by APR_EAGAIN,
1001 * this structure can be used to accumulate the data until a complete line
1002 * has been read from a bucket.
1005 /* This limit applies to the line buffer functions. If an application needs
1006 * longer lines, then they will need to manually handle line buffering.
1008 #define SERF_LINEBUF_LIMIT 8000
1012 /* Current state of the buffer. */
1016 SERF_LINEBUF_PARTIAL,
1017 SERF_LINEBUF_CRLF_SPLIT
1020 /* How much of the buffer have we used? */
1023 /* The line is read into this buffer, minus CR/LF */
1024 char line[SERF_LINEBUF_LIMIT];
1029 * Initialize the @a linebuf structure.
1031 void serf_linebuf_init(serf_linebuf_t *linebuf);
1034 * Fetch a line of text from @a bucket, accumulating the line into
1035 * @a linebuf. @a acceptable specifies the types of newlines which are
1036 * acceptable for this fetch.
1038 * ### we should return a data/len pair so that we can avoid a copy,
1039 * ### rather than having callers look into our state and line buffer.
1041 apr_status_t serf_linebuf_fetch(
1042 serf_linebuf_t *linebuf,
1043 serf_bucket_t *bucket,
1049 /* Internal functions for bucket use and lifecycle tracking */
1050 apr_status_t serf_debug__record_read(
1051 const serf_bucket_t *bucket,
1052 apr_status_t status);
1053 void serf_debug__entered_loop(
1054 serf_bucket_alloc_t *allocator);
1055 void serf_debug__closed_conn(
1056 serf_bucket_alloc_t *allocator);
1057 void serf_debug__bucket_destroy(
1058 const serf_bucket_t *bucket);
1059 void serf_debug__bucket_alloc_check(
1060 serf_bucket_alloc_t *allocator);
1063 #define SERF_MAJOR_VERSION 1
1064 #define SERF_MINOR_VERSION 3
1065 #define SERF_PATCH_VERSION 7
1067 /* Version number string */
1068 #define SERF_VERSION_STRING APR_STRINGIFY(SERF_MAJOR_VERSION) "." \
1069 APR_STRINGIFY(SERF_MINOR_VERSION) "." \
1070 APR_STRINGIFY(SERF_PATCH_VERSION)
1073 * Check at compile time if the Serf version is at least a certain
1075 * @param major The major version component of the version checked
1076 * for (e.g., the "1" of "1.3.0").
1077 * @param minor The minor version component of the version checked
1078 * for (e.g., the "3" of "1.3.0").
1079 * @param patch The patch level component of the version checked
1080 * for (e.g., the "0" of "1.3.0").
1082 #define SERF_VERSION_AT_LEAST(major,minor,patch) \
1083 (((major) < SERF_MAJOR_VERSION) \
1084 || ((major) == SERF_MAJOR_VERSION && (minor) < SERF_MINOR_VERSION) \
1085 || ((major) == SERF_MAJOR_VERSION && (minor) == SERF_MINOR_VERSION && \
1086 (patch) <= SERF_PATCH_VERSION))
1090 * Returns the version of the library the application has linked/loaded.
1091 * Values are returned in @a major, @a minor, and @a patch.
1093 * Applications will want to use this function to verify compatibility,
1094 * expecially while serf has not reached a 1.0 milestone. APIs and
1095 * semantics may change drastically until the library hits 1.0.
1097 void serf_lib_version(
1109 * Every user of serf will want to deal with our various bucket types.
1110 * Go ahead and include that header right now.
1112 * Note: make sure this occurs outside of the C++ namespace block
1114 #include "serf_bucket_types.h"
1117 #endif /* !SERF_H */