Passenger: Passenger::ScgiRequestParser Class Reference

# 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