Sloop::Client::Request

Sloop Home Examples Guide TOC POD TOC

Sloop::Client::Request

DESCRIPTION

Class representing an HTTP request from a client. Objects of this sort are attached to Sloop::Client objects (as the 'request' field).

ATTRIBUTES

$req->{body}

Scalar containing the raw body of the request, if any. This may or may not be complete; the correct way to get the body is to use Sloop::Client->readPost() or Sloop::Client->simplePost().

If you do not read the entire body, do not bother trying to reply to the request. Just cancel() the client object.

$req->{bad}

If this exists, it is a string message explaining why the request header was rejected.

$req->{headers}

Reference to a hash of the HTTP header. The keys are field names in all lower case and the values are the original strings. If the client used the same header multiple times, the values are amalgamated into a comma seperated list in one string.

$req->{method}

A string containing a lower case version of the http method, eg. "get" or "post".

$req->{path}

The HTTP request path split into an array. Eg. "GET /one/two/three.html" would be ('one', 'two', 'three.html').

$req->{protocol}

The raw text of the protocol, eg. "HTTP/1.1", or "???" if one was not found.

$req->{qargs}

Does not exist by default; created via $req->qstr2qargs() or $req->post2qargs(). A hash structure keyed by name; all elements are array references, even if the field was intended to be singular. This is to deal with the fact that a request may, accidentally or on purpose, specify the field twice. If you intended it to be a singular value, use:

 if (exists $req->{qargs}->{field_name}) {
        my $val = $req->{qargs}->{field_name}->[0];
 }

Presuming you have already called qstr2qargs() or post2qargs and checked the return value (or made sure {qargs} is defined). This will be safe regardless of how malformed the request is. Note that $req->query() will do all that for you.

$req->{qstr}

Reference to the string containing the raw text beyond '?' from the request path (ie, the query string). Does not exist if there was no '?'. This string is destroyed by a $req->qstr2qargs() call.

$req->{slash_end}

True/false value indicating whether the path part of the request-line (not including any query string) ended in a forward slash.

METHODS

$req->findCookieValue($name)

Convenience method for getting the value of the cookie named $name.

Returns: The value or undef if not found (or malformed). If the value is undefined (i.e. $name is a cookie with nothing after the =), an empty string is returned.

$req->header($name)

Retrieves a header value.

$name is the (all lowercase) name of the HTTP header, eg. "user-agent", "content-length".

Returns: A text value for the header, if any.

$req->hostURI()

Returns: A string such as 'http://localhost'. The protocol is taken from $ENV{SLOOP_PROTOCOL} and the host from the 'Host:' header, or, if it does not exist, from the `hostname` command. If that fails, undef is returned.

$req->pathFromLevel()

Retrieves any remainder in $req->{path} beyond the level of the handler called. Eg, if $req->{path} is ('one', 'two', 'three.html') and 'two' triggered a handler, pathFromLevel() will return ('three.html').

Returns: An array; if there is no remainder, the array is empty.

$req->post2qargs($decode)

Parses the contents of $req->{body} into $req->{qargs} (see ATTRIBUTES). Destructive effect on {body}.

$decode is a boolean indicatator of whether or not $req->{body} is URL encoded.

Returns: The $req->{qargs} reference, or undef if there was no body to parse.

$req->qstr2qargs()

Parses the contents of $req->{qstr} into $req->{qargs} (see ATTRIBUTES). Destructive effect on {qstr}.

It's assumed the query string is URL encoded, and it will be decoded as such.

Returns: The $req->{qargs} reference, or undef if there was no qstr to parse. A malformed query string which did not lead to an error when the HTTP header was initially parsed may lead to an empty/partial object but is not explicitly indicated.

$req->query(@keys)

Retrieves the value of a query field, or a number of query fields if more are passed in. More specifically, the value is the first value in the array of values for that field (see 'qargs' under SYNOPSIS, above, for an explanation). If qstr2qargs() or post2qargs() have yet been called, the former is tried first, then if there is no query string and $req->{method} is 'post', the latter.

If you use this method and the query is in a POST body, it will be treated as URL encoded unless you call post2qargs() appropriately yourself first.

@keys is one or more query keys to search for.

Returns: If there was only one key in the argument list, returns that value. If there were more, returns an array of values. Fields which were not found are undef. If a field has multiple values, the first one is returned.

$req->requestPath()

Returns: A reconstruction of the path from the request's request-line (the original was broken down during parsing).

getHeaders($dataref)

This is a static (i.e., not OO) function that wraps part of the internal HTTP parser. It's included in the API since it might be useful with Sloop::Other and Sloop::Multipart::process().

$dataref is a scalar reference containing raw HTTP headers. It must be checked for "\r\n\r\n" termination first or bad things may happen. It should also be free from anything that's not a "key: value" pair, such as the preliminary status line in an HTTP response ("HTTP 1.1 OK", etc.), or this will count as malformed and the return value will be undef.

Returns: A hash containing the headers as key value pairs, with the key in all lowercase, is returned, or undef if $dataref is not a reference or contains malformed headers.

If the call succeeds, $dataref now refers to whatever starts after the terminating "/r/n/r/n".