Filtering I/O in Apache 2.0: Part 2 Page 3

If we are using a configured string as the header, then we need to create a bucket to store the string before we can pass it down to the next filter. In this case, we are going to use an immortal bucket because the memory for the string was allocated earlier, and we don't want to copy it again if we can help it. Once we have created the bucket, we have to actually put it in the brigade. If we don't put it in the brigade then none of the later filters will get to see the data. Since the final filter is the thing that actually sends the data to the client, we need to be sure that the data is sent to the next filter. Actually sending the data is done later in the function, as we will see below. It is also important that this bucket goes at the beginning of this brigade. Putting this bucket at the start of the brigade is accomplished with AP_BRIGADE_INSERT_HEAD.

The final step in this filter is to deal with the footers:

    e = AP_BRIGADE_LAST(bb);
    if (AP_BUCKET_IS_EOS(e)) {
        ap_bucket_brigade *end;
 
        end = ap_brigade_split(bb, e);
        if (!AP_BRIGADE_EMPTY(bb)) {
            ap_pass_brigade(f->next, bb);
        }
        ap_brigade_destroy(bb);
        bb = end;
        if (conf->headerf) {
            request_rec *rr;
 
            rr = ap_sub_req_lookup_uri(conf->footerf, f->r);
            if (rr->status == HTTP_OK) {
                ap_run_sub_req(rr);
            }
        }
        if (conf->footert) {
            ap_bucket *foot;
 
            foot = ap_bucket_create_immortal(conf->footert, strlen(conf->footert));            
            AP_BUCKET_INSERT_BEFORE(e, foot);
        }
    }
    ap_pass_brigade(f->next, bb);
    return APR_SUCCESS;
}                                                                                  



As I mentioned above, determining when to send the footers is done differently 
than the headers.  In this case, we only want to send the footers when we know 
that we are at the end of the response.  Filters know when they are seeing the end
of a response, because they are given an EOS bucket.  An EOS bucket is a special
bucket created by Apache to signify the "end of stream".  Another feature of EOS
buckets is that they are always at the end of a brigade, so to determine if we are
at the end, we get the last bucket in the brigade and check if it is an EOS 
bucket.  If it isn't, then we just pass the data we have just been given to the
next filter with the ap_pass_brigade function.



If this brigade does have the end of the request, then we need to send out the
footers for this page.  To make processing easier, we treat both files and strings
the same.  In this case, that means sending the data we have before we try to
send the footer data.  If we didn't do this, and we tried to send a file using
a sub-request then the file would be delivered before the data we have just been
passed.  To send the data we have, we must split the brigade just before the EOS
bucket.  This is done with ap_brigade_split.  If the new brigade is not empty
then we need to send it to the next filter.  Oce we have either sent the brigade
to the next filer, or done nothing with it, we must destroy the brigade, or we
will leak memory.



At this point sending the footer file is the same as sending the header file, so 
we won't go into any detail about that.  Sending the footer string starts by 
creating the bucket, same as the header string.  This time, instead of
inserting the bucket at the start of the array, we want to insert it just before
the EOS bucket.  We know that e is pointing to the EOS bucket, because we set that
up earlier in the function, so we use AP_BUCKET_INSERT_BEFORE to make sure
that the footer bucket is inserted in the correct place.