1/* ==================================================================== 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * ==================================================================== 19 */ 20 21#ifndef SERF_H 22#define SERF_H 23 24/** 25 * @file serf.h 26 * @brief Main serf header file 27 */ 28 29#include <apr.h> 30#include <apr_errno.h> 31#include <apr_allocator.h> 32#include <apr_pools.h> 33#include <apr_network_io.h> 34#include <apr_time.h> 35#include <apr_poll.h> 36#include <apr_uri.h> 37 38#ifdef __cplusplus 39extern "C" { 40#endif 41 42/* Forward declare some structures */ 43typedef struct serf_context_t serf_context_t; 44 45typedef struct serf_bucket_t serf_bucket_t; 46typedef struct serf_bucket_type_t serf_bucket_type_t; 47typedef struct serf_bucket_alloc_t serf_bucket_alloc_t; 48 49typedef struct serf_connection_t serf_connection_t; 50typedef struct serf_listener_t serf_listener_t; 51typedef struct serf_incoming_t serf_incoming_t; 52typedef struct serf_incoming_request_t serf_incoming_request_t; 53 54typedef struct serf_request_t serf_request_t; 55 56 57/** 58 * @defgroup serf high-level constructs 59 * @ingroup serf 60 * @{ 61 */ 62 63/** 64 * Serf-specific error codes 65 */ 66#define SERF_ERROR_RANGE 100 67#define SERF_ERROR_START (APR_OS_START_USERERR + SERF_ERROR_RANGE) 68 69/* This code is for when this is the last response on this connection: 70 * i.e. do not send any more requests on this connection or expect 71 * any more responses. 72 */ 73#define SERF_ERROR_CLOSING (SERF_ERROR_START + 1) 74/* This code is for when the connection terminated before the request 75 * could be processed on the other side. 76 */ 77#define SERF_ERROR_REQUEST_LOST (SERF_ERROR_START + 2) 78/* This code is for when the connection is blocked - we can not proceed 79 * until something happens - generally due to SSL negotiation-like behavior 80 * where a write() is blocked until a read() is processed. 81 */ 82#define SERF_ERROR_WAIT_CONN (SERF_ERROR_START + 3) 83/* This code is for when something went wrong during deflating compressed 84 * data e.g. a CRC error. */ 85#define SERF_ERROR_DECOMPRESSION_FAILED (SERF_ERROR_START + 4) 86/* This code is for when a response received from a http server is not in 87 * http-compliant syntax. */ 88#define SERF_ERROR_BAD_HTTP_RESPONSE (SERF_ERROR_START + 5) 89/* The server sent less data than what was announced. */ 90#define SERF_ERROR_TRUNCATED_HTTP_RESPONSE (SERF_ERROR_START + 6) 91/* The proxy server returned an error while setting up the SSL tunnel. */ 92#define SERF_ERROR_SSLTUNNEL_SETUP_FAILED (SERF_ERROR_START + 7) 93/* The server unexpectedly closed the connection prematurely. */ 94#define SERF_ERROR_ABORTED_CONNECTION (SERF_ERROR_START + 8) 95 96/* SSL certificates related errors */ 97#define SERF_ERROR_SSL_CERT_FAILED (SERF_ERROR_START + 70) 98 99/* SSL communications related errors */ 100#define SERF_ERROR_SSL_COMM_FAILED (SERF_ERROR_START + 71) 101 102/* General authentication related errors */ 103#define SERF_ERROR_AUTHN_FAILED (SERF_ERROR_START + 90) 104 105/* None of the available authn mechanisms for the request are supported */ 106#define SERF_ERROR_AUTHN_NOT_SUPPORTED (SERF_ERROR_START + 91) 107 108/* Authn was requested by the server but the header lacked some attribute */ 109#define SERF_ERROR_AUTHN_MISSING_ATTRIBUTE (SERF_ERROR_START + 92) 110 111/* Authentication handler initialization related errors */ 112#define SERF_ERROR_AUTHN_INITALIZATION_FAILED (SERF_ERROR_START + 93) 113 114/* Error code reserved for use in the test suite. */ 115#define SERF_ERROR_ISSUE_IN_TESTSUITE (SERF_ERROR_START + 99) 116 117/* This macro groups errors potentially raised when reading a http response. */ 118#define SERF_BAD_RESPONSE_ERROR(status) ((status) \ 119 && ((SERF_ERROR_DECOMPRESSION_FAILED == (status)) \ 120 ||(SERF_ERROR_BAD_HTTP_RESPONSE == (status)) \ 121 ||(SERF_ERROR_TRUNCATED_HTTP_RESPONSE == (status)))) 122 123/** 124 * Return a string that describes the specified error code. 125 * 126 * If the error code is not one of the above Serf error codes, then 127 * NULL will be returned. 128 * 129 * Note regarding lifetime: the string is a statically-allocated constant 130 */ 131const char *serf_error_string(apr_status_t errcode); 132 133 134/** 135 * Create a new context for serf operations. 136 * 137 * A serf context defines a control loop which processes multiple 138 * connections simultaneously. 139 * 140 * The context will be allocated within @a pool. 141 */ 142serf_context_t *serf_context_create( 143 apr_pool_t *pool); 144 145/** 146 * Callback function. Add a socket to the externally managed poll set. 147 * 148 * Both @a pfd and @a serf_baton should be used when calling serf_event_trigger 149 * later. 150 */ 151typedef apr_status_t (*serf_socket_add_t)( 152 void *user_baton, 153 apr_pollfd_t *pfd, 154 void *serf_baton); 155 156/** 157 * Callback function. Remove the socket, identified by both @a pfd and 158 * @a serf_baton from the externally managed poll set. 159 */ 160typedef apr_status_t (*serf_socket_remove_t)( 161 void *user_baton, 162 apr_pollfd_t *pfd, 163 void *serf_baton); 164 165/* Create a new context for serf operations. 166 * 167 * Use this function to make serf not use its internal control loop, but 168 * instead rely on an external event loop. Serf will use the @a addf and @a rmf 169 * callbacks to notify of any event on a connection. The @a user_baton will be 170 * passed through the addf and rmf callbacks. 171 * 172 * The context will be allocated within @a pool. 173 */ 174serf_context_t *serf_context_create_ex( 175 void *user_baton, 176 serf_socket_add_t addf, 177 serf_socket_remove_t rmf, 178 apr_pool_t *pool); 179 180/** 181 * Make serf process events on a connection, identified by both @a pfd and 182 * @a serf_baton. 183 * 184 * Any outbound data is delivered, and incoming data is made available to 185 * the associated response handlers and their buckets. 186 * 187 * If any data is processed (incoming or outgoing), then this function will 188 * return with APR_SUCCESS. 189 */ 190apr_status_t serf_event_trigger( 191 serf_context_t *s, 192 void *serf_baton, 193 const apr_pollfd_t *pfd); 194 195/** @see serf_context_run should not block at all. */ 196#define SERF_DURATION_NOBLOCK 0 197/** @see serf_context_run should run for (nearly) "forever". */ 198#define SERF_DURATION_FOREVER 2000000000 /* approx 1^31 */ 199 200/** 201 * Run the main networking control loop. 202 * 203 * The set of connections defined by the serf context @a ctx are processed. 204 * Any outbound data is delivered, and incoming data is made available to 205 * the associated response handlers and their buckets. This function will 206 * block on the network for no longer than @a duration microseconds. 207 * 208 * If any data is processed (incoming or outgoing), then this function will 209 * return with APR_SUCCESS. Typically, the caller will just want to call it 210 * again to continue processing data. 211 * 212 * If no activity occurs within the specified timeout duration, then 213 * APR_TIMEUP is returned. 214 * 215 * All temporary allocations will be made in @a pool. 216 */ 217apr_status_t serf_context_run( 218 serf_context_t *ctx, 219 apr_short_interval_time_t duration, 220 apr_pool_t *pool); 221 222 223apr_status_t serf_context_prerun( 224 serf_context_t *ctx); 225 226/** 227 * Callback function for progress information. @a progress indicates cumulative 228 * number of bytes read or written, for the whole context. 229 */ 230typedef void (*serf_progress_t)( 231 void *progress_baton, 232 apr_off_t read, 233 apr_off_t write); 234 235/** 236 * Sets the progress callback function. @a progress_func will be called every 237 * time bytes are read of or written on a socket. 238 */ 239void serf_context_set_progress_cb( 240 serf_context_t *ctx, 241 const serf_progress_t progress_func, 242 void *progress_baton); 243 244/** @} */ 245 246/** 247 * @defgroup serf connections and requests 248 * @ingroup serf 249 * @{ 250 */ 251 252/** 253 * When a connection is established, the application needs to wrap some 254 * buckets around @a skt to enable serf to process incoming responses. This 255 * is the control point for assembling connection-level processing logic 256 * around the given socket. 257 * 258 * The @a setup_baton is the baton established at connection creation time. 259 * 260 * This callback corresponds to reading from the server. Since this is an 261 * on-demand activity, we use a callback. The corresponding write operation 262 * is based on the @see serf_request_deliver function, where the application 263 * can assemble the appropriate bucket(s) before delivery. 264 * 265 * The returned bucket should live at least as long as the connection itself. 266 * It is assumed that an appropriate allocator is passed in @a setup_baton. 267 * ### we may want to create a connection-level allocator and pass that 268 * ### along. however, that allocator would *only* be used for this 269 * ### callback. it may be wasteful to create a per-conn allocator, so this 270 * ### baton-based, app-responsible form might be best. 271 * 272 * Responsibility for the buckets is passed to the serf library. They will be 273 * destroyed when the connection is closed. 274 * 275 * All temporary allocations should be made in @a pool. 276 */ 277typedef apr_status_t (*serf_connection_setup_t)( 278 apr_socket_t *skt, 279 serf_bucket_t **read_bkt, 280 serf_bucket_t **write_bkt, 281 void *setup_baton, 282 apr_pool_t *pool); 283 284/** 285 * ### need to update docco w.r.t socket. became "stream" recently. 286 * ### the stream does not have a barrier, this callback should generally 287 * ### add a barrier around the stream before incorporating it into a 288 * ### response bucket stack. 289 * ### should serf add the barrier automatically to protect its data 290 * ### structure? i.e. the passed bucket becomes owned rather than 291 * ### borrowed. that might suit overall semantics better. 292 * Accept an incoming response for @a request, and its @a socket. A bucket 293 * for the response should be constructed and returned. This is the control 294 * point for assembling the appropriate wrapper buckets around the socket to 295 * enable processing of the incoming response. 296 * 297 * The @a acceptor_baton is the baton provided when the specified request 298 * was created. 299 * 300 * The request's pool and bucket allocator should be used for any allocations 301 * that need to live for the duration of the response. Care should be taken 302 * to bound the amount of memory stored in this pool -- to ensure that 303 * allocations are not proportional to the amount of data in the response. 304 * 305 * Responsibility for the bucket is passed to the serf library. It will be 306 * destroyed when the response has been fully read (the bucket returns an 307 * APR_EOF status from its read functions). 308 * 309 * All temporary allocations should be made in @a pool. 310 */ 311/* ### do we need to return an error? */ 312typedef serf_bucket_t * (*serf_response_acceptor_t)( 313 serf_request_t *request, 314 serf_bucket_t *stream, 315 void *acceptor_baton, 316 apr_pool_t *pool); 317 318/** 319 * Notification callback for when a connection closes. 320 * 321 * This callback is used to inform an application that the @a conn 322 * connection has been (abnormally) closed. The @a closed_baton is the 323 * baton provided when the connection was first opened. The reason for 324 * closure is given in @a why, and will be APR_SUCCESS if the application 325 * requested closure (by clearing the pool used to allocate this 326 * connection or calling serf_connection_close). 327 * 328 * All temporary allocations should be made in @a pool. 329 */ 330typedef void (*serf_connection_closed_t)( 331 serf_connection_t *conn, 332 void *closed_baton, 333 apr_status_t why, 334 apr_pool_t *pool); 335 336/** 337 * Response data has arrived and should be processed. 338 * 339 * Whenever response data for @a request arrives (initially, or continued data 340 * arrival), this handler is invoked. The response data is available in the 341 * @a response bucket. The @a handler_baton is passed along from the baton 342 * provided by the request setup callback (@see serf_request_setup_t). 343 * 344 * The handler MUST process data from the @a response bucket until the 345 * bucket's read function states it would block (see APR_STATUS_IS_EAGAIN). 346 * The handler is invoked only when new data arrives. If no further data 347 * arrives, and the handler does not process all available data, then the 348 * system can result in a deadlock around the unprocessed, but read, data. 349 * 350 * The handler should return APR_EOF when the response has been fully read. 351 * If calling the handler again would block, APR_EAGAIN should be returned. 352 * If the handler should be invoked again, simply return APR_SUCCESS. 353 * 354 * Note: if the connection closed (at the request of the application, or 355 * because of an (abnormal) termination) while a request is being delivered, 356 * or before a response arrives, then @a response will be NULL. This is the 357 * signal that the request was not delivered properly, and no further 358 * response should be expected (this callback will not be invoked again). 359 * If a request is injected into the connection (during this callback's 360 * execution, or otherwise), then the connection will be reopened. 361 * 362 * All temporary allocations should be made in @a pool. 363 */ 364typedef apr_status_t (*serf_response_handler_t)( 365 serf_request_t *request, 366 serf_bucket_t *response, 367 void *handler_baton, 368 apr_pool_t *pool); 369 370/** 371 * Callback function to be implemented by the application, so that serf 372 * can handle server and proxy authentication. 373 * code = 401 (server) or 407 (proxy). 374 * baton = the baton passed to serf_context_run. 375 * authn_type = one of "Basic", "Digest". 376 */ 377typedef apr_status_t (*serf_credentials_callback_t)( 378 char **username, 379 char **password, 380 serf_request_t *request, void *baton, 381 int code, const char *authn_type, 382 const char *realm, 383 apr_pool_t *pool); 384 385/** 386 * Create a new connection associated with the @a ctx serf context. 387 * 388 * If no proxy server is configured, a connection will be created to 389 * (eventually) connect to the address specified by @a address. The address must 390 * live at least as long as @a pool (thus, as long as the connection object). 391 * If a proxy server is configured, @address will be ignored. 392 * 393 * The connection object will be allocated within @a pool. Clearing or 394 * destroying this pool will close the connection, and terminate any 395 * outstanding requests or responses. 396 * 397 * When the connection is closed (upon request or because of an error), 398 * then the @a closed callback is invoked, and @a closed_baton is passed. 399 * 400 * ### doc on setup(_baton). tweak below comment re: acceptor. 401 * NULL may be passed for @a acceptor and @a closed; default implementations 402 * will be used. 403 * 404 * Note: the connection is not made immediately. It will be opened on 405 * the next call to @see serf_context_run. 406 */ 407serf_connection_t *serf_connection_create( 408 serf_context_t *ctx, 409 apr_sockaddr_t *address, 410 serf_connection_setup_t setup, 411 void *setup_baton, 412 serf_connection_closed_t closed, 413 void *closed_baton, 414 apr_pool_t *pool); 415 416/** 417 * Create a new connection associated with the @a ctx serf context. 418 * 419 * A connection will be created to (eventually) connect to the address 420 * specified by @a address. The address must live at least as long as 421 * @a pool (thus, as long as the connection object). 422 * 423 * The host address will be looked up based on the hostname in @a host_info. 424 * 425 * The connection object will be allocated within @a pool. Clearing or 426 * destroying this pool will close the connection, and terminate any 427 * outstanding requests or responses. 428 * 429 * When the connection is closed (upon request or because of an error), 430 * then the @a closed callback is invoked, and @a closed_baton is passed. 431 * 432 * ### doc on setup(_baton). tweak below comment re: acceptor. 433 * NULL may be passed for @a acceptor and @a closed; default implementations 434 * will be used. 435 * 436 * Note: the connection is not made immediately. It will be opened on 437 * the next call to @see serf_context_run. 438 */ 439apr_status_t serf_connection_create2( 440 serf_connection_t **conn, 441 serf_context_t *ctx, 442 apr_uri_t host_info, 443 serf_connection_setup_t setup, 444 void *setup_baton, 445 serf_connection_closed_t closed, 446 void *closed_baton, 447 apr_pool_t *pool); 448 449 450typedef apr_status_t (*serf_accept_client_t)( 451 serf_context_t *ctx, 452 serf_listener_t *l, 453 void *accept_baton, 454 apr_socket_t *insock, 455 apr_pool_t *pool); 456 457apr_status_t serf_listener_create( 458 serf_listener_t **listener, 459 serf_context_t *ctx, 460 const char *host, 461 apr_uint16_t port, 462 void *accept_baton, 463 serf_accept_client_t accept_func, 464 apr_pool_t *pool); 465 466typedef apr_status_t (*serf_incoming_request_cb_t)( 467 serf_context_t *ctx, 468 serf_incoming_request_t *req, 469 void *request_baton, 470 apr_pool_t *pool); 471 472apr_status_t serf_incoming_create( 473 serf_incoming_t **client, 474 serf_context_t *ctx, 475 apr_socket_t *insock, 476 void *request_baton, 477 serf_incoming_request_cb_t request, 478 apr_pool_t *pool); 479 480 481 482 483/** 484 * Reset the connection, but re-open the socket again. 485 */ 486apr_status_t serf_connection_reset( 487 serf_connection_t *conn); 488 489/** 490 * Close the connection associated with @a conn and cancel all pending requests. 491 * 492 * The closed callback passed to serf_connection_create() will be invoked 493 * with APR_SUCCESS. 494 */ 495apr_status_t serf_connection_close( 496 serf_connection_t *conn); 497 498/** 499 * Sets the maximum number of outstanding requests @a max_requests on the 500 * connection @a conn. Setting max_requests to 0 means unlimited (the default). 501 * Ex.: setting max_requests to 1 means a request is sent when a response on the 502 * previous request was received and handled. 503 * 504 * In general, serf tends to take around 16KB per outstanding request. 505 */ 506void serf_connection_set_max_outstanding_requests( 507 serf_connection_t *conn, 508 unsigned int max_requests); 509 510void serf_connection_set_async_responses( 511 serf_connection_t *conn, 512 serf_response_acceptor_t acceptor, 513 void *acceptor_baton, 514 serf_response_handler_t handler, 515 void *handler_baton); 516 517/** 518 * Setup the @a request for delivery on its connection. 519 * 520 * Right before this is invoked, @a pool will be built within the 521 * connection's pool for the request to use. The associated response will 522 * be allocated within that subpool. An associated bucket allocator will 523 * be built. These items may be fetched from the request object through 524 * @see serf_request_get_pool or @see serf_request_get_alloc. 525 * 526 * The content of the request is specified by the @a req_bkt bucket. When 527 * a response arrives, the @a acceptor callback will be invoked (along with 528 * the @a acceptor_baton) to produce a response bucket. That bucket will then 529 * be passed to @a handler, along with the @a handler_baton. 530 * 531 * The responsibility for the request bucket is passed to the request 532 * object. When the request is done with the bucket, it will be destroyed. 533 */ 534typedef apr_status_t (*serf_request_setup_t)( 535 serf_request_t *request, 536 void *setup_baton, 537 serf_bucket_t **req_bkt, 538 serf_response_acceptor_t *acceptor, 539 void **acceptor_baton, 540 serf_response_handler_t *handler, 541 void **handler_baton, 542 apr_pool_t *pool); 543 544/** 545 * Construct a request object for the @a conn connection. 546 * 547 * When it is time to deliver the request, the @a setup callback will 548 * be invoked with the @a setup_baton passed into it to complete the 549 * construction of the request object. 550 * 551 * If the request has not (yet) been delivered, then it may be canceled 552 * with @see serf_request_cancel. 553 * 554 * Invoking any calls other than @see serf_request_cancel before the setup 555 * callback executes is not supported. 556 */ 557serf_request_t *serf_connection_request_create( 558 serf_connection_t *conn, 559 serf_request_setup_t setup, 560 void *setup_baton); 561 562/** 563 * Construct a request object for the @a conn connection, add it in the 564 * list as the next to-be-written request before all unwritten requests. 565 * 566 * When it is time to deliver the request, the @a setup callback will 567 * be invoked with the @a setup_baton passed into it to complete the 568 * construction of the request object. 569 * 570 * If the request has not (yet) been delivered, then it may be canceled 571 * with @see serf_request_cancel. 572 * 573 * Invoking any calls other than @see serf_request_cancel before the setup 574 * callback executes is not supported. 575 */ 576serf_request_t *serf_connection_priority_request_create( 577 serf_connection_t *conn, 578 serf_request_setup_t setup, 579 void *setup_baton); 580 581 582/** Returns detected network latency for the @a conn connection. Negative 583 * value means that latency is unknwon. 584 */ 585apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn); 586 587/** Check if a @a request has been completely written. 588 * 589 * Returns APR_SUCCESS if the request was written completely on the connection. 590 * Returns APR_EBUSY if the request is not yet or partially written. 591 */ 592apr_status_t serf_request_is_written( 593 serf_request_t *request); 594 595/** 596 * Cancel the request specified by the @a request object. 597 * 598 * If the request has been scheduled for delivery, then its response 599 * handler will be run, passing NULL for the response bucket. 600 * 601 * If the request has already been (partially or fully) delivered, then 602 * APR_EBUSY is returned and the request is *NOT* canceled. To properly 603 * cancel the request, the connection must be closed (by clearing or 604 * destroying its associated pool). 605 */ 606apr_status_t serf_request_cancel( 607 serf_request_t *request); 608 609/** 610 * Return the pool associated with @a request. 611 * 612 * WARNING: be very careful about the kinds of things placed into this 613 * pool. In particular, all allocation should be bounded in size, rather 614 * than proportional to any data stream. 615 */ 616apr_pool_t *serf_request_get_pool( 617 const serf_request_t *request); 618 619/** 620 * Return the bucket allocator associated with @a request. 621 */ 622serf_bucket_alloc_t *serf_request_get_alloc( 623 const serf_request_t *request); 624 625/** 626 * Return the connection associated with @a request. 627 */ 628serf_connection_t *serf_request_get_conn( 629 const serf_request_t *request); 630 631/** 632 * Update the @a handler and @a handler_baton for this @a request. 633 * 634 * This can be called after the request has started processing - 635 * subsequent data will be delivered to this new handler. 636 */ 637void serf_request_set_handler( 638 serf_request_t *request, 639 const serf_response_handler_t handler, 640 const void **handler_baton); 641 642/** 643 * Configure proxy server settings, to be used by all connections associated 644 * with the @a ctx serf context. 645 * 646 * The next connection will be created to connect to the proxy server 647 * specified by @a address. The address must live at least as long as the 648 * serf context. 649 */ 650void serf_config_proxy( 651 serf_context_t *ctx, 652 apr_sockaddr_t *address); 653 654/* Supported authentication types. */ 655#define SERF_AUTHN_NONE 0x00 656#define SERF_AUTHN_BASIC 0x01 657#define SERF_AUTHN_DIGEST 0x02 658#define SERF_AUTHN_NTLM 0x04 659#define SERF_AUTHN_NEGOTIATE 0x08 660#define SERF_AUTHN_ALL 0xFF 661 662/** 663 * Define the authentication handlers that serf will try on incoming requests. 664 */ 665void serf_config_authn_types( 666 serf_context_t *ctx, 667 int authn_types); 668 669/** 670 * Set the credentials callback handler. 671 */ 672void serf_config_credentials_callback( 673 serf_context_t *ctx, 674 serf_credentials_callback_t cred_cb); 675 676/* ### maybe some connection control functions for flood? */ 677 678/*** Special bucket creation functions ***/ 679 680/** 681 * Create a bucket of type 'socket bucket'. 682 * This is basically a wrapper around @a serf_bucket_socket_create, which 683 * initializes the bucket using connection and/or context specific settings. 684 */ 685serf_bucket_t *serf_context_bucket_socket_create( 686 serf_context_t *ctx, 687 apr_socket_t *skt, 688 serf_bucket_alloc_t *allocator); 689 690/** 691 * Create a bucket of type 'request bucket'. 692 * This is basically a wrapper around @a serf_bucket_request_create, which 693 * initializes the bucket using request, connection and/or context specific 694 * settings. 695 * 696 * This function will set following header(s): 697 * - Host: if the connection was created with @a serf_connection_create2. 698 */ 699serf_bucket_t *serf_request_bucket_request_create( 700 serf_request_t *request, 701 const char *method, 702 const char *uri, 703 serf_bucket_t *body, 704 serf_bucket_alloc_t *allocator); 705 706/** @} */ 707 708 709/** 710 * @defgroup serf buckets 711 * @ingroup serf 712 * @{ 713 */ 714 715/** Pass as REQUESTED to the read function of a bucket to read, consume, 716 * and return all available data. 717 */ 718#define SERF_READ_ALL_AVAIL ((apr_size_t)-1) 719 720/** Acceptable newline types for bucket->readline(). */ 721#define SERF_NEWLINE_CR 0x0001 722#define SERF_NEWLINE_CRLF 0x0002 723#define SERF_NEWLINE_LF 0x0004 724#define SERF_NEWLINE_ANY 0x0007 725 726/** Used to indicate that a newline is not present in the data buffer. */ 727/* ### should we make this zero? */ 728#define SERF_NEWLINE_NONE 0x0008 729 730/** Used to indicate that a CR was found at the end of a buffer, and CRLF 731 * was acceptable. It may be that the LF is present, but it needs to be 732 * read first. 733 * 734 * Note: an alternative to using this symbol would be for callers to see 735 * the SERF_NEWLINE_CR return value, and know that some "end of buffer" was 736 * reached. While this works well for @see serf_util_readline, it does not 737 * necessary work as well for buckets (there is no obvious "end of buffer", 738 * although there is an "end of bucket"). The other problem with that 739 * alternative is that developers might miss the condition. This symbol 740 * calls out the possibility and ensures that callers will watch for it. 741 */ 742#define SERF_NEWLINE_CRLF_SPLIT 0x0010 743 744 745struct serf_bucket_type_t { 746 747 /** name of this bucket type */ 748 const char *name; 749 750 /** 751 * Read (and consume) up to @a requested bytes from @a bucket. 752 * 753 * A pointer to the data will be returned in @a data, and its length 754 * is specified by @a len. 755 * 756 * The data will exist until one of two conditions occur: 757 * 758 * 1) this bucket is destroyed 759 * 2) another call to any read function or to peek() 760 * 761 * If an application needs the data to exist for a longer duration, 762 * then it must make a copy. 763 */ 764 apr_status_t (*read)(serf_bucket_t *bucket, apr_size_t requested, 765 const char **data, apr_size_t *len); 766 767 /** 768 * Read (and consume) a line of data from @a bucket. 769 * 770 * The acceptable forms of a newline are given by @a acceptable, and 771 * the type found is returned in @a found. If a newline is not present 772 * in the returned data, then SERF_NEWLINE_NONE is stored into @a found. 773 * 774 * A pointer to the data is returned in @a data, and its length is 775 * specified by @a len. The data will include the newline, if present. 776 * 777 * Note that there is no way to limit the amount of data returned 778 * by this function. 779 * 780 * The lifetime of the data is the same as that of the @see read 781 * function above. 782 */ 783 apr_status_t (*readline)(serf_bucket_t *bucket, int acceptable, 784 int *found, 785 const char **data, apr_size_t *len); 786 787 /** 788 * Read a set of pointer/length pairs from the bucket. 789 * 790 * The size of the @a vecs array is specified by @a vecs_size. The 791 * bucket should fill in elements of the array, and return the number 792 * used in @a vecs_used. 793 * 794 * Each element of @a vecs should specify a pointer to a block of 795 * data and a length of that data. 796 * 797 * The total length of all data elements should not exceed the 798 * amount specified in @a requested. 799 * 800 * The lifetime of the data is the same as that of the @see read 801 * function above. 802 */ 803 apr_status_t (*read_iovec)(serf_bucket_t *bucket, apr_size_t requested, 804 int vecs_size, struct iovec *vecs, 805 int *vecs_used); 806 807 /** 808 * Read data from the bucket in a form suitable for apr_socket_sendfile() 809 * 810 * On input, hdtr->numheaders and hdtr->numtrailers specify the size 811 * of the hdtr->headers and hdtr->trailers arrays, respectively. The 812 * bucket should fill in the headers and trailers, up to the specified 813 * limits, and set numheaders and numtrailers to the number of iovecs 814 * filled in for each item. 815 * 816 * @a file should be filled in with a file that can be read. If a file 817 * is not available or appropriate, then NULL should be stored. The 818 * file offset for the data should be stored in @a offset, and the 819 * length of that data should be stored in @a len. If a file is not 820 * returned, then @a offset and @a len should be ignored. 821 * 822 * The file position is not required to correspond to @a offset, and 823 * the caller may manipulate it at will. 824 * 825 * The total length of all data elements, and the portion of the 826 * file should not exceed the amount specified in @a requested. 827 * 828 * The lifetime of the data is the same as that of the @see read 829 * function above. 830 */ 831 apr_status_t (*read_for_sendfile)(serf_bucket_t *bucket, 832 apr_size_t requested, apr_hdtr_t *hdtr, 833 apr_file_t **file, apr_off_t *offset, 834 apr_size_t *len); 835 836 /** 837 * Look within @a bucket for a bucket of the given @a type. The bucket 838 * must be the "initial" data because it will be consumed by this 839 * function. If the given bucket type is available, then read and consume 840 * it, and return it to the caller. 841 * 842 * This function is usually used by readers that have custom handling 843 * for specific bucket types (e.g. looking for a file bucket to pass 844 * to apr_socket_sendfile). 845 * 846 * If a bucket of the given type is not found, then NULL is returned. 847 * 848 * The returned bucket becomes the responsibility of the caller. When 849 * the caller is done with the bucket, it should be destroyed. 850 */ 851 serf_bucket_t * (*read_bucket)(serf_bucket_t *bucket, 852 const serf_bucket_type_t *type); 853 854 /** 855 * Peek, but don't consume, the data in @a bucket. 856 * 857 * Since this function is non-destructive, the implicit read size is 858 * SERF_READ_ALL_AVAIL. The caller can then use whatever amount is 859 * appropriate. 860 * 861 * The @a data parameter will point to the data, and @a len will 862 * specify how much data is available. The lifetime of the data follows 863 * the same rules as the @see read function above. 864 * 865 * Note: if the peek does not return enough data for your particular 866 * use, then you must read/consume some first, then peek again. 867 * 868 * If the returned data represents all available data, then APR_EOF 869 * will be returned. Since this function does not consume data, it 870 * can return the same data repeatedly rather than blocking; thus, 871 * APR_EAGAIN will never be returned. 872 */ 873 apr_status_t (*peek)(serf_bucket_t *bucket, 874 const char **data, apr_size_t *len); 875 876 /** 877 * Destroy @a bucket, along with any associated resources. 878 */ 879 void (*destroy)(serf_bucket_t *bucket); 880 881 /* ### apr buckets have 'copy', 'split', and 'setaside' functions. 882 ### not sure whether those will be needed in this bucket model. 883 */ 884}; 885 886/** 887 * Should the use and lifecycle of buckets be tracked? 888 * 889 * When tracking, the system will ensure several semantic requirements 890 * of bucket use: 891 * 892 * - if a bucket returns APR_EAGAIN, one of its read functions should 893 * not be called immediately. the context's run loop should be called. 894 * ### and for APR_EOF, too? 895 * - all buckets must be drained of input before returning to the 896 * context's run loop. 897 * - buckets should not be destroyed before they return APR_EOF unless 898 * the connection is closed for some reason. 899 * 900 * Undefine this symbol to avoid the tracking (and a performance gain). 901 * 902 * ### we may want to examine when/how we provide this. should it always 903 * ### be compiled in? and apps select it before including this header? 904 */ 905/* #define SERF_DEBUG_BUCKET_USE */ 906 907 908/* Internal macros for tracking bucket use. */ 909#ifdef SERF_DEBUG_BUCKET_USE 910#define SERF__RECREAD(b,s) serf_debug__record_read(b,s) 911#else 912#define SERF__RECREAD(b,s) (s) 913#endif 914 915#define serf_bucket_read(b,r,d,l) SERF__RECREAD(b, (b)->type->read(b,r,d,l)) 916#define serf_bucket_readline(b,a,f,d,l) \ 917 SERF__RECREAD(b, (b)->type->readline(b,a,f,d,l)) 918#define serf_bucket_read_iovec(b,r,s,v,u) \ 919 SERF__RECREAD(b, (b)->type->read_iovec(b,r,s,v,u)) 920#define serf_bucket_read_for_sendfile(b,r,h,f,o,l) \ 921 SERF__RECREAD(b, (b)->type->read_for_sendfile(b,r,h,f,o,l)) 922#define serf_bucket_read_bucket(b,t) ((b)->type->read_bucket(b,t)) 923#define serf_bucket_peek(b,d,l) ((b)->type->peek(b,d,l)) 924#define serf_bucket_destroy(b) ((b)->type->destroy(b)) 925 926/** 927 * Check whether a real error occurred. Note that bucket read functions 928 * can return EOF and EAGAIN as part of their "normal" operation, so they 929 * should not be considered an error. 930 */ 931#define SERF_BUCKET_READ_ERROR(status) ((status) \ 932 && !APR_STATUS_IS_EOF(status) \ 933 && !APR_STATUS_IS_EAGAIN(status) \ 934 && (SERF_ERROR_WAIT_CONN != status)) 935 936 937struct serf_bucket_t { 938 939 /** the type of this bucket */ 940 const serf_bucket_type_t *type; 941 942 /** bucket-private data */ 943 void *data; 944 945 /** the allocator used for this bucket (needed at destroy time) */ 946 serf_bucket_alloc_t *allocator; 947}; 948 949 950/** 951 * Generic macro to construct "is TYPE" macros. 952 */ 953#define SERF_BUCKET_CHECK(b, btype) ((b)->type == &serf_bucket_type_ ## btype) 954 955 956/** 957 * Notification callback for a block that was not returned to the bucket 958 * allocator when its pool was destroyed. 959 * 960 * The block of memory is given by @a block. The baton provided when the 961 * allocator was constructed is passed as @a unfreed_baton. 962 */ 963typedef void (*serf_unfreed_func_t)( 964 void *unfreed_baton, 965 void *block); 966 967/** 968 * Create a new allocator for buckets. 969 * 970 * All buckets are associated with a serf bucket allocator. This allocator 971 * will be created within @a pool and will be destroyed when that pool is 972 * cleared or destroyed. 973 * 974 * When the allocator is destroyed, if any allocations were not explicitly 975 * returned (by calling serf_bucket_mem_free), then the @a unfreed callback 976 * will be invoked for each block. @a unfreed_baton will be passed to the 977 * callback. 978 * 979 * If @a unfreed is NULL, then the library will invoke the abort() stdlib 980 * call. Any failure to return memory is a bug in the application, and an 981 * abort can assist with determining what kinds of memory were not freed. 982 */ 983serf_bucket_alloc_t *serf_bucket_allocator_create( 984 apr_pool_t *pool, 985 serf_unfreed_func_t unfreed, 986 void *unfreed_baton); 987 988/** 989 * Return the pool that was used for this @a allocator. 990 * 991 * WARNING: the use of this pool for allocations requires a very 992 * detailed understanding of pool behaviors, the bucket system, 993 * and knowledge of the bucket's use within the overall pattern 994 * of request/response behavior. 995 * 996 * See design-guide.txt for more information about pool usage. 997 */ 998apr_pool_t *serf_bucket_allocator_get_pool( 999 const serf_bucket_alloc_t *allocator); 1000 1001 1002/** 1003 * Utility structure for reading a complete line of input from a bucket. 1004 * 1005 * Since it is entirely possible for a line to be broken by APR_EAGAIN, 1006 * this structure can be used to accumulate the data until a complete line 1007 * has been read from a bucket. 1008 */ 1009 1010/* This limit applies to the line buffer functions. If an application needs 1011 * longer lines, then they will need to manually handle line buffering. 1012 */ 1013#define SERF_LINEBUF_LIMIT 8000 1014 1015typedef struct { 1016 1017 /* Current state of the buffer. */ 1018 enum { 1019 SERF_LINEBUF_EMPTY, 1020 SERF_LINEBUF_READY, 1021 SERF_LINEBUF_PARTIAL, 1022 SERF_LINEBUF_CRLF_SPLIT 1023 } state; 1024 1025 /* How much of the buffer have we used? */ 1026 apr_size_t used; 1027 1028 /* The line is read into this buffer, minus CR/LF */ 1029 char line[SERF_LINEBUF_LIMIT]; 1030 1031} serf_linebuf_t; 1032 1033/** 1034 * Initialize the @a linebuf structure. 1035 */ 1036void serf_linebuf_init(serf_linebuf_t *linebuf); 1037 1038/** 1039 * Fetch a line of text from @a bucket, accumulating the line into 1040 * @a linebuf. @a acceptable specifies the types of newlines which are 1041 * acceptable for this fetch. 1042 * 1043 * ### we should return a data/len pair so that we can avoid a copy, 1044 * ### rather than having callers look into our state and line buffer. 1045 */ 1046apr_status_t serf_linebuf_fetch( 1047 serf_linebuf_t *linebuf, 1048 serf_bucket_t *bucket, 1049 int acceptable); 1050 1051/** @} */ 1052 1053 1054/* Internal functions for bucket use and lifecycle tracking */ 1055apr_status_t serf_debug__record_read( 1056 const serf_bucket_t *bucket, 1057 apr_status_t status); 1058void serf_debug__entered_loop( 1059 serf_bucket_alloc_t *allocator); 1060void serf_debug__closed_conn( 1061 serf_bucket_alloc_t *allocator); 1062void serf_debug__bucket_destroy( 1063 const serf_bucket_t *bucket); 1064void serf_debug__bucket_alloc_check( 1065 serf_bucket_alloc_t *allocator); 1066 1067/* Version info */ 1068#define SERF_MAJOR_VERSION 1 1069#define SERF_MINOR_VERSION 3 1070#define SERF_PATCH_VERSION 9 1071 1072/* Version number string */ 1073#define SERF_VERSION_STRING APR_STRINGIFY(SERF_MAJOR_VERSION) "." \ 1074 APR_STRINGIFY(SERF_MINOR_VERSION) "." \ 1075 APR_STRINGIFY(SERF_PATCH_VERSION) 1076 1077/** 1078 * Check at compile time if the Serf version is at least a certain 1079 * level. 1080 * @param major The major version component of the version checked 1081 * for (e.g., the "1" of "1.3.0"). 1082 * @param minor The minor version component of the version checked 1083 * for (e.g., the "3" of "1.3.0"). 1084 * @param patch The patch level component of the version checked 1085 * for (e.g., the "0" of "1.3.0"). 1086 */ 1087#define SERF_VERSION_AT_LEAST(major,minor,patch) \ 1088(((major) < SERF_MAJOR_VERSION) \ 1089 || ((major) == SERF_MAJOR_VERSION && (minor) < SERF_MINOR_VERSION) \ 1090 || ((major) == SERF_MAJOR_VERSION && (minor) == SERF_MINOR_VERSION && \ 1091 (patch) <= SERF_PATCH_VERSION)) 1092 1093 1094/** 1095 * Returns the version of the library the application has linked/loaded. 1096 * Values are returned in @a major, @a minor, and @a patch. 1097 * 1098 * Applications will want to use this function to verify compatibility, 1099 * expecially while serf has not reached a 1.0 milestone. APIs and 1100 * semantics may change drastically until the library hits 1.0. 1101 */ 1102void serf_lib_version( 1103 int *major, 1104 int *minor, 1105 int *patch); 1106 1107 1108#ifdef __cplusplus 1109} 1110#endif 1111 1112 1113/* 1114 * Every user of serf will want to deal with our various bucket types. 1115 * Go ahead and include that header right now. 1116 * 1117 * Note: make sure this occurs outside of the C++ namespace block 1118 */ 1119#include "serf_bucket_types.h" 1120 1121 1122#endif /* !SERF_H */ 1123