Writing Apache Modules with Perl and C

10.4. The Array API

The HTTP protocol is filled with lists: lists of language codes, HTTP header fields, MIME types, and so forth. In general, it's not possible to predict the size of the lists in advance, and some of them can be quite large. In order to deal with this, Apache provides an array API that allows you to create lists of arbitrary type and length, much like the dynamic arrays provided by Perl. More complex data structures, such as the table type (described later in this chapter), are built on top of Apache arrays.

10.4.1. The array_header Type

The core of the array API is the array_header structure, whose definition you can find in include/alloc.h:

typedef struct {
    ap_pool *pool;
    int elt_size;
    int nelts;
    int nalloc;
    char *elts;
} array_header;

The fields you'll use are the nelts field, which holds the current number of elements in the array, and the elts field, which contains a pointer to the data in the array. elts is declared as a char* for the convenience of internal routines. You will need to cast it to a pointer of the correct type before you can access elements safely. You should not need to worry about the other fields, but note that the array_header contains a pointer back to the resource pool from which it was allocated. This means that both the array header and its contents will be freed automatically when the pool reaches the end of its lifetime.

10.4.2. Creating and Manipulating Arrays

Here are the API calls for working with arrays. Although array ...