On Wed, Aug 11, 2004 at 03:51:13PM -0700, Justin Erenkrantz wrote:
> --On Wednesday, August 11, 2004 5:16 PM -0400 Glenn Strauss
> <[EMAIL PROTECTED]> wrote:
>
> >I'm finding ap_input_mode_t very restrictive as a linear enum
> >and would like to make it an enum of bitflags.
>
> Please back up a bit.
>
> Why do you think the modes should be combined? -- justin
Short answer:
-------------
I am refactoring most of the input filtering for more consistent
behavior and much greater code reuse. However, two incompatible
changes are needed, and with Apache 2.2 in sight, I wanted to
introduce those changes now.
Those changes are: ap_input_mode_t becomes bitflags, and input
filters must check for bitflags instead of exact values
(mode & AP_MODE_GETLINE) instead of (mode == AP_MODE_GETLINE)
Also, AP_MODE_GETLINE should not return partial lines.
More details:
-------------
Why bitflags, you ask?
I had hoped to introduce this a bit more slowly,
but here is a brief peek without too much explanation:
I'd like any of the following to be legal values:
AP_MODE_BYTES
AP_MODE_BYTES | AP_MODE_PASS_SPECIALS
AP_MODE_BYTES | AP_MODE_PEEK
AP_MODE_LINE
AP_MODE_LINE | AP_MODE_PEEK
AP_MODE_LINE | AP_MODE_MIME_FOLDING
AP_MODE_LINE | AP_MODE_MIME_FOLDING | AP_MODE_PEEK
typedef enum {
/** The filter should return at most one line of CRLF data.
* (If a potential line is too long or no CRLF is found,
* the line is not returned, an error is.)
*/
AP_MODE_LINE = 1,
/** The filter should return at most readbytes data. */
AP_MODE_BYTES = 2,
/** The filter should pass any special buckets (not in-memory) as long as it
* does not need to perform any processing on them (translation or protocol
* delimiting) (augments AP_MODE_BYTES; mutually exclusive w/ AP_MODE_PEEK)
*/
AP_MODE_PASS_SPECIALS = 4,
/** The filter read should be treated as speculative and any returned
* data should be stored for later retrieval in another mode.
* (augments AP_MODE_BYTES or AP_MODE_LINE)
*/
AP_MODE_PEEK = 8,
/** When reading lines, look for MIME-folded continuations as well
* (augments AP_MODE_LINE)
*/
AP_MODE_MIME_FOLDING = 16
} ap_input_mode_t;
I think that input filtering is difficult to use and leads to a lot
of code duplication between modules. For example, the behavior of
line-mode is vauge and requires that callers re-parse the brigade
to check for complete lines. I've got a whole litany of things,
including bad code examples of brigade parsing in the Apache core,
but that's another post.
One advantage of the new API:
MIME continuation lines are used so often (HTTP headers/trailers,
email message headers, MIME encapsulation, ...) that they should be
part of the core API. Instead of code duplication (witness
ap_rgetline_core() and ap_get_mime_headers_core() both implementing
continuation line unfolding), AP_MODE_LINE | AP_MODE_MIME_FOLDING
does not return a partial line. It only returns a complete line
including continuations. Simplifying things a bit for now, this
allows caller to know that if its brigade is returned non-empty,
that the line is complete, including continuations, without caller
having to re-parse the line to double-check.
(More posts to follow, but I do not wish to flood the list if no
one wants to engage the conversation.)
Cheers,
Glenn
