serf.h revision 266728
1/* Copyright 2002-2004 Justin Erenkrantz and Greg Stein 2 * 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16#ifndef SERF_H 17#define SERF_H 18 19/** 20 * @file serf.h 21 * @brief Main serf header file 22 */ 23 24#include <apr.h> 25#include <apr_errno.h> 26#include <apr_allocator.h> 27#include <apr_pools.h> 28#include <apr_network_io.h> 29#include <apr_time.h> 30#include <apr_poll.h> 31#include <apr_uri.h> 32 33#ifdef __cplusplus 34extern "C" { 35#endif 36 37/* Forward declare some structures */ 38typedef struct serf_context_t serf_context_t; 39 40typedef struct serf_bucket_t serf_bucket_t; 41typedef struct serf_bucket_type_t serf_bucket_type_t; 42typedef struct serf_bucket_alloc_t serf_bucket_alloc_t; 43 44typedef struct serf_connection_t serf_connection_t; 45typedef struct serf_listener_t serf_listener_t; 46typedef struct serf_incoming_t serf_incoming_t; 47typedef struct serf_incoming_request_t serf_incoming_request_t; 48 49typedef struct serf_request_t serf_request_t; 50 51 52/** 53 * @defgroup serf high-level constructs 54 * @ingroup serf 55 * @{ 56 */ 57 58/** 59 * Serf-specific error codes 60 */ 61#define SERF_ERROR_RANGE 100 62#define SERF_ERROR_START (APR_OS_START_USERERR + SERF_ERROR_RANGE) 63 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 66 * any more responses. 67 */ 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. 71 */ 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. 76 */ 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) 90 91/* SSL certificates related errors */ 92#define SERF_ERROR_SSL_CERT_FAILED (SERF_ERROR_START + 70) 93 94/* SSL communications related errors */ 95#define SERF_ERROR_SSL_COMM_FAILED (SERF_ERROR_START + 71) 96 97/* General authentication related errors */ 98#define SERF_ERROR_AUTHN_FAILED (SERF_ERROR_START + 90) 99 100/* None of the available authn mechanisms for the request are supported */ 101#define SERF_ERROR_AUTHN_NOT_SUPPORTED (SERF_ERROR_START + 91) 102 103/* Authn was requested by the server but the header lacked some attribute */ 104#define SERF_ERROR_AUTHN_MISSING_ATTRIBUTE (SERF_ERROR_START + 92) 105 106/* Authentication handler initialization related errors */ 107#define SERF_ERROR_AUTHN_INITALIZATION_FAILED (SERF_ERROR_START + 93) 108 109/* Error code reserved for use in the test suite. */ 110#define SERF_ERROR_ISSUE_IN_TESTSUITE (SERF_ERROR_START + 99) 111 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)))) 117 118/** 119 * Return a string that describes the specified error code. 120 * 121 * If the error code is not one of the above Serf error codes, then 122 * NULL will be returned. 123 * 124 * Note regarding lifetime: the string is a statically-allocated constant 125 */ 126const char *serf_error_string(apr_status_t errcode); 127 128 129/** 130 * Create a new context for serf operations. 131 * 132 * A serf context defines a control loop which processes multiple 133 * connections simultaneously. 134 * 135 * The context will be allocated within @a pool. 136 */ 137serf_context_t *serf_context_create( 138 apr_pool_t *pool); 139 140/** 141 * Callback function. Add a socket to the externally managed poll set. 142 * 143 * Both @a pfd and @a serf_baton should be used when calling serf_event_trigger 144 * later. 145 */ 146typedef apr_status_t (*serf_socket_add_t)( 147 void *user_baton, 148 apr_pollfd_t *pfd, 149 void *serf_baton); 150 151/** 152 * Callback function. Remove the socket, identified by both @a pfd and 153 * @a serf_baton from the externally managed poll set. 154 */ 155typedef apr_status_t (*serf_socket_remove_t)( 156 void *user_baton, 157 apr_pollfd_t *pfd, 158 void *serf_baton); 159 160/* Create a new context for serf operations. 161 * 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. 166 * 167 * The context will be allocated within @a pool. 168 */ 169serf_context_t *serf_context_create_ex( 170 void *user_baton, 171 serf_socket_add_t addf, 172 serf_socket_remove_t rmf, 173 apr_pool_t *pool); 174 175/** 176 * Make serf process events on a connection, identified by both @a pfd and 177 * @a serf_baton. 178 * 179 * Any outbound data is delivered, and incoming data is made available to 180 * the associated response handlers and their buckets. 181 * 182 * If any data is processed (incoming or outgoing), then this function will 183 * return with APR_SUCCESS. 184 */ 185apr_status_t serf_event_trigger( 186 serf_context_t *s, 187 void *serf_baton, 188 const apr_pollfd_t *pfd); 189 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 */ 194 195/** 196 * Run the main networking control loop. 197 * 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. 202 * 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. 206 * 207 * If no activity occurs within the specified timeout duration, then 208 * APR_TIMEUP is returned. 209 * 210 * All temporary allocations will be made in @a pool. 211 */ 212apr_status_t serf_context_run( 213 serf_context_t *ctx, 214 apr_short_interval_time_t duration, 215 apr_pool_t *pool); 216 217 218apr_status_t serf_context_prerun( 219 serf_context_t *ctx); 220 221/** 222 * Callback function for progress information. @a progress indicates cumulative 223 * number of bytes read or written, for the whole context. 224 */ 225typedef void (*serf_progress_t)( 226 void *progress_baton, 227 apr_off_t read, 228 apr_off_t write); 229 230/** 231 * Sets the progress callback function. @a progress_func will be called every 232 * time bytes are read of or written on a socket. 233 */ 234void serf_context_set_progress_cb( 235 serf_context_t *ctx, 236 const serf_progress_t progress_func, 237 void *progress_baton); 238 239/** @} */ 240 241/** 242 * @defgroup serf connections and requests 243 * @ingroup serf 244 * @{ 245 */ 246 247/** 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. 252 * 253 * The @a setup_baton is the baton established at connection creation time. 254 * 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. 259 * 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. 266 * 267 * Responsibility for the buckets is passed to the serf library. They will be 268 * destroyed when the connection is closed. 269 * 270 * All temporary allocations should be made in @a pool. 271 */ 272typedef apr_status_t (*serf_connection_setup_t)( 273 apr_socket_t *skt, 274 serf_bucket_t **read_bkt, 275 serf_bucket_t **write_bkt, 276 void *setup_baton, 277 apr_pool_t *pool); 278 279/** 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. 291 * 292 * The @a acceptor_baton is the baton provided when the specified request 293 * was created. 294 * 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. 299 * 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). 303 * 304 * All temporary allocations should be made in @a pool. 305 */ 306/* ### do we need to return an error? */ 307typedef serf_bucket_t * (*serf_response_acceptor_t)( 308 serf_request_t *request, 309 serf_bucket_t *stream, 310 void *acceptor_baton, 311 apr_pool_t *pool); 312 313/** 314 * Notification callback for when a connection closes. 315 * 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). 322 * 323 * All temporary allocations should be made in @a pool. 324 */ 325typedef void (*serf_connection_closed_t)( 326 serf_connection_t *conn, 327 void *closed_baton, 328 apr_status_t why, 329 apr_pool_t *pool); 330 331/** 332 * Response data has arrived and should be processed. 333 * 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). 338 * 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. 344 * 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. 348 * 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. 356 * 357 * All temporary allocations should be made in @a pool. 358 */ 359typedef apr_status_t (*serf_response_handler_t)( 360 serf_request_t *request, 361 serf_bucket_t *response, 362 void *handler_baton, 363 apr_pool_t *pool); 364 365/** 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". 371 */ 372typedef apr_status_t (*serf_credentials_callback_t)( 373 char **username, 374 char **password, 375 serf_request_t *request, void *baton, 376 int code, const char *authn_type, 377 const char *realm, 378 apr_pool_t *pool); 379 380/** 381 * Create a new connection associated with the @a ctx serf context. 382 * 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. 387 * 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. 391 * 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. 394 * 395 * ### doc on setup(_baton). tweak below comment re: acceptor. 396 * NULL may be passed for @a acceptor and @a closed; default implementations 397 * will be used. 398 * 399 * Note: the connection is not made immediately. It will be opened on 400 * the next call to @see serf_context_run. 401 */ 402serf_connection_t *serf_connection_create( 403 serf_context_t *ctx, 404 apr_sockaddr_t *address, 405 serf_connection_setup_t setup, 406 void *setup_baton, 407 serf_connection_closed_t closed, 408 void *closed_baton, 409 apr_pool_t *pool); 410 411/** 412 * Create a new connection associated with the @a ctx serf context. 413 * 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). 417 * 418 * The host address will be looked up based on the hostname in @a host_info. 419 * 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. 423 * 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. 426 * 427 * ### doc on setup(_baton). tweak below comment re: acceptor. 428 * NULL may be passed for @a acceptor and @a closed; default implementations 429 * will be used. 430 * 431 * Note: the connection is not made immediately. It will be opened on 432 * the next call to @see serf_context_run. 433 */ 434apr_status_t serf_connection_create2( 435 serf_connection_t **conn, 436 serf_context_t *ctx, 437 apr_uri_t host_info, 438 serf_connection_setup_t setup, 439 void *setup_baton, 440 serf_connection_closed_t closed, 441 void *closed_baton, 442 apr_pool_t *pool); 443 444 445typedef apr_status_t (*serf_accept_client_t)( 446 serf_context_t *ctx, 447 serf_listener_t *l, 448 void *accept_baton, 449 apr_socket_t *insock, 450 apr_pool_t *pool); 451 452apr_status_t serf_listener_create( 453 serf_listener_t **listener, 454 serf_context_t *ctx, 455 const char *host, 456 apr_uint16_t port, 457 void *accept_baton, 458 serf_accept_client_t accept_func, 459 apr_pool_t *pool); 460 461typedef apr_status_t (*serf_incoming_request_cb_t)( 462 serf_context_t *ctx, 463 serf_incoming_request_t *req, 464 void *request_baton, 465 apr_pool_t *pool); 466 467apr_status_t serf_incoming_create( 468 serf_incoming_t **client, 469 serf_context_t *ctx, 470 apr_socket_t *insock, 471 void *request_baton, 472 serf_incoming_request_cb_t request, 473 apr_pool_t *pool); 474 475 476 477 478/** 479 * Reset the connection, but re-open the socket again. 480 */ 481apr_status_t serf_connection_reset( 482 serf_connection_t *conn); 483 484/** 485 * Close the connection associated with @a conn and cancel all pending requests. 486 * 487 * The closed callback passed to serf_connection_create() will be invoked 488 * with APR_SUCCESS. 489 */ 490apr_status_t serf_connection_close( 491 serf_connection_t *conn); 492 493/** 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. 498 * 499 * In general, serf tends to take around 16KB per outstanding request. 500 */ 501void serf_connection_set_max_outstanding_requests( 502 serf_connection_t *conn, 503 unsigned int max_requests); 504 505void 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); 511 512/** 513 * Setup the @a request for delivery on its connection. 514 * 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. 520 * 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. 525 * 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. 528 */ 529typedef apr_status_t (*serf_request_setup_t)( 530 serf_request_t *request, 531 void *setup_baton, 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, 537 apr_pool_t *pool); 538 539/** 540 * Construct a request object for the @a conn connection. 541 * 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. 545 * 546 * If the request has not (yet) been delivered, then it may be canceled 547 * with @see serf_request_cancel. 548 * 549 * Invoking any calls other than @see serf_request_cancel before the setup 550 * callback executes is not supported. 551 */ 552serf_request_t *serf_connection_request_create( 553 serf_connection_t *conn, 554 serf_request_setup_t setup, 555 void *setup_baton); 556 557/** 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. 560 * 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. 564 * 565 * If the request has not (yet) been delivered, then it may be canceled 566 * with @see serf_request_cancel. 567 * 568 * Invoking any calls other than @see serf_request_cancel before the setup 569 * callback executes is not supported. 570 */ 571serf_request_t *serf_connection_priority_request_create( 572 serf_connection_t *conn, 573 serf_request_setup_t setup, 574 void *setup_baton); 575 576 577/** Returns detected network latency for the @a conn connection. Negative 578 * value means that latency is unknwon. 579 */ 580apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn); 581 582/** Check if a @a request has been completely written. 583 * 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. 586 */ 587apr_status_t serf_request_is_written( 588 serf_request_t *request); 589 590/** 591 * Cancel the request specified by the @a request object. 592 * 593 * If the request has been scheduled for delivery, then its response 594 * handler will be run, passing NULL for the response bucket. 595 * 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). 600 */ 601apr_status_t serf_request_cancel( 602 serf_request_t *request); 603 604/** 605 * Return the pool associated with @a request. 606 * 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. 610 */ 611apr_pool_t *serf_request_get_pool( 612 const serf_request_t *request); 613 614/** 615 * Return the bucket allocator associated with @a request. 616 */ 617serf_bucket_alloc_t *serf_request_get_alloc( 618 const serf_request_t *request); 619 620/** 621 * Return the connection associated with @a request. 622 */ 623serf_connection_t *serf_request_get_conn( 624 const serf_request_t *request); 625 626/** 627 * Update the @a handler and @a handler_baton for this @a request. 628 * 629 * This can be called after the request has started processing - 630 * subsequent data will be delivered to this new handler. 631 */ 632void serf_request_set_handler( 633 serf_request_t *request, 634 const serf_response_handler_t handler, 635 const void **handler_baton); 636 637/** 638 * Configure proxy server settings, to be used by all connections associated 639 * with the @a ctx serf context. 640 * 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 643 * serf context. 644 */ 645void serf_config_proxy( 646 serf_context_t *ctx, 647 apr_sockaddr_t *address); 648 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 656 657/** 658 * Define the authentication handlers that serf will try on incoming requests. 659 */ 660void serf_config_authn_types( 661 serf_context_t *ctx, 662 int authn_types); 663 664/** 665 * Set the credentials callback handler. 666 */ 667void serf_config_credentials_callback( 668 serf_context_t *ctx, 669 serf_credentials_callback_t cred_cb); 670 671/* ### maybe some connection control functions for flood? */ 672 673/*** Special bucket creation functions ***/ 674 675/** 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. 679 */ 680serf_bucket_t *serf_context_bucket_socket_create( 681 serf_context_t *ctx, 682 apr_socket_t *skt, 683 serf_bucket_alloc_t *allocator); 684 685/** 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 689 * settings. 690 * 691 * This function will set following header(s): 692 * - Host: if the connection was created with @a serf_connection_create2. 693 */ 694serf_bucket_t *serf_request_bucket_request_create( 695 serf_request_t *request, 696 const char *method, 697 const char *uri, 698 serf_bucket_t *body, 699 serf_bucket_alloc_t *allocator); 700 701/** @} */ 702 703 704/** 705 * @defgroup serf buckets 706 * @ingroup serf 707 * @{ 708 */ 709 710/** Pass as REQUESTED to the read function of a bucket to read, consume, 711 * and return all available data. 712 */ 713#define SERF_READ_ALL_AVAIL ((apr_size_t)-1) 714 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 720 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 724 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 727 * read first. 728 * 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. 736 */ 737#define SERF_NEWLINE_CRLF_SPLIT 0x0010 738 739 740struct serf_bucket_type_t { 741 742 /** name of this bucket type */ 743 const char *name; 744 745 /** 746 * Read (and consume) up to @a requested bytes from @a bucket. 747 * 748 * A pointer to the data will be returned in @a data, and its length 749 * is specified by @a len. 750 * 751 * The data will exist until one of two conditions occur: 752 * 753 * 1) this bucket is destroyed 754 * 2) another call to any read function or to peek() 755 * 756 * If an application needs the data to exist for a longer duration, 757 * then it must make a copy. 758 */ 759 apr_status_t (*read)(serf_bucket_t *bucket, apr_size_t requested, 760 const char **data, apr_size_t *len); 761 762 /** 763 * Read (and consume) a line of data from @a bucket. 764 * 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. 768 * 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. 771 * 772 * Note that there is no way to limit the amount of data returned 773 * by this function. 774 * 775 * The lifetime of the data is the same as that of the @see read 776 * function above. 777 */ 778 apr_status_t (*readline)(serf_bucket_t *bucket, int acceptable, 779 int *found, 780 const char **data, apr_size_t *len); 781 782 /** 783 * Read a set of pointer/length pairs from the bucket. 784 * 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. 788 * 789 * Each element of @a vecs should specify a pointer to a block of 790 * data and a length of that data. 791 * 792 * The total length of all data elements should not exceed the 793 * amount specified in @a requested. 794 * 795 * The lifetime of the data is the same as that of the @see read 796 * function above. 797 */ 798 apr_status_t (*read_iovec)(serf_bucket_t *bucket, apr_size_t requested, 799 int vecs_size, struct iovec *vecs, 800 int *vecs_used); 801 802 /** 803 * Read data from the bucket in a form suitable for apr_socket_sendfile() 804 * 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. 810 * 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. 816 * 817 * The file position is not required to correspond to @a offset, and 818 * the caller may manipulate it at will. 819 * 820 * The total length of all data elements, and the portion of the 821 * file should not exceed the amount specified in @a requested. 822 * 823 * The lifetime of the data is the same as that of the @see read 824 * function above. 825 */ 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, 829 apr_size_t *len); 830 831 /** 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. 836 * 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). 840 * 841 * If a bucket of the given type is not found, then NULL is returned. 842 * 843 * The returned bucket becomes the responsibility of the caller. When 844 * the caller is done with the bucket, it should be destroyed. 845 */ 846 serf_bucket_t * (*read_bucket)(serf_bucket_t *bucket, 847 const serf_bucket_type_t *type); 848 849 /** 850 * Peek, but don't consume, the data in @a bucket. 851 * 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 854 * appropriate. 855 * 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. 859 * 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. 862 * 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. 867 */ 868 apr_status_t (*peek)(serf_bucket_t *bucket, 869 const char **data, apr_size_t *len); 870 871 /** 872 * Destroy @a bucket, along with any associated resources. 873 */ 874 void (*destroy)(serf_bucket_t *bucket); 875 876 /* ### apr buckets have 'copy', 'split', and 'setaside' functions. 877 ### not sure whether those will be needed in this bucket model. 878 */ 879}; 880 881/** 882 * Should the use and lifecycle of buckets be tracked? 883 * 884 * When tracking, the system will ensure several semantic requirements 885 * of bucket use: 886 * 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. 894 * 895 * Undefine this symbol to avoid the tracking (and a performance gain). 896 * 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? 899 */ 900/* #define SERF_DEBUG_BUCKET_USE */ 901 902 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) 906#else 907#define SERF__RECREAD(b,s) (s) 908#endif 909 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)) 920 921/** 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. 925 */ 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)) 930 931 932struct serf_bucket_t { 933 934 /** the type of this bucket */ 935 const serf_bucket_type_t *type; 936 937 /** bucket-private data */ 938 void *data; 939 940 /** the allocator used for this bucket (needed at destroy time) */ 941 serf_bucket_alloc_t *allocator; 942}; 943 944 945/** 946 * Generic macro to construct "is TYPE" macros. 947 */ 948#define SERF_BUCKET_CHECK(b, btype) ((b)->type == &serf_bucket_type_ ## btype) 949 950 951/** 952 * Notification callback for a block that was not returned to the bucket 953 * allocator when its pool was destroyed. 954 * 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. 957 */ 958typedef void (*serf_unfreed_func_t)( 959 void *unfreed_baton, 960 void *block); 961 962/** 963 * Create a new allocator for buckets. 964 * 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. 968 * 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 972 * callback. 973 * 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. 977 */ 978serf_bucket_alloc_t *serf_bucket_allocator_create( 979 apr_pool_t *pool, 980 serf_unfreed_func_t unfreed, 981 void *unfreed_baton); 982 983/** 984 * Return the pool that was used for this @a allocator. 985 * 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. 990 * 991 * See design-guide.txt for more information about pool usage. 992 */ 993apr_pool_t *serf_bucket_allocator_get_pool( 994 const serf_bucket_alloc_t *allocator); 995 996 997/** 998 * Utility structure for reading a complete line of input from a bucket. 999 * 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. 1003 */ 1004 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. 1007 */ 1008#define SERF_LINEBUF_LIMIT 8000 1009 1010typedef struct { 1011 1012 /* Current state of the buffer. */ 1013 enum { 1014 SERF_LINEBUF_EMPTY, 1015 SERF_LINEBUF_READY, 1016 SERF_LINEBUF_PARTIAL, 1017 SERF_LINEBUF_CRLF_SPLIT 1018 } state; 1019 1020 /* How much of the buffer have we used? */ 1021 apr_size_t used; 1022 1023 /* The line is read into this buffer, minus CR/LF */ 1024 char line[SERF_LINEBUF_LIMIT]; 1025 1026} serf_linebuf_t; 1027 1028/** 1029 * Initialize the @a linebuf structure. 1030 */ 1031void serf_linebuf_init(serf_linebuf_t *linebuf); 1032 1033/** 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. 1037 * 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. 1040 */ 1041apr_status_t serf_linebuf_fetch( 1042 serf_linebuf_t *linebuf, 1043 serf_bucket_t *bucket, 1044 int acceptable); 1045 1046/** @} */ 1047 1048 1049/* Internal functions for bucket use and lifecycle tracking */ 1050apr_status_t serf_debug__record_read( 1051 const serf_bucket_t *bucket, 1052 apr_status_t status); 1053void serf_debug__entered_loop( 1054 serf_bucket_alloc_t *allocator); 1055void serf_debug__closed_conn( 1056 serf_bucket_alloc_t *allocator); 1057void serf_debug__bucket_destroy( 1058 const serf_bucket_t *bucket); 1059void serf_debug__bucket_alloc_check( 1060 serf_bucket_alloc_t *allocator); 1061 1062/* Version info */ 1063#define SERF_MAJOR_VERSION 1 1064#define SERF_MINOR_VERSION 3 1065#define SERF_PATCH_VERSION 5 1066 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) 1071 1072/** 1073 * Check at compile time if the Serf version is at least a certain 1074 * level. 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"). 1081 */ 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)) 1087 1088 1089/** 1090 * Returns the version of the library the application has linked/loaded. 1091 * Values are returned in @a major, @a minor, and @a patch. 1092 * 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. 1096 */ 1097void serf_lib_version( 1098 int *major, 1099 int *minor, 1100 int *patch); 1101 1102 1103#ifdef __cplusplus 1104} 1105#endif 1106 1107 1108/* 1109 * Every user of serf will want to deal with our various bucket types. 1110 * Go ahead and include that header right now. 1111 * 1112 * Note: make sure this occurs outside of the C++ namespace block 1113 */ 1114#include "serf_bucket_types.h" 1115 1116 1117#endif /* !SERF_H */ 1118