apr_buckets.h

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

 *              relative to the private base pointer
 * @param length The length of the data in the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_shared_make(apr_bucket_refcount *r, apr_off_t start, apr_off_t length) 
 */
APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
				      apr_off_t start, apr_off_t length);

/**
 * Decrement the refcount of the data in the bucket. This function
 * should only be called by type-specific bucket destruction functions.
 * @param data The private data pointer from the bucket to be destroyed
 * @return TRUE or FALSE; TRUE if the reference count is now
 *         zero, indicating that the shared resource itself can
 *         be destroyed by the caller.
 * @deffunc int apr_bucket_shared_destroy(void *data)
 */
APU_DECLARE(int) apr_bucket_shared_destroy(void *data);

/**
 * Split a bucket into two at the given point, and adjust the refcount
 * to the underlying data. Most reference-counting bucket types will
 * be able to use this function 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_shared_split(apr_bucket *b, apr_off_t point)
 */
APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
                                                         apr_off_t point);

/**
 * Copy a refcounted bucket, incrementing the reference count. Most
 * reference-counting bucket types will be able to use this function
 * 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_shared_copy(apr_bucket *a, apr_bucket **b)
 */
APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
                                                        apr_bucket **b);


/*  *****  Functions to Create Buckets of varying types  *****  */
/*
 * Each bucket type foo has two initialization functions:
 * apr_bucket_make_foo which sets up some already-allocated memory as a
 * bucket of type foo; and apr_bucket_create_foo which allocates memory
 * for the bucket, calls apr_bucket_make_foo, and initializes the
 * bucket's list pointers. The apr_bucket_make_foo functions are used
 * inside the bucket code to change the type of buckets in place;
 * other code should call apr_bucket_create_foo. All the initialization
 * functions change nothing if they fail.
 */

/*
 * This macro implements the guts of apr_bucket_create_foo
 */
#define apr_bucket_do_create(do_make)		\
    do {					\
	apr_bucket *b, *ap__b;			\
	b = calloc(1, sizeof(*b));		\
	if (b == NULL) {			\
	    return NULL;			\
	}					\
	ap__b = do_make;			\
	if (ap__b == NULL) {			\
	    free(b);				\
	    return NULL;			\
	}					\
	APR_RING_ELEM_INIT(ap__b, link);	\
	return ap__b;				\
    } while(0)

/**
 * Create an End of Stream bucket.  This indicates that there is no more data
 * coming from down the filter stack.  All filters should flush at this point.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_eos_create(void)
 */
APU_DECLARE(apr_bucket *) apr_bucket_eos_create(void);

/**
 * Make the bucket passed in an EOS bucket.  This indicates that there is no 
 * more data coming from down the filter stack.  All filters should flush at 
 * this point.
 * @param b The bucket to make into an EOS bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_eos_make(apr_bucket *b)
 */
APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);

/**
 * Create a flush  bucket.  This indicates that filters should flush their
 * data.  There is no guarantee that they will flush it, but this is the
 * best we can do.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_flush_create(void)
 */
APU_DECLARE(apr_bucket *) apr_bucket_flush_create(void);

/**
 * Make the bucket passed in a FLUSH  bucket.  This indicates that filters 
 * should flush their data.  There is no guarantee that they will flush it, 
 * but this is the best we can do.
 * @param b The bucket to make into a FLUSH bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_flush_make(apr_bucket *b)
 */
APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);

/**
 * Create a bucket referring to long-lived data.
 * @param buf The data to insert into the bucket
 * @param nbyte The size of the data to insert.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_immortal_create(const char *buf, apr_size_t nbyte, apr_size_t *w)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_immortal_create(const char *buf, apr_size_t nbyte);

/**
 * Make the bucket passed in a bucket refer to long-lived data
 * @param b The bucket to make into a IMMORTAL bucket
 * @param buf The data to insert into the bucket
 * @param nbyte The size of the data to insert.
 * @param w The number of bytes added to the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_immortal_make(apr_bucket *b, const char *buf, apr_size_t nbyte, apr_size_t *w)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_immortal_make(apr_bucket *b, const char *buf, 
                                        apr_size_t nbyte);

/**
 * Create a bucket referring to data on the stack.
 * @param buf The data to insert into the bucket
 * @param nbyte The size of the data to insert.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_transient_create(const char *buf, apr_size_t nbyte, apr_size_t *w)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_transient_create(const char *buf, apr_size_t nbyte);

/**
 * Make the bucket passed in a bucket refer to stack data
 * @param b The bucket to make into a TRANSIENT bucket
 * @param buf The data to insert into the bucket
 * @param nbyte The size of the data to insert.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_transient_make(apr_bucket *b, const char *buf, apr_size_t nbyte)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_transient_make(apr_bucket *b, const char *buf,
                                         apr_size_t nbyte);

/**
 * Create a bucket referring to memory on the heap. If the caller asks
 * for the data to be copied, this function always allocates 4K of
 * memory so that more data can be added to the bucket without
 * requiring another allocation. Therefore not all the data may be put
 * into the bucket. If copying is not requested then the bucket takes
 * over responsibility for free()ing the memory.
 * @param buf The buffer to insert into the bucket
 * @param nbyte The size of the buffer to insert.
 * @param copy Whether to copy the data into newly-allocated memory or not
 * @param w The number of bytes actually copied into the bucket.
 *          If copy is zero then this return value can be ignored by passing a NULL pointer.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_heap_create(const char *buf, apr_size_t nbyte, int copy, apr_size_t *w)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_heap_create(const char *buf, apr_size_t nbyte, 
                                      int copy, apr_size_t *w);
/**
 * Make the bucket passed in a bucket refer to heap data
 * @param b The bucket to make into a HEAP bucket
 * @param buf The buffer to insert into the bucket
 * @param nbyte The size of the buffer to insert.
 * @param copy Whether to copy the data into newly-allocated memory or not
 * @param w The number of bytes actually copied into the bucket.
 *          If copy is zero then this return value can be ignored by passing a NULL pointer.
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_heap_make(apr_bucket *b, const char *buf, apr_size_t nbyte, int copy, apr_size_t *w)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_heap_make(apr_bucket *b, const char *buf,
                                    apr_size_t nbyte, int copy, apr_size_t *w);

/**
 * Create a bucket referring to memory allocated from a pool.
 *
 * @param buf The buffer to insert into the bucket
 * @param pool The pool the memory was allocated from
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_pool_create(const char *buf, apr_size_t *length, apr_pool_t *pool)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_pool_create(const char *buf, apr_size_t length,
                                      apr_pool_t *pool);

/**
 * Make the bucket passed in a bucket refer to pool data
 * @param b The bucket to make into a pool bucket
 * @param buf The buffer to insert into the bucket
 * @param pool The pool the memory was allocated from
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_pool_make(apr_bucket *b, const char *buf, apr_size_t *length, apr_pool_t *pool)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_pool_make(apr_bucket *b, const char *buf, 
                                    apr_size_t length, apr_pool_t *pool);

#if APR_HAS_MMAP
/**
 * Create a bucket referring to mmap()ed memory.
 * @param mmap The mmap to insert into the bucket
 * @param start The offset of the first byte in the mmap
 *              that this bucket refers to
 * @param length The number of bytes referred to by this bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_mmap_create(const apr_mmap_t *mm, apr_size_t start, apr_size_t length)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_mmap_create(apr_mmap_t *mm, apr_off_t start,
                                      apr_size_t length);

/**
 * Make the bucket passed in a bucket refer to an MMAP'ed file
 * @param b The bucket to make into a MMAP bucket
 * @param mmap The mmap to insert into the bucket
 * @param start The offset of the first byte in the mmap
 *              that this bucket refers to
 * @param length The number of bytes referred to by this bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_mmap_make(apr_bucket *b, const apr_mmap_t *mm, apr_size_t start, apr_size_t length)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm, 
                                    apr_off_t start, apr_size_t length);
#endif

/**
 * Create a bucket referring to a socket.
 * @param thissocket The socket to put in the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_socket_create(apr_socket_t *thissocket)
 */
APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock);
/**
 * Make the bucket passed in a bucket refer to a socket
 * @param b The bucket to make into a SOCKET bucket
 * @param thissocket The socket to put in the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_socket_make(apr_bucket *b, apr_socket_t *thissocket)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_socket_make(apr_bucket *b, apr_socket_t *thissock);

/**
 * Create a bucket referring to a pipe.
 * @param thispipe The pipe to put in the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_pipe_create(apr_file_t *thispipe)
 */
APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe);

/**
 * Make the bucket passed in a bucket refer to a pipe
 * @param b The bucket to make into a PIPE bucket
 * @param thispipe The pipe to put in the bucket
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_pipe_make(apr_bucket *b, apr_file_t *thispipe)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_pipe_make(apr_bucket *b, apr_file_t *thispipe);

/**
 * Create a bucket referring to a file.
 * @param fd The file to put in the bucket
 * @param offset The offset where the data of interest begins in the file
 * @param len The amount of data in the file we are interested in
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_file_create(apr_file_t *fd, apr_off_t offset, apr_size_t len)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_file_create(apr_file_t *fd, apr_off_t offset,
                                      apr_size_t len);

/**
 * Make the bucket passed in a bucket refer to a file
 * @param b The bucket to make into a FILE bucket
 * @param fd The file to put in the bucket
 * @param offset The offset where the data of interest begins in the file
 * @param len The amount of data in the file we are interested in
 * @return The new bucket, or NULL if allocation failed
 * @deffunc apr_bucket *apr_bucket_file_make(apr_bucket *b, apr_file_t *fd, apr_off_t offset, apr_size_t len)
 */
APU_DECLARE(apr_bucket *) 
                apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
                                    apr_off_t offset, apr_size_t len);

#ifdef __cplusplus
}
#endif

#endif /* !APR_BUCKETS_H */