Should we add an explicit explanation to AP_MODE_READBYTES: return at most readbytes data. Can't return 0 with APR_BLOCK_READ. Can't return more than readbytes data.
I'd say the first and last one are equivalent statements. And, that APR_BLOCK_READ description belongs with the definition of APR_BLOCK_READ not AP_MODE_READBYTES.
Also while we are at it I have a few more questions:
/** The filter should return at most one line of CRLF data. * (If a potential line is too long or no CRLF is found, the * filter may return partial data). */ AP_MODE_GETLINE,
does it mean that the filter should ignore the readbytes argument in this mode?
I think so, yes.
/** The filter should implicitly eat any CRLF pairs that it sees. */ AP_MODE_EATCRLF,
does it mean that it should do the same as AP_MODE_GETLINE but kill CRLF? If not how much data is it supposed to read? Or is it a mode that never goes on its own and should be OR'ed with some definitive mode, e.g.: AP_MODE_GETLINE|AP_MODE_EATCRLF and AP_MODE_READBYTES|AP_MODE_EATCRLF?
It's meant to be called right before we read the next pipelined request on the connection. Old (really old) Netscape clients added spurious CRLFs between requests. I don't see a clear rationale why it'd have to be 'combined' with other ap_get_brigade() modes. The only one that'd make sense (to me) is AP_MODE_GETLINE. Note that AP_MODE_EATCRLF doesn't necessarily return anything. It's wildly HTTP specific...
Though it'd be nice to add a note re: APR_BLOCK_READ in the AP_MODE_READBYTES doc above. Or I guess may be it belongs to some filters tutorial...
I'll note that I wrote an article on describing httpd-2.x's filters for some Linux magazine recently. I bet you can find back issues. As an aside, I never actually saw the final copy or the printed copy. So, don't blame me if it doesn't help. ;-) -- justin
