home *** CD-ROM | disk | FTP | other *** search
/ GameStar 2004 May / Gamestar_62_2004-05_dvd.iso / Programy / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F251735_apr_buckets.h < prev    next >
C/C++ Source or Header  |  2003-08-27  |  62KB  |  1,534 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54. /**
  55.  * @file apr_buckets.h
  56.  * @brief APR-UTIL Buckets/Bucket Brigades
  57.  */
  58.  
  59. #ifndef APR_BUCKETS_H
  60. #define APR_BUCKETS_H
  61.  
  62. #if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG)
  63. #define APR_RING_DEBUG
  64. #endif
  65.  
  66. #include "apu.h"
  67. #include "apr_network_io.h"
  68. #include "apr_file_io.h"
  69. #include "apr_general.h"
  70. #include "apr_mmap.h"
  71. #include "apr_errno.h"
  72. #include "apr_ring.h"
  73. #include "apr.h"
  74. #if APR_HAVE_SYS_UIO_H
  75. #include <sys/uio.h>    /* for struct iovec */
  76. #endif
  77. #if APR_HAVE_STDARG_H
  78. #include <stdarg.h>
  79. #endif
  80.  
  81. #ifdef __cplusplus
  82. extern "C" {
  83. #endif
  84.  
  85. /**
  86.  * @defgroup APR_Util_Bucket_Brigades Bucket Brigades
  87.  * @ingroup APR_Util
  88.  * @{ 
  89.  */
  90.  
  91. /** default bucket buffer size - 8KB minus room for memory allocator headers */
  92. #define APR_BUCKET_BUFF_SIZE 8000
  93.  
  94. /** Determines how a bucket or brigade should be read */
  95. typedef enum {
  96.     APR_BLOCK_READ,   /**< block until data becomes available */
  97.     APR_NONBLOCK_READ /**< return immediately if no data is available */
  98. } apr_read_type_e;
  99.  
  100. /**
  101.  * The one-sentence buzzword-laden overview: Bucket brigades represent
  102.  * a complex data stream that can be passed through a layered IO
  103.  * system without unnecessary copying. A longer overview follows...
  104.  *
  105.  * A bucket brigade is a doubly linked list (ring) of buckets, so we
  106.  * aren't limited to inserting at the front and removing at the end.
  107.  * Buckets are only passed around as members of a brigade, although
  108.  * singleton buckets can occur for short periods of time.
  109.  *
  110.  * Buckets are data stores of various types. They can refer to data in
  111.  * memory, or part of a file or mmap area, or the output of a process,
  112.  * etc. Buckets also have some type-dependent accessor functions:
  113.  * read, split, copy, setaside, and destroy.
  114.  *
  115.  * read returns the address and size of the data in the bucket. If the
  116.  * data isn't in memory then it is read in and the bucket changes type
  117.  * so that it can refer to the new location of the data. If all the
  118.  * data doesn't fit in the bucket then a new bucket is inserted into
  119.  * the brigade to hold the rest of it.
  120.  *
  121.  * split divides the data in a bucket into two regions. After a split
  122.  * the original bucket refers to the first part of the data and a new
  123.  * bucket inserted into the brigade after the original bucket refers
  124.  * to the second part of the data. Reference counts are maintained as
  125.  * necessary.
  126.  *
  127.  * setaside ensures that the data in the bucket has a long enough
  128.  * lifetime. Sometimes it is convenient to create a bucket referring
  129.  * to data on the stack in the expectation that it will be consumed
  130.  * (output to the network) before the stack is unwound. If that
  131.  * expectation turns out not to be valid, the setaside function is
  132.  * called to move the data somewhere safer.
  133.  *
  134.  * copy makes a duplicate of the bucket structure as long as it's
  135.  * possible to have multiple references to a single copy of the
  136.  * data itself.  Not all bucket types can be copied.
  137.  *
  138.  * destroy maintains the reference counts on the resources used by a
  139.  * bucket and frees them if necessary.
  140.  *
  141.  * Note: all of the above functions have wrapper macros (apr_bucket_read(),
  142.  * apr_bucket_destroy(), etc), and those macros should be used rather
  143.  * than using the function pointers directly.
  144.  *
  145.  * To write a bucket brigade, they are first made into an iovec, so that we
  146.  * don't write too little data at one time.  Currently we ignore compacting the
  147.  * buckets into as few buckets as possible, but if we really want good
  148.  * performance, then we need to compact the buckets before we convert to an
  149.  * iovec, or possibly while we are converting to an iovec.
  150.  */
  151.  
  152. /*
  153.  * Forward declaration of the main types.
  154.  */
  155.  
  156. /** @see apr_bucket_brigade */
  157. typedef struct apr_bucket_brigade apr_bucket_brigade;
  158. /** @see apr_bucket */
  159. typedef struct apr_bucket apr_bucket;
  160. /** @see apr_bucket_alloc_t */
  161. typedef struct apr_bucket_alloc_t apr_bucket_alloc_t;
  162.  
  163. /** @see apr_bucket_type_t */
  164. typedef struct apr_bucket_type_t apr_bucket_type_t;
  165.  
  166. /**
  167.  * Basic bucket type
  168.  */
  169. struct apr_bucket_type_t {
  170.     /**
  171.      * The name of the bucket type
  172.      */
  173.     const char *name;
  174.     /** 
  175.      * The number of functions this bucket understands.  Can not be less than
  176.      * five.
  177.      */
  178.     int num_func;
  179.     /**
  180.      * Whether the bucket contains metadata (ie, information that
  181.      * describes the regular contents of the brigade).  The metadata
  182.      * is not returned by apr_bucket_read() and is not indicated by
  183.      * the ->length of the apr_bucket itself.  In other words, an
  184.      * empty bucket is safe to arbitrarily remove if and only if it
  185.      * contains no metadata.  In this sense, "data" is just raw bytes
  186.      * that are the "content" of the brigade and "metadata" describes
  187.      * that data but is not a proper part of it.
  188.      */
  189.     enum {
  190.         /** This bucket type represents actual data to send to the client. */
  191.         APR_BUCKET_DATA = 0,
  192.         /** This bucket type represents metadata. */
  193.         APR_BUCKET_METADATA = 1
  194.     } is_metadata;
  195.     /**
  196.      * Free the private data and any resources used by the bucket (if they
  197.      *  aren't shared with another bucket).  This function is required to be
  198.      *  implemented for all bucket types, though it might be a no-op on some
  199.      *  of them (namely ones that never allocate any private data structures).
  200.      * @param data The private data pointer from the bucket to be destroyed
  201.      */
  202.     void (*destroy)(void *data);
  203.  
  204.     /**
  205.      * Read the data from the bucket. This is required to be implemented
  206.      *  for all bucket types.
  207.      * @param b The bucket to read from
  208.      * @param str A place to store the data read.  Allocation should only be
  209.      *            done if absolutely necessary. 
  210.      * @param len The amount of data read.
  211.      * @param block Should this read function block if there is more data that
  212.      *              cannot be read immediately.
  213.      */
  214.     apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 
  215.                          apr_read_type_e block);
  216.     
  217.     /**
  218.      * Make it possible to set aside the data for at least as long as the
  219.      *  given pool. Buckets containing data that could potentially die before
  220.      *  this pool (e.g. the data resides on the stack, in a child pool of
  221.      *  the given pool, or in a disjoint pool) must somehow copy, shift, or
  222.      *  transform the data to have the proper lifetime.
  223.      * @param e The bucket to convert
  224.      * @remark Some bucket types contain data that will always outlive the
  225.      *         bucket itself. For example no data (EOS and FLUSH), or the data
  226.      *         resides in global, constant memory (IMMORTAL), or the data is on
  227.      *      the heap (HEAP). For these buckets, apr_bucket_setaside_noop can
  228.      *      be used.
  229.      */
  230.     apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool);
  231.  
  232.     /**
  233.      * Split one bucket in two at the specified position by duplicating
  234.      *  the bucket structure (not the data) and modifying any necessary
  235.      *  start/end/offset information.  If it's not possible to do this
  236.      *  for the bucket type (perhaps the length of the data is indeterminate,
  237.      *  as with pipe and socket buckets), then APR_ENOTIMPL is returned.
  238.      * @param e The bucket to split
  239.      * @param point The offset of the first byte in the new bucket
  240.      */
  241.     apr_status_t (*split)(apr_bucket *e, apr_size_t point);
  242.  
  243.     /**
  244.      * Copy the bucket structure (not the data), assuming that this is
  245.      *  possible for the bucket type. If it's not, APR_ENOTIMPL is returned.
  246.      * @param e The bucket to copy
  247.      * @param c Returns a pointer to the new bucket
  248.      */
  249.     apr_status_t (*copy)(apr_bucket *e, apr_bucket **c);
  250.  
  251. };
  252.  
  253. /**
  254.  * apr_bucket structures are allocated on the malloc() heap and
  255.  * their lifetime is controlled by the parent apr_bucket_brigade
  256.  * structure. Buckets can move from one brigade to another e.g. by
  257.  * calling APR_BRIGADE_CONCAT(). In general the data in a bucket has
  258.  * the same lifetime as the bucket and is freed when the bucket is
  259.  * destroyed; if the data is shared by more than one bucket (e.g.
  260.  * after a split) the data is freed when the last bucket goes away.
  261.  */
  262. struct apr_bucket {
  263.     /** Links to the rest of the brigade */
  264.     APR_RING_ENTRY(apr_bucket) link;
  265.     /** The type of bucket.  */
  266.     const apr_bucket_type_t *type;
  267.     /** The length of the data in the bucket.  This could have been implemented
  268.      *  with a function, but this is an optimization, because the most
  269.      *  common thing to do will be to get the length.  If the length is unknown,
  270.      *  the value of this field will be (apr_size_t)(-1).
  271.      */
  272.     apr_size_t length;
  273.     /** The start of the data in the bucket relative to the private base
  274.      *  pointer.  The vast majority of bucket types allow a fixed block of
  275.      *  data to be referenced by multiple buckets, each bucket pointing to
  276.      *  a different segment of the data.  That segment starts at base+start
  277.      *  and ends at base+start+length.  
  278.      *  If the length == (apr_size_t)(-1), then start == -1.
  279.      */
  280.     apr_off_t start;
  281.     /** type-dependent data hangs off this pointer */
  282.     void *data;    
  283.     /**
  284.      * Pointer to function used to free the bucket. This function should
  285.      * always be defined and it should be consistent with the memory
  286.      * function used to allocate the bucket. For example, if malloc() is 
  287.      * used to allocate the bucket, this pointer should point to free().
  288.      * @param e Pointer to the bucket being freed
  289.      */
  290.     void (*free)(void *e);
  291.     /** The freelist from which this bucket was allocated */
  292.     apr_bucket_alloc_t *list;
  293. };
  294.  
  295. /** A list of buckets */
  296. struct apr_bucket_brigade {
  297.     /** The pool to associate the brigade with.  The data is not allocated out
  298.      *  of the pool, but a cleanup is registered with this pool.  If the 
  299.      *  brigade is destroyed by some mechanism other than pool destruction,
  300.      *  the destroying function is responsible for killing the cleanup.
  301.      */
  302.     apr_pool_t *p;
  303.     /** The buckets in the brigade are on this list. */
  304.     /*
  305.      * The apr_bucket_list structure doesn't actually need a name tag
  306.      * because it has no existence independent of struct apr_bucket_brigade;
  307.      * the ring macros are designed so that you can leave the name tag
  308.      * argument empty in this situation but apparently the Windows compiler
  309.      * doesn't like that.
  310.      */
  311.     APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
  312.     /** The freelist from which this bucket was allocated */
  313.     apr_bucket_alloc_t *bucket_alloc;
  314. };
  315.  
  316.  
  317. /**
  318.  * Function called when a brigade should be flushed
  319.  */
  320. typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx);
  321.  
  322. /*
  323.  * define APR_BUCKET_DEBUG if you want your brigades to be checked for
  324.  * validity at every possible instant.  this will slow your code down
  325.  * substantially but is a very useful debugging tool.
  326.  */
  327. #ifdef APR_BUCKET_DEBUG
  328.  
  329. #define APR_BRIGADE_CHECK_CONSISTENCY(b)                \
  330.         APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link)
  331.  
  332. #define APR_BUCKET_CHECK_CONSISTENCY(e)                    \
  333.         APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link)
  334.  
  335. #else
  336. /**
  337.  * checks the ring pointers in a bucket brigade for consistency.  an
  338.  * abort() will be triggered if any inconsistencies are found.
  339.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  340.  * @param b The brigade
  341.  */
  342. #define APR_BRIGADE_CHECK_CONSISTENCY(b)
  343. /**
  344.  * checks the brigade a bucket is in for ring consistency.  an
  345.  * abort() will be triggered if any inconsistencies are found.
  346.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  347.  * @param e The bucket
  348.  */
  349. #define APR_BUCKET_CHECK_CONSISTENCY(e)
  350. #endif
  351.  
  352.  
  353. /**
  354.  * Wrappers around the RING macros to reduce the verbosity of the code
  355.  * that handles bucket brigades.
  356.  */
  357. /**
  358.  * The magic pointer value that indicates the head of the brigade
  359.  * @remark This is used to find the beginning and end of the brigade, eg:
  360.  * <pre>
  361.  *      while (e != APR_BRIGADE_SENTINEL(b)) {
  362.  *          ...
  363.  *          e = APR_BUCKET_NEXT(e);
  364.  *      }
  365.  * </pre>
  366.  * @param  b The brigade
  367.  * @return The magic pointer value
  368.  */
  369. #define APR_BRIGADE_SENTINEL(b)    APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
  370.  
  371. /**
  372.  * Determine if the bucket brigade is empty
  373.  * @param b The brigade to check
  374.  * @return true or false
  375.  */
  376. #define APR_BRIGADE_EMPTY(b)    APR_RING_EMPTY(&(b)->list, apr_bucket, link)
  377.  
  378. /**
  379.  * Return the first bucket in a brigade
  380.  * @param b The brigade to query
  381.  * @return The first bucket in the brigade
  382.  */
  383. #define APR_BRIGADE_FIRST(b)    APR_RING_FIRST(&(b)->list)
  384. /**
  385.  * Return the last bucket in a brigade
  386.  * @param b The brigade to query
  387.  * @return The last bucket in the brigade
  388.  */
  389. #define APR_BRIGADE_LAST(b)    APR_RING_LAST(&(b)->list)
  390.  
  391. /**
  392.  * Iterate through a bucket brigade
  393.  * @param e The current bucket
  394.  * @param b The brigade to iterate over
  395.  * @remark This is the same as either:
  396.  * <pre>
  397.  *    e = APR_BRIGADE_FIRST(b);
  398.  *     while (e != APR_BRIGADE_SENTINEL(b)) {
  399.  *        ...
  400.  *         e = APR_BUCKET_NEXT(e);
  401.  *     }
  402.  *  OR
  403.  *     for (e = APR_BRIGADE_FIRST(b);
  404.  *           e != APR_BRIGADE_SENTINEL(b);
  405.  *           e = APR_BUCKET_NEXT(e)) {
  406.  *        ...
  407.  *     }
  408.  * </pre>
  409.  * @warning Be aware that you cannot change the value of e within
  410.  * the foreach loop, nor can you destroy the bucket it points to.
  411.  * Modifying the prev and next pointers of the bucket is dangerous
  412.  * but can be done if you're careful.  If you change e's value or
  413.  * destroy the bucket it points to, then APR_BRIGADE_FOREACH
  414.  * will have no way to find out what bucket to use for its next
  415.  * iteration.  The reason for this can be seen by looking closely
  416.  * at the equivalent loops given in the tip above.  So, for example,
  417.  * if you are writing a loop that empties out a brigade one bucket
  418.  * at a time, APR_BRIGADE_FOREACH just won't work for you.  Do it
  419.  * by hand, like so:
  420.  * <pre>
  421.  *      while (!APR_BRIGADE_EMPTY(b)) {
  422.  *          e = APR_BRIGADE_FIRST(b);
  423.  *          ...
  424.  *          apr_bucket_delete(e);
  425.  *      }
  426.  * </pre>
  427.  * @deprecated This macro causes more headaches than it's worth.  Use
  428.  * one of the alternatives documented here instead; the clarity gained
  429.  * in what's really going on is well worth the extra line or two of code.
  430.  * This macro will be removed at some point in the future.
  431.  */
  432. #define APR_BRIGADE_FOREACH(e, b)                    \
  433.     APR_RING_FOREACH((e), &(b)->list, apr_bucket, link)
  434.  
  435. /**
  436.  * Insert a list of buckets at the front of a brigade
  437.  * @param b The brigade to add to
  438.  * @param e The first bucket in a list of buckets to insert
  439.  */
  440. #define APR_BRIGADE_INSERT_HEAD(b, e) do {                \
  441.     apr_bucket *ap__b = (e);                                        \
  442.     APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);    \
  443.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  444.     } while (0)
  445.  
  446. /**
  447.  * Insert a list of buckets at the end of a brigade
  448.  * @param b The brigade to add to
  449.  * @param e The first bucket in a list of buckets to insert
  450.  */
  451. #define APR_BRIGADE_INSERT_TAIL(b, e) do {                \
  452.     apr_bucket *ap__b = (e);                    \
  453.     APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);    \
  454.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  455.     } while (0)
  456.  
  457. /**
  458.  * Concatenate brigade b onto the end of brigade a, leaving brigade b empty
  459.  * @param a The first brigade
  460.  * @param b The second brigade
  461.  */
  462. #define APR_BRIGADE_CONCAT(a, b) do {                    \
  463.         APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);    \
  464.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  465.     } while (0)
  466.  
  467. /**
  468.  * Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
  469.  * @param a The first brigade
  470.  * @param b The second brigade
  471.  */
  472. #define APR_BRIGADE_PREPEND(a, b) do {                    \
  473.         APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);    \
  474.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  475.     } while (0)
  476.  
  477. /**
  478.  * Insert a list of buckets before a specified bucket
  479.  * @param a The bucket to insert before
  480.  * @param b The buckets to insert
  481.  */
  482. #define APR_BUCKET_INSERT_BEFORE(a, b) do {                \
  483.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  484.     APR_RING_INSERT_BEFORE(ap__a, ap__b, link);            \
  485.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  486.     } while (0)
  487.  
  488. /**
  489.  * Insert a list of buckets after a specified bucket
  490.  * @param a The bucket to insert after
  491.  * @param b The buckets to insert
  492.  */
  493. #define APR_BUCKET_INSERT_AFTER(a, b) do {                \
  494.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  495.     APR_RING_INSERT_AFTER(ap__a, ap__b, link);            \
  496.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  497.     } while (0)
  498.  
  499. /**
  500.  * Get the next bucket in the list
  501.  * @param e The current bucket
  502.  * @return The next bucket
  503.  */
  504. #define APR_BUCKET_NEXT(e)    APR_RING_NEXT((e), link)
  505. /**
  506.  * Get the previous bucket in the list
  507.  * @param e The current bucket
  508.  * @return The previous bucket
  509.  */
  510. #define APR_BUCKET_PREV(e)    APR_RING_PREV((e), link)
  511.  
  512. /**
  513.  * Remove a bucket from its bucket brigade
  514.  * @param e The bucket to remove
  515.  */
  516. #define APR_BUCKET_REMOVE(e)    APR_RING_REMOVE((e), link)
  517.  
  518. /**
  519.  * Initialize a new bucket's prev/next pointers
  520.  * @param e The bucket to initialize
  521.  */
  522. #define APR_BUCKET_INIT(e)    APR_RING_ELEM_INIT((e), link)
  523.  
  524. /**
  525.  * Determine if a bucket contains metadata.  An empty bucket is
  526.  * safe to arbitrarily remove if and only if this is false.
  527.  * @param e The bucket to inspect
  528.  * @return true or false
  529.  */
  530. #define APR_BUCKET_IS_METADATA(e)    ((e)->type->is_metadata)
  531.  
  532. /**
  533.  * Determine if a bucket is a FLUSH bucket
  534.  * @param e The bucket to inspect
  535.  * @return true or false
  536.  */
  537. #define APR_BUCKET_IS_FLUSH(e)       ((e)->type == &apr_bucket_type_flush)
  538. /**
  539.  * Determine if a bucket is an EOS bucket
  540.  * @param e The bucket to inspect
  541.  * @return true or false
  542.  */
  543. #define APR_BUCKET_IS_EOS(e)         ((e)->type == &apr_bucket_type_eos)
  544. /**
  545.  * Determine if a bucket is a FILE bucket
  546.  * @param e The bucket to inspect
  547.  * @return true or false
  548.  */
  549. #define APR_BUCKET_IS_FILE(e)        ((e)->type == &apr_bucket_type_file)
  550. /**
  551.  * Determine if a bucket is a PIPE bucket
  552.  * @param e The bucket to inspect
  553.  * @return true or false
  554.  */
  555. #define APR_BUCKET_IS_PIPE(e)        ((e)->type == &apr_bucket_type_pipe)
  556. /**
  557.  * Determine if a bucket is a SOCKET bucket
  558.  * @param e The bucket to inspect
  559.  * @return true or false
  560.  */
  561. #define APR_BUCKET_IS_SOCKET(e)      ((e)->type == &apr_bucket_type_socket)
  562. /**
  563.  * Determine if a bucket is a HEAP bucket
  564.  * @param e The bucket to inspect
  565.  * @return true or false
  566.  */
  567. #define APR_BUCKET_IS_HEAP(e)        ((e)->type == &apr_bucket_type_heap)
  568. /**
  569.  * Determine if a bucket is a TRANSIENT bucket
  570.  * @param e The bucket to inspect
  571.  * @return true or false
  572.  */
  573. #define APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)
  574. /**
  575.  * Determine if a bucket is a IMMORTAL bucket
  576.  * @param e The bucket to inspect
  577.  * @return true or false
  578.  */
  579. #define APR_BUCKET_IS_IMMORTAL(e)    ((e)->type == &apr_bucket_type_immortal)
  580. #if APR_HAS_MMAP
  581. /**
  582.  * Determine if a bucket is a MMAP bucket
  583.  * @param e The bucket to inspect
  584.  * @return true or false
  585.  */
  586. #define APR_BUCKET_IS_MMAP(e)        ((e)->type == &apr_bucket_type_mmap)
  587. #endif
  588. /**
  589.  * Determine if a bucket is a POOL bucket
  590.  * @param e The bucket to inspect
  591.  * @return true or false
  592.  */
  593. #define APR_BUCKET_IS_POOL(e)        ((e)->type == &apr_bucket_type_pool)
  594.  
  595. /*
  596.  * General-purpose reference counting for the various bucket types.
  597.  *
  598.  * Any bucket type that keeps track of the resources it uses (i.e.
  599.  * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
  600.  * attach a reference count to the resource so that it can be freed
  601.  * when the last bucket that uses it goes away. Resource-sharing may
  602.  * occur because of bucket splits or buckets that refer to globally
  603.  * cached data. */
  604.  
  605. /** @see apr_bucket_refcount */
  606. typedef struct apr_bucket_refcount apr_bucket_refcount;
  607. /**
  608.  * The structure used to manage the shared resource must start with an
  609.  * apr_bucket_refcount which is updated by the general-purpose refcount
  610.  * code. A pointer to the bucket-type-dependent private data structure
  611.  * can be cast to a pointer to an apr_bucket_refcount and vice versa.
  612.  */
  613. struct apr_bucket_refcount {
  614.     /** The number of references to this bucket */
  615.     int          refcount;
  616. };
  617.  
  618. /*  *****  Reference-counted bucket types  *****  */
  619.  
  620. /** @see apr_bucket_heap */
  621. typedef struct apr_bucket_heap apr_bucket_heap;
  622. /**
  623.  * A bucket referring to data allocated off the heap.
  624.  */
  625. struct apr_bucket_heap {
  626.     /** Number of buckets using this memory */
  627.     apr_bucket_refcount  refcount;
  628.     /** The start of the data actually allocated.  This should never be
  629.      * modified, it is only used to free the bucket.
  630.      */
  631.     char    *base;
  632.     /** how much memory was allocated */
  633.     apr_size_t  alloc_len;
  634.     /** function to use to delete the data */
  635.     void (*free_func)(void *data);
  636. };
  637.  
  638. /** @see apr_bucket_pool */
  639. typedef struct apr_bucket_pool apr_bucket_pool;
  640. /**
  641.  * A bucket referring to data allocated from a pool
  642.  */
  643. struct apr_bucket_pool {
  644.     /** The pool bucket must be able to be easily morphed to a heap
  645.      * bucket if the pool gets cleaned up before all references are
  646.      * destroyed.  This apr_bucket_heap structure is populated automatically
  647.      * when the pool gets cleaned up, and subsequent calls to pool_read()
  648.      * will result in the apr_bucket in question being morphed into a
  649.      * regular heap bucket.  (To avoid having to do many extra refcount
  650.      * manipulations and b->data manipulations, the apr_bucket_pool
  651.      * struct actually *contains* the apr_bucket_heap struct that it
  652.      * will become as its first element; the two share their
  653.      * apr_bucket_refcount members.)
  654.      */
  655.     apr_bucket_heap  heap;
  656.     /** The block of data actually allocated from the pool.
  657.      * Segments of this block are referenced by adjusting
  658.      * the start and length of the apr_bucket accordingly.
  659.      * This will be NULL after the pool gets cleaned up.
  660.      */
  661.     const char *base;
  662.     /** The pool the data was allocated from.  When the pool
  663.      * is cleaned up, this gets set to NULL as an indicator
  664.      * to pool_read() that the data is now on the heap and
  665.      * so it should morph the bucket into a regular heap
  666.      * bucket before continuing.
  667.      */
  668.     apr_pool_t *pool;
  669.     /** The freelist this structure was allocated from, which is
  670.      * needed in the cleanup phase in order to allocate space on the heap
  671.      */
  672.     apr_bucket_alloc_t *list;
  673. };
  674.  
  675. #if APR_HAS_MMAP
  676. /** @see apr_bucket_mmap */
  677. typedef struct apr_bucket_mmap apr_bucket_mmap;
  678. /**
  679.  * A bucket referring to an mmap()ed file
  680.  */
  681. struct apr_bucket_mmap {
  682.     /** Number of buckets using this memory */
  683.     apr_bucket_refcount  refcount;
  684.     /** The mmap this sub_bucket refers to */
  685.     apr_mmap_t *mmap;
  686. };
  687. #endif
  688.  
  689. /** @see apr_bucket_file */
  690. typedef struct apr_bucket_file apr_bucket_file;
  691. /**
  692.  * A bucket referring to an file
  693.  */
  694. struct apr_bucket_file {
  695.     /** Number of buckets using this memory */
  696.     apr_bucket_refcount  refcount;
  697.     /** The file this bucket refers to */
  698.     apr_file_t *fd;
  699.     /** The pool into which any needed structures should
  700.      *  be created while reading from this file bucket */
  701.     apr_pool_t *readpool;
  702. #if APR_HAS_MMAP
  703.     /** Whether this bucket should be memory-mapped if
  704.      *  a caller tries to read from it */
  705.     int can_mmap;
  706. #endif /* APR_HAS_MMAP */
  707. };
  708.  
  709. /** @see apr_bucket_structs */
  710. typedef union apr_bucket_structs apr_bucket_structs;
  711. /**
  712.  * A union of all bucket structures so we know what
  713.  * the max size is.
  714.  */
  715. union apr_bucket_structs {
  716.     apr_bucket      b;      /**< Bucket */
  717.     apr_bucket_heap heap;   /**< Heap */
  718.     apr_bucket_pool pool;   /**< Pool */
  719. #if APR_HAS_MMAP
  720.     apr_bucket_mmap mmap;   /**< MMap */
  721. #endif
  722.     apr_bucket_file file;   /**< File */
  723. };
  724.  
  725. /**
  726.  * The amount that apr_bucket_alloc() should allocate in the common case.
  727.  * Note: this is twice as big as apr_bucket_structs to allow breathing
  728.  * room for third-party bucket types.
  729.  */
  730. #define APR_BUCKET_ALLOC_SIZE  APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
  731.  
  732. /*  *****  Bucket Brigade Functions  *****  */
  733. /**
  734.  * Create a new bucket brigade.  The bucket brigade is originally empty.
  735.  * @param p The pool to associate with the brigade.  Data is not allocated out
  736.  *          of the pool, but a cleanup is registered.
  737.  * @param list The bucket allocator to use
  738.  * @return The empty bucket brigade
  739.  */
  740. APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p,
  741.                                                      apr_bucket_alloc_t *list);
  742.  
  743. /**
  744.  * destroy an entire bucket brigade.  This includes destroying all of the
  745.  * buckets within the bucket brigade's bucket list. 
  746.  * @param b The bucket brigade to destroy
  747.  */
  748. APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b);
  749.  
  750. /**
  751.  * empty out an entire bucket brigade.  This includes destroying all of the
  752.  * buckets within the bucket brigade's bucket list.  This is similar to
  753.  * apr_brigade_destroy(), except that it does not deregister the brigade's
  754.  * pool cleanup function.
  755.  * @param data The bucket brigade to clean up
  756.  * @remark Generally, you should use apr_brigade_destroy().  This function
  757.  *         can be useful in situations where you have a single brigade that
  758.  *         you wish to reuse many times by destroying all of the buckets in
  759.  *         the brigade and putting new buckets into it later.
  760.  */
  761. APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data);
  762.  
  763. /**
  764.  * Split a bucket brigade into two, such that the given bucket is the
  765.  * first in the new bucket brigade. This function is useful when a
  766.  * filter wants to pass only the initial part of a brigade to the next
  767.  * filter.
  768.  * @param b The brigade to split
  769.  * @param e The first element of the new brigade
  770.  * @return The new brigade
  771.  */
  772. APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b,
  773.                                                     apr_bucket *e);
  774.  
  775. /**
  776.  * Partition a bucket brigade at a given offset (in bytes from the start of
  777.  * the brigade).  This is useful whenever a filter wants to use known ranges
  778.  * of bytes from the brigade; the ranges can even overlap.
  779.  * @param b The brigade to partition
  780.  * @param point The offset at which to partition the brigade
  781.  * @param after_point Returns a pointer to the first bucket after the partition
  782.  */
  783. APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b,
  784.                                                 apr_off_t point,
  785.                                                 apr_bucket **after_point);
  786.  
  787. #if APR_NOT_DONE_YET
  788. /**
  789.  * consume nbytes from beginning of b -- call apr_bucket_destroy as
  790.  * appropriate, and/or modify start on last element 
  791.  * @param b The brigade to consume data from
  792.  * @param nbytes The number of bytes to consume
  793.  */
  794. APU_DECLARE(void) apr_brigade_consume(apr_bucket_brigade *b,
  795.                                       apr_off_t nbytes);
  796. #endif
  797.  
  798. /**
  799.  * Return the total length of the brigade.
  800.  * @param bb The brigade to compute the length of
  801.  * @param read_all Read unknown-length buckets to force a size
  802.  * @param length Returns the length of the brigade, or -1 if the brigade has
  803.  *               buckets of indeterminate length and read_all is 0.
  804.  */
  805. APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
  806.                                              int read_all,
  807.                                              apr_off_t *length);
  808.  
  809. /**
  810.  * Take a bucket brigade and store the data in a flat char*
  811.  * @param bb The bucket brigade to create the char* from
  812.  * @param c The char* to write into
  813.  * @param len The maximum length of the char array. On return, it is the
  814.  *            actual length of the char array.
  815.  */
  816. APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb,
  817.                                               char *c,
  818.                                               apr_size_t *len);
  819.  
  820. /**
  821.  * Creates a pool-allocated string representing a flat bucket brigade
  822.  * @param bb The bucket brigade to create the char array from
  823.  * @param c On return, the allocated char array
  824.  * @param len On return, the length of the char array.
  825.  * @param pool The pool to allocate the string from.
  826.  */
  827. APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 
  828.                                                char **c,
  829.                                                apr_size_t *len,
  830.                                                apr_pool_t *pool);
  831.  
  832. /**
  833.  * Split a brigade to represent one LF line.
  834.  * @param bbOut The bucket brigade that will have the LF line appended to.
  835.  * @param bbIn The input bucket brigade to search for a LF-line.
  836.  * @param block The blocking mode to be used to split the line.
  837.  * @param maxbytes The maximum bytes to read.  If this many bytes are seen
  838.  *                 without a LF, the brigade will contain a partial line.
  839.  */
  840. APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut,
  841.                                                  apr_bucket_brigade *bbIn,
  842.                                                  apr_read_type_e block,
  843.                                                  apr_off_t maxbytes);
  844.  
  845. /**
  846.  * create an iovec of the elements in a bucket_brigade... return number 
  847.  * of elements used.  This is useful for writing to a file or to the
  848.  * network efficiently.
  849.  * @param b The bucket brigade to create the iovec from
  850.  * @param vec The iovec to create
  851.  * @param nvec The number of elements in the iovec. On return, it is the
  852.  *             number of iovec elements actually filled out.
  853.  */
  854. APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 
  855.                                                struct iovec *vec, int *nvec);
  856.  
  857. /**
  858.  * This function writes a list of strings into a bucket brigade. 
  859.  * @param b The bucket brigade to add to
  860.  * @param flush The flush function to use if the brigade is full
  861.  * @param ctx The structure to pass to the flush function
  862.  * @param va A list of strings to add
  863.  * @return APR_SUCCESS or error code.
  864.  */
  865. APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b,
  866.                                                apr_brigade_flush flush,
  867.                                                void *ctx,
  868.                                                va_list va);
  869.  
  870. /**
  871.  * This function writes a string into a bucket brigade.
  872.  * @param b The bucket brigade to add to
  873.  * @param flush The flush function to use if the brigade is full
  874.  * @param ctx The structure to pass to the flush function
  875.  * @param str The string to add
  876.  * @param nbyte The number of bytes to write
  877.  * @return APR_SUCCESS or error code
  878.  */
  879. APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b,
  880.                                             apr_brigade_flush flush, void *ctx,
  881.                                             const char *str, apr_size_t nbyte);
  882.  
  883. /**
  884.  * This function writes multiple strings into a bucket brigade.
  885.  * @param b The bucket brigade to add to
  886.  * @param flush The flush function to use if the brigade is full
  887.  * @param ctx The structure to pass to the flush function
  888.  * @param vec The strings to add (address plus length for each)
  889.  * @param nvec The number of entries in iovec
  890.  * @return APR_SUCCESS or error code
  891.  */
  892. APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b,
  893.                                              apr_brigade_flush flush,
  894.                                              void *ctx,
  895.                                              const struct iovec *vec,
  896.                                              apr_size_t nvec);
  897.  
  898. /**
  899.  * This function writes a string into a bucket brigade.
  900.  * @param bb The bucket brigade to add to
  901.  * @param flush The flush function to use if the brigade is full
  902.  * @param ctx The structure to pass to the flush function
  903.  * @param str The string to add
  904.  * @return APR_SUCCESS or error code
  905.  */
  906. APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb,
  907.                                            apr_brigade_flush flush, void *ctx,
  908.                                            const char *str);
  909.  
  910. /**
  911.  * This function writes a character into a bucket brigade.
  912.  * @param b The bucket brigade to add to
  913.  * @param flush The flush function to use if the brigade is full
  914.  * @param ctx The structure to pass to the flush function
  915.  * @param c The character to add
  916.  * @return APR_SUCCESS or error code
  917.  */
  918. APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b,
  919.                                            apr_brigade_flush flush, void *ctx,
  920.                                            const char c);
  921.  
  922. /**
  923.  * This function writes an unspecified number of strings into a bucket brigade.
  924.  * @param b The bucket brigade to add to
  925.  * @param flush The flush function to use if the brigade is full
  926.  * @param ctx The structure to pass to the flush function
  927.  * @param ... The strings to add
  928.  * @return APR_SUCCESS or error code
  929.  */
  930. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b,
  931.                                                      apr_brigade_flush flush,
  932.                                                      void *ctx, ...);
  933.  
  934. /**
  935.  * Evaluate a printf and put the resulting string at the end 
  936.  * of the bucket brigade.
  937.  * @param b The brigade to write to
  938.  * @param flush The flush function to use if the brigade is full
  939.  * @param ctx The structure to pass to the flush function
  940.  * @param fmt The format of the string to write
  941.  * @param ... The arguments to fill out the format
  942.  * @return APR_SUCCESS or error code
  943.  */
  944. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 
  945.                                                     apr_brigade_flush flush,
  946.                                                     void *ctx,
  947.                                                     const char *fmt, ...)
  948.         __attribute__((format(printf,4,5)));
  949.  
  950. /**
  951.  * Evaluate a printf and put the resulting string at the end 
  952.  * of the bucket brigade.
  953.  * @param b The brigade to write to
  954.  * @param flush The flush function to use if the brigade is full
  955.  * @param ctx The structure to pass to the flush function
  956.  * @param fmt The format of the string to write
  957.  * @param va The arguments to fill out the format
  958.  * @return APR_SUCCESS or error code
  959.  */
  960. APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 
  961.                                               apr_brigade_flush flush,
  962.                                               void *ctx,
  963.                                               const char *fmt, va_list va);
  964.  
  965. /*  *****  Bucket freelist functions *****  */
  966. /**
  967.  * Create a bucket allocator.
  968.  * @param p This pool's underlying apr_allocator_t is used to allocate memory
  969.  *          for the bucket allocator.  When the pool is destroyed, the bucket
  970.  *          allocator's cleanup routine will free all memory that has been
  971.  *          allocated from it.
  972.  * @remark  The reason the allocator gets its memory from the pool's
  973.  *          apr_allocator_t rather than from the pool itself is because
  974.  *          the bucket allocator will free large memory blocks back to the
  975.  *          allocator when it's done with them, thereby preventing memory
  976.  *          footprint growth that would occur if we allocated from the pool.
  977.  * @warning The allocator must never be used by more than one thread at a time.
  978.  */
  979. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p);
  980.  
  981. /**
  982.  * Create a bucket allocator.
  983.  * @param allocator This apr_allocator_t is used to allocate both the bucket
  984.  *          allocator and all memory handed out by the bucket allocator.  The
  985.  *          caller is responsible for destroying the bucket allocator and the
  986.  *          apr_allocator_t -- no automatic cleanups will happen.
  987.  * @warning The allocator must never be used by more than one thread at a time.
  988.  */
  989. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator);
  990.  
  991. /**
  992.  * Destroy a bucket allocator.
  993.  * @param list The allocator to be destroyed
  994.  */
  995. APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list);
  996.  
  997. /**
  998.  * Allocate memory for use by the buckets.
  999.  * @param size The amount to allocate.
  1000.  * @param list The allocator from which to allocate the memory.
  1001.  */
  1002. APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list);
  1003.  
  1004. /**
  1005.  * Free memory previously allocated with apr_bucket_alloc().
  1006.  * @param block The block of memory to be freed.
  1007.  */
  1008. APU_DECLARE_NONSTD(void) apr_bucket_free(void *block);
  1009.  
  1010.  
  1011. /*  *****  Bucket Functions  *****  */
  1012. /**
  1013.  * Free the resources used by a bucket. If multiple buckets refer to
  1014.  * the same resource it is freed when the last one goes away.
  1015.  * @see apr_bucket_delete()
  1016.  * @param e The bucket to destroy
  1017.  */
  1018. #define apr_bucket_destroy(e) do {                    \
  1019.         (e)->type->destroy((e)->data);                    \
  1020.         (e)->free(e);                            \
  1021.     } while (0)
  1022.  
  1023. /**
  1024.  * Delete a bucket by removing it from its brigade (if any) and then
  1025.  * destroying it.
  1026.  * @remark This mainly acts as an aid in avoiding code verbosity.  It is
  1027.  * the preferred exact equivalent to:
  1028.  * <pre>
  1029.  *      APR_BUCKET_REMOVE(e);
  1030.  *      apr_bucket_destroy(e);
  1031.  * </pre>
  1032.  * @param e The bucket to delete
  1033.  */
  1034. #define apr_bucket_delete(e) do {                    \
  1035.         APR_BUCKET_REMOVE(e);                        \
  1036.         apr_bucket_destroy(e);                        \
  1037.     } while (0)
  1038.  
  1039. /**
  1040.  * read the data from the bucket
  1041.  * @param e The bucket to read from
  1042.  * @param str The location to store the data in
  1043.  * @param len The amount of data read
  1044.  * @param block Whether the read function blocks
  1045.  */
  1046. #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
  1047.  
  1048. /**
  1049.  * Setaside data so that stack data is not destroyed on returning from
  1050.  * the function
  1051.  * @param e The bucket to setaside
  1052.  * @param p The pool to setaside into
  1053.  */
  1054. #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
  1055.  
  1056. /**
  1057.  * Split one bucket in two.
  1058.  * @param e The bucket to split
  1059.  * @param point The offset to split the bucket at
  1060.  */
  1061. #define apr_bucket_split(e,point) (e)->type->split(e, point)
  1062.  
  1063. /**
  1064.  * Copy a bucket.
  1065.  * @param e The bucket to copy
  1066.  * @param c Returns a pointer to the new bucket
  1067.  */
  1068. #define apr_bucket_copy(e,c) (e)->type->copy(e, c)
  1069.  
  1070. /* Bucket type handling */
  1071.  
  1072. /**
  1073.  * This function simply returns APR_SUCCESS to denote that the bucket does
  1074.  * not require anything to happen for its setaside() function. This is
  1075.  * appropriate for buckets that have "immortal" data -- the data will live
  1076.  * at least as long as the bucket.
  1077.  * @param data The bucket to setaside
  1078.  * @param pool The pool defining the desired lifetime of the bucket data
  1079.  * @return APR_SUCCESS
  1080.  */ 
  1081. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data,
  1082.                                                           apr_pool_t *pool);
  1083.  
  1084. /**
  1085.  * A place holder function that signifies that the setaside function was not
  1086.  * implemented for this bucket
  1087.  * @param data The bucket to setaside
  1088.  * @param pool The pool defining the desired lifetime of the bucket data
  1089.  * @return APR_ENOTIMPL
  1090.  */ 
  1091. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data,
  1092.                                                              apr_pool_t *pool);
  1093.  
  1094. /**
  1095.  * A place holder function that signifies that the split function was not
  1096.  * implemented for this bucket
  1097.  * @param data The bucket to split
  1098.  * @param point The location to split the bucket
  1099.  * @return APR_ENOTIMPL
  1100.  */ 
  1101. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data,
  1102.                                                           apr_size_t point);
  1103.  
  1104. /**
  1105.  * A place holder function that signifies that the copy function was not
  1106.  * implemented for this bucket
  1107.  * @param e The bucket to copy
  1108.  * @param c Returns a pointer to the new bucket
  1109.  * @return APR_ENOTIMPL
  1110.  */
  1111. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e,
  1112.                                                          apr_bucket **c);
  1113.  
  1114. /**
  1115.  * A place holder function that signifies that this bucket does not need
  1116.  * to do anything special to be destroyed.  That's only the case for buckets
  1117.  * that either have no data (metadata buckets) or buckets whose data pointer
  1118.  * points to something that's not a bucket-type-specific structure, as with
  1119.  * simple buckets where data points to a string and pipe buckets where data
  1120.  * points directly to the apr_file_t.
  1121.  * @param data The bucket data to destroy
  1122.  */ 
  1123. APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data);
  1124.  
  1125. /**
  1126.  * There is no apr_bucket_destroy_notimpl, because destruction is required
  1127.  * to be implemented (it could be a noop, but only if that makes sense for
  1128.  * the bucket type)
  1129.  */
  1130.  
  1131. /* There is no apr_bucket_read_notimpl, because it is a required function
  1132.  */
  1133.  
  1134.  
  1135. /* All of the bucket types implemented by the core */
  1136. /**
  1137.  * The flush bucket type.  This signifies that all data should be flushed to
  1138.  * the next filter.  The flush bucket should be sent with the other buckets.
  1139.  */
  1140. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
  1141. /**
  1142.  * The EOS bucket type.  This signifies that there will be no more data, ever.
  1143.  * All filters MUST send all data to the next filter when they receive a
  1144.  * bucket of this type
  1145.  */
  1146. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
  1147. /**
  1148.  * The FILE bucket type.  This bucket represents a file on disk
  1149.  */
  1150. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
  1151. /**
  1152.  * The HEAP bucket type.  This bucket represents a data allocated from the
  1153.  * heap.
  1154.  */
  1155. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
  1156. #if APR_HAS_MMAP
  1157. /**
  1158.  * The MMAP bucket type.  This bucket represents an MMAP'ed file
  1159.  */
  1160. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
  1161. #endif
  1162. /**
  1163.  * The POOL bucket type.  This bucket represents a data that was allocated
  1164.  * from a pool.  IF this bucket is still available when the pool is cleared,
  1165.  * the data is copied on to the heap.
  1166.  */
  1167. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
  1168. /**
  1169.  * The PIPE bucket type.  This bucket represents a pipe to another program.
  1170.  */
  1171. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
  1172. /**
  1173.  * The IMMORTAL bucket type.  This bucket represents a segment of data that
  1174.  * the creator is willing to take responsibility for.  The core will do
  1175.  * nothing with the data in an immortal bucket
  1176.  */
  1177. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
  1178. /**
  1179.  * The TRANSIENT bucket type.  This bucket represents a data allocated off
  1180.  * the stack.  When the setaside function is called, this data is copied on
  1181.  * to the heap
  1182.  */
  1183. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
  1184. /**
  1185.  * The SOCKET bucket type.  This bucket represents a socket to another machine
  1186.  */
  1187. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;
  1188.  
  1189.  
  1190. /*  *****  Simple buckets  *****  */
  1191.  
  1192. /**
  1193.  * Split a simple bucket into two at the given point.  Most non-reference
  1194.  * counting buckets that allow multiple references to the same block of
  1195.  * data (eg transient and immortal) will use this as their split function
  1196.  * without any additional type-specific handling.
  1197.  * @param b The bucket to be split
  1198.  * @param point The offset of the first byte in the new bucket
  1199.  * @return APR_EINVAL if the point is not within the bucket;
  1200.  *         APR_ENOMEM if allocation failed;
  1201.  *         or APR_SUCCESS
  1202.  */
  1203. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
  1204.                                                          apr_size_t point);
  1205.  
  1206. /**
  1207.  * Copy a simple bucket.  Most non-reference-counting buckets that allow
  1208.  * multiple references to the same block of data (eg transient and immortal)
  1209.  * will use this as their copy function without any additional type-specific
  1210.  * handling.
  1211.  * @param a The bucket to copy
  1212.  * @param b Returns a pointer to the new bucket
  1213.  * @return APR_ENOMEM if allocation failed;
  1214.  *         or APR_SUCCESS
  1215.  */
  1216. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
  1217.                                                         apr_bucket **b);
  1218.  
  1219.  
  1220. /*  *****  Shared, reference-counted buckets  *****  */
  1221.  
  1222. /**
  1223.  * Initialize a bucket containing reference-counted data that may be
  1224.  * shared. The caller must allocate the bucket if necessary and
  1225.  * initialize its type-dependent fields, and allocate and initialize
  1226.  * its own private data structure. This function should only be called
  1227.  * by type-specific bucket creation functions.
  1228.  * @param b The bucket to initialize
  1229.  * @param data A pointer to the private data structure
  1230.  *             with the reference count at the start
  1231.  * @param start The start of the data in the bucket
  1232.  *              relative to the private base pointer
  1233.  * @param length The length of the data in the bucket
  1234.  * @return The new bucket, or NULL if allocation failed
  1235.  */
  1236. APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
  1237.                                  apr_off_t start, 
  1238.                                                  apr_size_t length);
  1239.  
  1240. /**
  1241.  * Decrement the refcount of the data in the bucket. This function
  1242.  * should only be called by type-specific bucket destruction functions.
  1243.  * @param data The private data pointer from the bucket to be destroyed
  1244.  * @return TRUE or FALSE; TRUE if the reference count is now
  1245.  *         zero, indicating that the shared resource itself can
  1246.  *         be destroyed by the caller.
  1247.  */
  1248. APU_DECLARE(int) apr_bucket_shared_destroy(void *data);
  1249.  
  1250. /**
  1251.  * Split a bucket into two at the given point, and adjust the refcount
  1252.  * to the underlying data. Most reference-counting bucket types will
  1253.  * be able to use this function as their split function without any
  1254.  * additional type-specific handling.
  1255.  * @param b The bucket to be split
  1256.  * @param point The offset of the first byte in the new bucket
  1257.  * @return APR_EINVAL if the point is not within the bucket;
  1258.  *         APR_ENOMEM if allocation failed;
  1259.  *         or APR_SUCCESS
  1260.  */
  1261. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
  1262.                                                          apr_size_t point);
  1263.  
  1264. /**
  1265.  * Copy a refcounted bucket, incrementing the reference count. Most
  1266.  * reference-counting bucket types will be able to use this function
  1267.  * as their copy function without any additional type-specific handling.
  1268.  * @param a The bucket to copy
  1269.  * @param b Returns a pointer to the new bucket
  1270.  * @return APR_ENOMEM if allocation failed;
  1271.            or APR_SUCCESS
  1272.  */
  1273. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
  1274.                                                         apr_bucket **b);
  1275.  
  1276.  
  1277. /*  *****  Functions to Create Buckets of varying types  *****  */
  1278. /*
  1279.  * Each bucket type foo has two initialization functions:
  1280.  * apr_bucket_foo_make which sets up some already-allocated memory as a
  1281.  * bucket of type foo; and apr_bucket_foo_create which allocates memory
  1282.  * for the bucket, calls apr_bucket_make_foo, and initializes the
  1283.  * bucket's list pointers. The apr_bucket_foo_make functions are used
  1284.  * inside the bucket code to change the type of buckets in place;
  1285.  * other code should call apr_bucket_foo_create. All the initialization
  1286.  * functions change nothing if they fail.
  1287.  */
  1288.  
  1289. /**
  1290.  * Create an End of Stream bucket.  This indicates that there is no more data
  1291.  * coming from down the filter stack.  All filters should flush at this point.
  1292.  * @param list The freelist from which this bucket should be allocated
  1293.  * @return The new bucket, or NULL if allocation failed
  1294.  */
  1295. APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list);
  1296.  
  1297. /**
  1298.  * Make the bucket passed in an EOS bucket.  This indicates that there is no 
  1299.  * more data coming from down the filter stack.  All filters should flush at 
  1300.  * this point.
  1301.  * @param b The bucket to make into an EOS bucket
  1302.  * @return The new bucket, or NULL if allocation failed
  1303.  */
  1304. APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);
  1305.  
  1306. /**
  1307.  * Create a flush  bucket.  This indicates that filters should flush their
  1308.  * data.  There is no guarantee that they will flush it, but this is the
  1309.  * best we can do.
  1310.  * @param list The freelist from which this bucket should be allocated
  1311.  * @return The new bucket, or NULL if allocation failed
  1312.  */
  1313. APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list);
  1314.  
  1315. /**
  1316.  * Make the bucket passed in a FLUSH  bucket.  This indicates that filters 
  1317.  * should flush their data.  There is no guarantee that they will flush it, 
  1318.  * but this is the best we can do.
  1319.  * @param b The bucket to make into a FLUSH bucket
  1320.  * @return The new bucket, or NULL if allocation failed
  1321.  */
  1322. APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);
  1323.  
  1324. /**
  1325.  * Create a bucket referring to long-lived data.
  1326.  * @param buf The data to insert into the bucket
  1327.  * @param nbyte The size of the data to insert.
  1328.  * @param list The freelist from which this bucket should be allocated
  1329.  * @return The new bucket, or NULL if allocation failed
  1330.  */
  1331. APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 
  1332.                                                      apr_size_t nbyte,
  1333.                                                      apr_bucket_alloc_t *list);
  1334.  
  1335. /**
  1336.  * Make the bucket passed in a bucket refer to long-lived data
  1337.  * @param b The bucket to make into a IMMORTAL bucket
  1338.  * @param buf The data to insert into the bucket
  1339.  * @param nbyte The size of the data to insert.
  1340.  * @return The new bucket, or NULL if allocation failed
  1341.  */
  1342. APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 
  1343.                                                    const char *buf, 
  1344.                                                    apr_size_t nbyte);
  1345.  
  1346. /**
  1347.  * Create a bucket referring to data on the stack.
  1348.  * @param buf The data to insert into the bucket
  1349.  * @param nbyte The size of the data to insert.
  1350.  * @param list The freelist from which this bucket should be allocated
  1351.  * @return The new bucket, or NULL if allocation failed
  1352.  */
  1353. APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 
  1354.                                                       apr_size_t nbyte,
  1355.                                                       apr_bucket_alloc_t *list);
  1356.  
  1357. /**
  1358.  * Make the bucket passed in a bucket refer to stack data
  1359.  * @param b The bucket to make into a TRANSIENT bucket
  1360.  * @param buf The data to insert into the bucket
  1361.  * @param nbyte The size of the data to insert.
  1362.  * @return The new bucket, or NULL if allocation failed
  1363.  */
  1364. APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 
  1365.                                                     const char *buf,
  1366.                                                     apr_size_t nbyte);
  1367.  
  1368. /**
  1369.  * Create a bucket referring to memory on the heap. If the caller asks
  1370.  * for the data to be copied, this function always allocates 4K of
  1371.  * memory so that more data can be added to the bucket without
  1372.  * requiring another allocation. Therefore not all the data may be put
  1373.  * into the bucket. If copying is not requested then the bucket takes
  1374.  * over responsibility for free()ing the memory.
  1375.  * @param buf The buffer to insert into the bucket
  1376.  * @param nbyte The size of the buffer to insert.
  1377.  * @param free_func Function to use to free the data; NULL indicates that the
  1378.  *                  bucket should make a copy of the data
  1379.  * @param list The freelist from which this bucket should be allocated
  1380.  * @return The new bucket, or NULL if allocation failed
  1381.  */
  1382. APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 
  1383.                                                  apr_size_t nbyte,
  1384.                                                  void (*free_func)(void *data),
  1385.                                                  apr_bucket_alloc_t *list);
  1386. /**
  1387.  * Make the bucket passed in a bucket refer to heap data
  1388.  * @param b The bucket to make into a HEAP bucket
  1389.  * @param buf The buffer to insert into the bucket
  1390.  * @param nbyte The size of the buffer to insert.
  1391.  * @param free_func Function to use to free the data; NULL indicates that the
  1392.  *                  bucket should make a copy of the data
  1393.  * @return The new bucket, or NULL if allocation failed
  1394.  */
  1395. APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf,
  1396.                                                apr_size_t nbyte,
  1397.                                                void (*free_func)(void *data));
  1398.  
  1399. /**
  1400.  * Create a bucket referring to memory allocated from a pool.
  1401.  *
  1402.  * @param buf The buffer to insert into the bucket
  1403.  * @param length The number of bytes referred to by this bucket
  1404.  * @param pool The pool the memory was allocated from
  1405.  * @param list The freelist from which this bucket should be allocated
  1406.  * @return The new bucket, or NULL if allocation failed
  1407.  */
  1408. APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 
  1409.                                                  apr_size_t length,
  1410.                                                  apr_pool_t *pool,
  1411.                                                  apr_bucket_alloc_t *list);
  1412.  
  1413. /**
  1414.  * Make the bucket passed in a bucket refer to pool data
  1415.  * @param b The bucket to make into a pool bucket
  1416.  * @param buf The buffer to insert into the bucket
  1417.  * @param length The number of bytes referred to by this bucket
  1418.  * @param pool The pool the memory was allocated from
  1419.  * @return The new bucket, or NULL if allocation failed
  1420.  */
  1421. APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf,
  1422.                                                apr_size_t length, 
  1423.                                                apr_pool_t *pool);
  1424.  
  1425. #if APR_HAS_MMAP
  1426. /**
  1427.  * Create a bucket referring to mmap()ed memory.
  1428.  * @param mm The mmap to insert into the bucket
  1429.  * @param start The offset of the first byte in the mmap
  1430.  *              that this bucket refers to
  1431.  * @param length The number of bytes referred to by this bucket
  1432.  * @param list The freelist from which this bucket should be allocated
  1433.  * @return The new bucket, or NULL if allocation failed
  1434.  */
  1435. APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 
  1436.                                                  apr_off_t start,
  1437.                                                  apr_size_t length,
  1438.                                                  apr_bucket_alloc_t *list);
  1439.  
  1440. /**
  1441.  * Make the bucket passed in a bucket refer to an MMAP'ed file
  1442.  * @param b The bucket to make into a MMAP bucket
  1443.  * @param mm The mmap to insert into the bucket
  1444.  * @param start The offset of the first byte in the mmap
  1445.  *              that this bucket refers to
  1446.  * @param length The number of bytes referred to by this bucket
  1447.  * @return The new bucket, or NULL if allocation failed
  1448.  */
  1449. APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm,
  1450.                                                apr_off_t start, 
  1451.                                                apr_size_t length);
  1452. #endif
  1453.  
  1454. /**
  1455.  * Create a bucket referring to a socket.
  1456.  * @param thissock The socket to put in the bucket
  1457.  * @param list The freelist from which this bucket should be allocated
  1458.  * @return The new bucket, or NULL if allocation failed
  1459.  */
  1460. APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock,
  1461.                                                    apr_bucket_alloc_t *list);
  1462. /**
  1463.  * Make the bucket passed in a bucket refer to a socket
  1464.  * @param b The bucket to make into a SOCKET bucket
  1465.  * @param thissock The socket to put in the bucket
  1466.  * @return The new bucket, or NULL if allocation failed
  1467.  */
  1468. APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 
  1469.                                                  apr_socket_t *thissock);
  1470.  
  1471. /**
  1472.  * Create a bucket referring to a pipe.
  1473.  * @param thispipe The pipe to put in the bucket
  1474.  * @param list The freelist from which this bucket should be allocated
  1475.  * @return The new bucket, or NULL if allocation failed
  1476.  */
  1477. APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe,
  1478.                                                  apr_bucket_alloc_t *list);
  1479.  
  1480. /**
  1481.  * Make the bucket passed in a bucket refer to a pipe
  1482.  * @param b The bucket to make into a PIPE bucket
  1483.  * @param thispipe The pipe to put in the bucket
  1484.  * @return The new bucket, or NULL if allocation failed
  1485.  */
  1486. APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 
  1487.                                                apr_file_t *thispipe);
  1488.  
  1489. /**
  1490.  * Create a bucket referring to a file.
  1491.  * @param fd The file to put in the bucket
  1492.  * @param offset The offset where the data of interest begins in the file
  1493.  * @param len The amount of data in the file we are interested in
  1494.  * @param p The pool into which any needed structures should be created
  1495.  *          while reading from this file bucket
  1496.  * @param list The freelist from which this bucket should be allocated
  1497.  * @return The new bucket, or NULL if allocation failed
  1498.  */
  1499. APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd,
  1500.                                                  apr_off_t offset,
  1501.                                                  apr_size_t len, 
  1502.                                                  apr_pool_t *p,
  1503.                                                  apr_bucket_alloc_t *list);
  1504.  
  1505. /**
  1506.  * Make the bucket passed in a bucket refer to a file
  1507.  * @param b The bucket to make into a FILE bucket
  1508.  * @param fd The file to put in the bucket
  1509.  * @param offset The offset where the data of interest begins in the file
  1510.  * @param len The amount of data in the file we are interested in
  1511.  * @param p The pool into which any needed structures should be created
  1512.  *          while reading from this file bucket
  1513.  * @return The new bucket, or NULL if allocation failed
  1514.  */
  1515. APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
  1516.                                                apr_off_t offset,
  1517.                                                apr_size_t len, apr_pool_t *p);
  1518.  
  1519. /**
  1520.  * Enable or disable memory-mapping for a FILE bucket (default is enabled)
  1521.  * @param b The bucket
  1522.  * @param enabled Whether memory-mapping should be enabled
  1523.  * @return APR_SUCCESS normally, or an error code if the operation fails
  1524.  */
  1525. APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b,
  1526.                                                       int enabled);
  1527.  
  1528. /** @} */
  1529. #ifdef __cplusplus
  1530. }
  1531. #endif
  1532.  
  1533. #endif /* !APR_BUCKETS_H */
  1534.