Apache Portable Runtime Utility Library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Types | Data Fields
apr_bucket_type_t Struct Reference

#include <apr_buckets.h>

Public Types

enum  { APR_BUCKET_DATA = 0, APR_BUCKET_METADATA = 1 }

Data Fields

const char * name
int num_func
enum apr_bucket_type_t:: { ... }  is_metadata
void(* destroy )(void *data)
apr_status_t(* read )(apr_bucket *b, const char **str, apr_size_t *len, apr_read_type_e block)
apr_status_t(* setaside )(apr_bucket *e, apr_pool_t *pool)
apr_status_t(* split )(apr_bucket *e, apr_size_t point)
apr_status_t(* copy )(apr_bucket *e, apr_bucket **c)

Detailed Description

Basic bucket type

Member Enumeration Documentation

anonymous enum

Whether the bucket contains metadata (ie, information that describes the regular contents of the brigade). The metadata is not returned by apr_bucket_read() and is not indicated by the ->length of the apr_bucket itself. In other words, an empty bucket is safe to arbitrarily remove if and only if it contains no metadata. In this sense, "data" is just raw bytes that are the "content" of the brigade and "metadata" describes that data but is not a proper part of it.

Enumerator:
APR_BUCKET_DATA 

This bucket type represents actual data to send to the client.

APR_BUCKET_METADATA 

This bucket type represents metadata.

Field Documentation

apr_status_t(* apr_bucket_type_t::copy)(apr_bucket *e, apr_bucket **c)

Copy the bucket structure (not the data), assuming that this is possible for the bucket type. If it's not, APR_ENOTIMPL is returned.

Parameters
eThe bucket to copy
cReturns a pointer to the new bucket
void(* apr_bucket_type_t::destroy)(void *data)

Free the private data and any resources used by the bucket (if they aren't shared with another bucket). This function is required to be implemented for all bucket types, though it might be a no-op on some of them (namely ones that never allocate any private data structures).

Parameters
dataThe private data pointer from the bucket to be destroyed
enum { ... } apr_bucket_type_t::is_metadata

Whether the bucket contains metadata (ie, information that describes the regular contents of the brigade). The metadata is not returned by apr_bucket_read() and is not indicated by the ->length of the apr_bucket itself. In other words, an empty bucket is safe to arbitrarily remove if and only if it contains no metadata. In this sense, "data" is just raw bytes that are the "content" of the brigade and "metadata" describes that data but is not a proper part of it.

const char* apr_bucket_type_t::name

The name of the bucket type

int apr_bucket_type_t::num_func

The number of functions this bucket understands. Can not be less than five.

apr_status_t(* apr_bucket_type_t::read)(apr_bucket *b, const char **str, apr_size_t *len, apr_read_type_e block)

Read the data from the bucket. This is required to be implemented for all bucket types.

Parameters
bThe bucket to read from
strA place to store the data read. Allocation should only be done if absolutely necessary.
lenThe amount of data read.
blockShould this read function block if there is more data that cannot be read immediately.
apr_status_t(* apr_bucket_type_t::setaside)(apr_bucket *e, apr_pool_t *pool)

Make it possible to set aside the data for at least as long as the given pool. Buckets containing data that could potentially die before this pool (e.g. the data resides on the stack, in a child pool of the given pool, or in a disjoint pool) must somehow copy, shift, or transform the data to have the proper lifetime.

Parameters
eThe bucket to convert
Remarks
Some bucket types contain data that will always outlive the bucket itself. For example no data (EOS and FLUSH), or the data resides in global, constant memory (IMMORTAL), or the data is on the heap (HEAP). For these buckets, apr_bucket_setaside_noop can be used.
apr_status_t(* apr_bucket_type_t::split)(apr_bucket *e, apr_size_t point)

Split one bucket in two at the specified position by duplicating the bucket structure (not the data) and modifying any necessary start/end/offset information. If it's not possible to do this for the bucket type (perhaps the length of the data is indeterminate, as with pipe and socket buckets), then APR_ENOTIMPL is returned.

Parameters
eThe bucket to split
pointThe offset of the first byte in the new bucket

The documentation for this struct was generated from the following file: