apr_buckets.h

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

 * @param bb The brigade to compute the length of
 * @param read_all Read unknown-length buckets to force a size
 @ @param length Set to length of the brigade, or -1 if it has unknown-length buckets
 * @deffunc apr_status_t apr_brigade_length(apr_bucket_brigade *bb, int read_all)
 */
APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
                                             int read_all,
                                             apr_ssize_t *length);

/**
 * create an iovec of the elements in a bucket_brigade... return number 
 * of elements used.  This is useful for writing to a file or to the
 * network efficiently.
 * @param The bucket brigade to create the iovec from
 * @param The iovec to create
 * @param The number of elements in the iovec
 * @return The number of iovec elements actually filled out.
 * @deffunc int apr_brigade_to_iovec(apr_bucket_brigade *b, struct iovec *vec, int nvec);
 */
APU_DECLARE(int) apr_brigade_to_iovec(apr_bucket_brigade *b, 
				     struct iovec *vec, int nvec);

/**
 * This function writes a list of strings into a bucket brigade. 
 * @param b The bucket brigade to add to
 * @param va A list of strings to add
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_vputstrs(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, va_list va)
 */
APU_DECLARE(int) apr_brigade_vputstrs(apr_bucket_brigade *b,
                                      apr_brigade_flush flush, void *ctx,
                                      va_list va);

/**
 * This function writes an string into a bucket brigade.
 * @param b The bucket brigade to add to
 * @param str The string to add
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_write(ap_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *str, apr_size_t nbyte)
 */
APU_DECLARE(int) apr_brigade_write(apr_bucket_brigade *b,
                                   apr_brigade_flush flush, void *ctx,
                                   const char *str, apr_size_t nbyte);

/**
 * This function writes an string into a bucket brigade.
 * @param b The bucket brigade to add to
 * @param str The string to add
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_puts(ap_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *str)
 */
APU_DECLARE(int) apr_brigade_puts(apr_bucket_brigade *b,
                                  apr_brigade_flush flush, void *ctx,
                                  const char *str);

/**
 * This function writes a character into a bucket brigade.
 * @param b The bucket brigade to add to
 * @param c The character to add
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_putc(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char c)
 */
APU_DECLARE(int) apr_brigade_putc(apr_bucket_brigade *b,
                                  apr_brigade_flush flush, void *ctx,
                                  const char c);

/**
 * This function writes an unspecified number of strings into a bucket brigade.
 * @param b The bucket brigade to add to
 * @param ... The strings to add
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_putstrs(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, ...)
 */
APU_DECLARE_NONSTD(int) apr_brigade_putstrs(apr_bucket_brigade *b,
                                            apr_brigade_flush flush,
                                            void *ctx, ...);

/**
 * Evaluate a printf and put the resulting string at the end 
 * of the bucket brigade.
 * @param b The brigade to write to
 * @param fmt The format of the string to write
 * @param ... The arguments to fill out the format
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_printf(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt, ...) 
 */
APU_DECLARE_NONSTD(int) apr_brigade_printf(apr_bucket_brigade *b, 
                                           apr_brigade_flush flush, void *ctx,
                                           const char *fmt, ...)
        __attribute__((format(printf,4,5)));

/**
 * Evaluate a printf and put the resulting string at the end 
 * of the bucket brigade.
 * @param b The brigade to write to
 * @param fmt The format of the string to write
 * @param va The arguments to fill out the format
 * @return The number of bytes added to the brigade
 * @deffunc int apr_brigade_vprintf(apr_bucket_brigade *b, apr_brigade_flush flush, void *ctx, const char *fmt, va_list va) 
 */
APU_DECLARE(int) apr_brigade_vprintf(apr_bucket_brigade *b, 
                                     apr_brigade_flush flush, void *ctx,
                                     const char *fmt, va_list va);


/*  *****  Bucket Functions  *****  */
/**
 * Free the resources used by a bucket. If multiple buckets refer to
 * the same resource it is freed when the last one goes away.
 * @see apr_bucket_delete()
 * @param e The bucket to destroy
 * @deffunc void apr_bucket_destroy(apr_bucket *e)
 */
#define apr_bucket_destroy(e) do {					\
        e->type->destroy(e->data);					\
        free(e);							\
    } while (0)

/**
 * Delete a bucket by removing it from its brigade (if any) and then
 * destroying it.
 * @tip This mainly acts as an aid in avoiding code verbosity.  It is
 * the preferred exact equivalent to:
 * <pre>
 *      APR_BUCKET_REMOVE(e);
 *      apr_bucket_destroy(e);
 * </pre>
 * @param e The bucket to delete
 * @deffunc void apr_bucket_delete(apr_bucket *e)
 */
#define apr_bucket_delete(e) do {					\
        APR_BUCKET_REMOVE(e);						\
        apr_bucket_destroy(e);						\
    } while (0)

/**
 * read the data from the bucket
 * @param e The bucket to read from
 * @param str The location to store the data in
 * @param len The amount of data read
 * @param block Whether the read function blocks
 * @deffunc apr_status_t apr_bucket_read(apr_bucket *e, const char **str, apr_size_t *len, apr_read_type_e block)
 */
#define apr_bucket_read(e,str,len,block) e->type->read(e, str, len, block)

/**
 * Setaside data so that stack data is not destroyed on returning from
 * the function
 * @param e The bucket to setaside
 * @deffunc apr_status_t apr_bucket_setaside(apr_bucket *e)
 */
#define apr_bucket_setaside(e) e->type->setaside(e)

/**
 * Split one bucket in two.
 * @param e The bucket to split
 * @param point The offset to split the bucket at
 * @deffunc apr_status_t apr_bucket_split(apr_bucket *e, apr_off_t point)
 */
#define apr_bucket_split(e,point) e->type->split(e, point)

/**
 * Copy a bucket.
 * @param e The bucket to copy
 * @param c Returns a pointer to the new bucket
 * @deffunc apr_status_t apr_bucket_copy(apr_bucket *e, apr_bucket **c)
 */
#define apr_bucket_copy(e,c) e->type->copy(e, c)

/* Bucket type handling */

/**
 * A place holder function that signifies that the setaside function was not
 * implemented for this bucket
 * @param data The bucket to setaside
 * @return APR_ENOTIMPL
 * @deffunc apr_status_t apr_bucket_setaside_notimpl(apr_bucket *data)
 */ 
APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data);

/**
 * A place holder function that signifies that the split function was not
 * implemented for this bucket
 * @param data The bucket to split
 * @param point The location to split the bucket
 * @return APR_ENOTIMPL
 * @deffunc apr_status_t apr_bucket_split_notimpl(apr_bucket *data, apr_off_t point)
 */ 
APU_DECLARE_NONSTD(apr_status_t) 
                       apr_bucket_split_notimpl(apr_bucket *data, 
                                               apr_off_t point);

/**
 * A place holder function that signifies that the copy function was not
 * implemented for this bucket
 * @param e The bucket to copy
 * @param c Returns a pointer to the new bucket
 * @return APR_ENOTIMPL
 * @deffunc apr_status_t apr_bucket_copy_notimpl(apr_bucket *e, apr_bucket **c)
 */
APU_DECLARE_NONSTD(apr_status_t) 
                       apr_bucket_copy_notimpl(apr_bucket *e, apr_bucket **c);

/**
 * A place holder function that signifies that the destroy function was not
 * implemented for this bucket
 * @param data The bucket to destroy
 * @deffunc void apr_bucket_destroy_notimpl(void *data)
 */ 
APU_DECLARE_NONSTD(void) apr_bucket_destroy_notimpl(void *data);

/* There is no apr_bucket_read_notimpl, because it is a required function
 */


/* All of the bucket types implemented by the core */
/**
 * The flush bucket type.  This signifies that all data should be flushed to
 * the next filter.  The flush bucket should be sent with the other buckets.
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
/**
 * The EOS bucket type.  This signifies that there will be no more data, ever.
 * All filters MUST send all data to the next filter when they receive a
 * bucket of this type
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
/**
 * The FILE bucket type.  This bucket represents a file on disk
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
/**
 * The HEAP bucket type.  This bucket represents a data allocated from the
 * heap.
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
#if APR_HAS_MMAP
/**
 * The MMAP bucket type.  This bucket represents an MMAP'ed file
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
#endif
/**
 * The POOL bucket type.  This bucket represents a data that was allocated
 * from a pool.  IF this bucket is still available when the pool is cleared,
 * the data is copied on to the heap.
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
/**
 * The PIPE bucket type.  This bucket represents a pipe to another program.
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
/**
 * The IMMORTAL bucket type.  This bucket represents a segment of data that
 * the creator is willing to take responsability for.  The core will do
 * nothing with the data in an immortal bucket
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
/**
 * The TRANSIENT bucket type.  This bucket represents a data allocated off
 * the stack.  When the setaside function is called, this data is copied on
 * to the heap
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
/**
 * The SOCKET bucket type.  This bucket represents a socket to another machine
 */
APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;


/*  *****  Simple buckets  *****  */

/**
 * Split a simple bucket into two at the given point.  Most non-reference
 * counting buckets that allow multiple references to the same block of
 * data (eg transient and immortal) will use this as their split function
 * without any additional type-specific handling.
 * @param b The bucket to be split
 * @param point The offset of the first byte in the new bucket
 * @return APR_EINVAL if the point is not within the bucket;
 *         APR_ENOMEM if allocation failed;
 *         or APR_SUCCESS
 * @deffunc apr_status_t apr_bucket_simple_split(apr_bucket *b, apr_off_t point)
 */
APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
                                                         apr_off_t point);

/**
 * Copy a simple bucket.  Most non-reference-counting buckets that allow
 * multiple references to the same block of data (eg transient and immortal)
 * will use this as their copy function without any additional type-specific
 * handling.
 * @param a The bucket to copy
 * @param b Returns a pointer to the new bucket
 * @return APR_ENOMEM if allocation failed;
 *         or APR_SUCCESS
 * @deffunc apr_status_t apr_bucket_simple_copy(apr_bucket *a, apr_bucket **b)
 */
APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
                                                        apr_bucket **b);


/*  *****  Shared, reference-counted buckets  *****  */

/**
 * Initialize a bucket containing reference-counted data that may be
 * shared. The caller must allocate the bucket if necessary and
 * initialize its type-dependent fields, and allocate and initialize
 * its own private data structure. This function should only be called
 * by type-specific bucket creation functions.
 * @param b The bucket to initialize
 * @param data A pointer to the private data structure
 *             with the reference count at the start
 * @param start The start of the data in the bucket