Passenger::ScgiRequestParser Class Reference

A parser for SCGI requests. More...

#include <ScgiRequestParser.h>

List of all members.

Public Types
enum	ErrorReason { ,   LENGTH_STRING_TOO_LARGE, LIMIT_REACHED, INVALID_LENGTH_STRING, HEADER_TERMINATOR_EXPECTED,   INVALID_HEADER_DATA }
Public Member Functions
	ScgiRequestParser (unsigned long maxSize=0)
	Create a new ScgiRequestParser, ready to parse a request.
unsigned int	feed (const char *data, unsigned int size)
	Feed SCGI request data to the parser.
string	getHeaderData () const
	Get the raw header data that has been processed so far.
StaticString	getHeader (const StaticString &name) const
	Get the value of the header with the given name.
bool	hasHeader (const StaticString &name) const
	Checks whether there is a header with the given name.
State	getState () const
	Get the parser's current state.
ErrorReason	getErrorReason () const
	Returns the reason why the parser entered the error state.
bool	acceptingInput () const
	Checks whether this parser is still capable of accepting input (that is, that this parser is not in a final state).

---

Detailed Description

A parser for SCGI requests.

It parses the request header and ignores the body data.

You can use it by constructing a parser object, then feeding data to the parser until it has reached a final state.

Example:

    ScgiRequestParser parser;
    char buf[1024 * 16];
    ssize_t size;
    unsigned in bytesAccepted;
    
    do {
        size = read(fd, buf, sizeof(buf));
        bytesAccepted = parser.feed(buf, size);
    } while (parser.acceptingInput());
    // Parser is done when its return value isn't equal to the input size.
    
    // Check whether a parse error occured.
    if (parser.getState() == ScgiRequestParser::ERROR) {
        bailOut();
    } else {
        // All good! Do something with the SCGI header that the parser parsed.
        processHeader(parser.getHeaderData());
        
        // If the last buffer passed to the parser also contains body data,
        // then the body data starts at 'buf + bytesAccepted'.
        if (bytesAccepted < size) {
            processBody(buf + bytesAccepted);
        }
        while (!end_of_file(fd)) {
            ... read(...) ...
            processBody(...);
        }
    }

Parser properties:

• A parser object can only process a single SCGI request. You must discard the existing parser object and create a new one if you want to process another SCGI request.
• This parser checks whether the header netstring is valid. It will enter the error state if it encounters a parse error.
• However, this parser does not perform any validation of the actual header contents. For example, it doesn't check that CONTENT_LENGTH is the first header, or that the SCGI header is present.

---

Member Enumeration Documentation

enum Passenger::ScgiRequestParser::ErrorReason

Enumerator:

LENGTH_STRING_TOO_LARGE	The length string is too large.
LIMIT_REACHED	The header is larger than the maxSize value provided to the constructor.
INVALID_LENGTH_STRING	The length string contains an invalid character.
HEADER_TERMINATOR_EXPECTED	A header terminator character (",") was expected, but some else was encountered instead.
INVALID_HEADER_DATA	The header data itself contains errors.

---

Constructor & Destructor Documentation

Passenger::ScgiRequestParser::ScgiRequestParser

(

unsigned long

maxSize = 0

)

[inline]

Create a new ScgiRequestParser, ready to parse a request.

Parameters:

maxSize

The maximum size that the SCGI data is allowed to be, or 0 if no limit is desired.

---

Member Function Documentation

unsigned int Passenger::ScgiRequestParser::feed	(	const char *	data,
		unsigned int	size
	)			[inline]

Feed SCGI request data to the parser.

Parameters:

	data	The data to feed.
	size	The size of the data, in bytes.

Returns:

The number of recognized SCGI header bytes. If this value equals 'size', then it means all data in 'data' is part of the SCGI header. If this value is less than size, then it means only some data in 'data' is part of the SCGI header, and the remaining 'size - result' bytes are part of the request body.

Precondition:

size > 0

Postcondition:

result <= size

if result <= size: getState() == DONE || getState() == ERROR

ErrorReason Passenger::ScgiRequestParser::getErrorReason

(

)

const [inline]

Returns the reason why the parser entered the error state.

Precondition:

getState() == ERROR

StaticString Passenger::ScgiRequestParser::getHeader

(

const StaticString &

name

)

const [inline]

Get the value of the header with the given name.

Lookup is case-sensitive.

Returns the empty string if there is no such header.

Precondition:

getState() == DONE

bool Passenger::ScgiRequestParser::hasHeader

(

const StaticString &

name

)

const [inline]

Checks whether there is a header with the given name.

Lookup is case-sensitive.

Precondition:

getState() == DONE

---

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

• ScgiRequestParser.h