|
Packit |
a09cf7 |
# NAME
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
HTTP::Message - HTTP style message (base class)
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# VERSION
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
version 6.18
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# SYNOPSIS
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
use base 'HTTP::Message';
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# DESCRIPTION
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
An `HTTP::Message` object contains some headers and a content body.
|
|
Packit |
a09cf7 |
The following methods are available:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess = HTTP::Message->new
|
|
Packit |
a09cf7 |
- $mess = HTTP::Message->new( $headers )
|
|
Packit |
a09cf7 |
- $mess = HTTP::Message->new( $headers, $content )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This constructs a new message object. Normally you would want
|
|
Packit |
a09cf7 |
construct `HTTP::Request` or `HTTP::Response` objects instead.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The optional $header argument should be a reference to an
|
|
Packit |
a09cf7 |
`HTTP::Headers` object or a plain array reference of key/value pairs.
|
|
Packit |
a09cf7 |
If an `HTTP::Headers` object is provided then a copy of it will be
|
|
Packit |
a09cf7 |
embedded into the constructed message, i.e. it will not be owned and
|
|
Packit |
a09cf7 |
can be modified afterwards without affecting the message.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The optional $content argument should be a string of bytes.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess = HTTP::Message->parse( $str )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This constructs a new message object by parsing the given string.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->headers
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Returns the embedded `HTTP::Headers` object.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->headers\_as\_string
|
|
Packit |
a09cf7 |
- $mess->headers\_as\_string( $eol )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Call the as\_string() method for the headers in the
|
|
Packit |
a09cf7 |
message. This will be the same as
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$mess->headers->as_string
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
but it will make your program a whole character shorter :-)
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->content
|
|
Packit |
a09cf7 |
- $mess->content( $bytes )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The content() method sets the raw content if an argument is given. If no
|
|
Packit |
a09cf7 |
argument is given the content is not touched. In either case the
|
|
Packit |
a09cf7 |
original raw content is returned.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If the `undef` argument is given, the content is reset to its default value,
|
|
Packit |
a09cf7 |
which is an empty string.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Note that the content should be a string of bytes. Strings in perl
|
|
Packit |
a09cf7 |
can contain characters outside the range of a byte. The `Encode`
|
|
Packit |
a09cf7 |
module can be used to turn such strings into a string of bytes.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->add\_content( $bytes )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The add\_content() methods appends more data bytes to the end of the
|
|
Packit |
a09cf7 |
current content buffer.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->add\_content\_utf8( $string )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The add\_content\_utf8() method appends the UTF-8 bytes representing the
|
|
Packit |
a09cf7 |
string to the end of the current content buffer.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->content\_ref
|
|
Packit |
a09cf7 |
- $mess->content\_ref( \\$bytes )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The content\_ref() method will return a reference to content buffer string.
|
|
Packit |
a09cf7 |
It can be more efficient to access the content this way if the content
|
|
Packit |
a09cf7 |
is huge, and it can even be used for direct manipulation of the content,
|
|
Packit |
a09cf7 |
for instance:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
${$res->content_ref} =~ s/\bfoo\b/bar/g;
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This example would modify the content buffer in-place.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If an argument is passed it will setup the content to reference some
|
|
Packit |
a09cf7 |
external source. The content() and add\_content() methods
|
|
Packit |
a09cf7 |
will automatically dereference scalar references passed this way. For
|
|
Packit |
a09cf7 |
other references content() will return the reference itself and
|
|
Packit |
a09cf7 |
add\_content() will refuse to do anything.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->content\_charset
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This returns the charset used by the content in the message. The
|
|
Packit |
a09cf7 |
charset is either found as the charset attribute of the
|
|
Packit |
a09cf7 |
`Content-Type` header or by guessing.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
See [http://www.w3.org/TR/REC-html40/charset.html#spec-char-encoding](http://www.w3.org/TR/REC-html40/charset.html#spec-char-encoding)
|
|
Packit |
a09cf7 |
for details about how charset is determined.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->decoded\_content( %options )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Returns the content with any `Content-Encoding` undone and for textual content
|
|
Packit |
a09cf7 |
the raw content encoded to Perl's Unicode strings. If the `Content-Encoding`
|
|
Packit |
a09cf7 |
or `charset` of the message is unknown this method will fail by returning
|
|
Packit |
a09cf7 |
`undef`.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The following options can be specified.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `charset`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This override the charset parameter for text content. The value
|
|
Packit |
a09cf7 |
`none` can used to suppress decoding of the charset.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `default_charset`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This override the default charset guessed by content\_charset() or
|
|
Packit |
a09cf7 |
if that fails "ISO-8859-1".
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `alt_charset`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If decoding fails because the charset specified in the Content-Type header
|
|
Packit |
a09cf7 |
isn't recognized by Perl's Encode module, then try decoding using this charset
|
|
Packit |
a09cf7 |
instead of failing. The `alt_charset` might be specified as `none` to simply
|
|
Packit |
a09cf7 |
return the string without any decoding of charset as alternative.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `charset_strict`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Abort decoding if malformed characters is found in the content. By
|
|
Packit |
a09cf7 |
default you get the substitution character ("\\x{FFFD}") in place of
|
|
Packit |
a09cf7 |
malformed characters.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `raise_error`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If TRUE then raise an exception if not able to decode content. Reason
|
|
Packit |
a09cf7 |
might be that the specified `Content-Encoding` or `charset` is not
|
|
Packit |
a09cf7 |
supported. If this option is FALSE, then decoded\_content() will return
|
|
Packit |
a09cf7 |
`undef` on errors, but will still set $@.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- `ref`
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If TRUE then a reference to decoded content is returned. This might
|
|
Packit |
a09cf7 |
be more efficient in cases where the decoded content is identical to
|
|
Packit |
a09cf7 |
the raw content as no data copying is required in this case.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->decodable
|
|
Packit |
a09cf7 |
- HTTP::Message::decodable()
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This returns the encoding identifiers that decoded\_content() can
|
|
Packit |
a09cf7 |
process. In scalar context returns a comma separated string of
|
|
Packit |
a09cf7 |
identifiers.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This value is suitable for initializing the `Accept-Encoding` request
|
|
Packit |
a09cf7 |
header field.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->decode
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This method tries to replace the content of the message with the
|
|
Packit |
a09cf7 |
decoded version and removes the `Content-Encoding` header. Returns
|
|
Packit |
a09cf7 |
TRUE if successful and FALSE if not.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If the message does not have a `Content-Encoding` header this method
|
|
Packit |
a09cf7 |
does nothing and returns TRUE.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Note that the content of the message is still bytes after this method
|
|
Packit |
a09cf7 |
has been called and you still need to call decoded\_content() if you
|
|
Packit |
a09cf7 |
want to process its content as a string.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->encode( $encoding, ... )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Apply the given encodings to the content of the message. Returns TRUE
|
|
Packit |
a09cf7 |
if successful. The "identity" (non-)encoding is always supported; other
|
|
Packit |
a09cf7 |
currently supported encodings, subject to availability of required
|
|
Packit |
a09cf7 |
additional modules, are "gzip", "deflate", "x-bzip2" and "base64".
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
A successful call to this function will set the `Content-Encoding`
|
|
Packit |
a09cf7 |
header.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Note that `multipart/*` or `message/*` messages can't be encoded and
|
|
Packit |
a09cf7 |
this method will croak if you try.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->parts
|
|
Packit |
a09cf7 |
- $mess->parts( @parts )
|
|
Packit |
a09cf7 |
- $mess->parts( \\@parts )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Messages can be composite, i.e. contain other messages. The composite
|
|
Packit |
a09cf7 |
messages have a content type of `multipart/*` or `message/*`. This
|
|
Packit |
a09cf7 |
method give access to the contained messages.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The argumentless form will return a list of `HTTP::Message` objects.
|
|
Packit |
a09cf7 |
If the content type of $msg is not `multipart/*` or `message/*` then
|
|
Packit |
a09cf7 |
this will return the empty list. In scalar context only the first
|
|
Packit |
a09cf7 |
object is returned. The returned message parts should be regarded as
|
|
Packit |
a09cf7 |
read-only (future versions of this library might make it possible
|
|
Packit |
a09cf7 |
to modify the parent by modifying the parts).
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If the content type of $msg is `message/*` then there will only be
|
|
Packit |
a09cf7 |
one part returned.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If the content type is `message/http`, then the return value will be
|
|
Packit |
a09cf7 |
either an `HTTP::Request` or an `HTTP::Response` object.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If a @parts argument is given, then the content of the message will be
|
|
Packit |
a09cf7 |
modified. The array reference form is provided so that an empty list
|
|
Packit |
a09cf7 |
can be provided. The @parts array should contain `HTTP::Message`
|
|
Packit |
a09cf7 |
objects. The @parts objects are owned by $mess after this call and
|
|
Packit |
a09cf7 |
should not be modified or made part of other messages.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
When updating the message with this method and the old content type of
|
|
Packit |
a09cf7 |
$mess is not `multipart/*` or `message/*`, then the content type is
|
|
Packit |
a09cf7 |
set to `multipart/mixed` and all other content headers are cleared.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This method will croak if the content type is `message/*` and more
|
|
Packit |
a09cf7 |
than one part is provided.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->add\_part( $part )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This will add a part to a message. The $part argument should be
|
|
Packit |
a09cf7 |
another `HTTP::Message` object. If the previous content type of
|
|
Packit |
a09cf7 |
$mess is not `multipart/*` then the old content (together with all
|
|
Packit |
a09cf7 |
content headers) will be made part #1 and the content type made
|
|
Packit |
a09cf7 |
`multipart/mixed` before the new part is added. The $part object is
|
|
Packit |
a09cf7 |
owned by $mess after this call and should not be modified or made part
|
|
Packit |
a09cf7 |
of other messages.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
There is no return value.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->clear
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Will clear the headers and set the content to the empty string. There
|
|
Packit |
a09cf7 |
is no return value
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->protocol
|
|
Packit |
a09cf7 |
- $mess->protocol( $proto )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Sets the HTTP protocol used for the message. The protocol() is a string
|
|
Packit |
a09cf7 |
like `HTTP/1.0` or `HTTP/1.1`.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->clone
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Returns a copy of the message object.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->as\_string
|
|
Packit |
a09cf7 |
- $mess->as\_string( $eol )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Returns the message formatted as a single string.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
The optional $eol parameter specifies the line ending sequence to use.
|
|
Packit |
a09cf7 |
The default is "\\n". If no $eol is given then as\_string will ensure
|
|
Packit |
a09cf7 |
that the returned string is newline terminated (even when the message
|
|
Packit |
a09cf7 |
content is not). No extra newline is appended if an explicit $eol is
|
|
Packit |
a09cf7 |
passed.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- $mess->dump( %opt )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Returns the message formatted as a string. In void context print the string.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This differs from `$mess->as_string` in that it escapes the bytes
|
|
Packit |
a09cf7 |
of the content so that it's safe to print them and it limits how much
|
|
Packit |
a09cf7 |
content to print. The escapes syntax used is the same as for Perl's
|
|
Packit |
a09cf7 |
double quoted strings. If there is no content the string "(no
|
|
Packit |
a09cf7 |
content)" is shown in its place.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Options to influence the output can be passed as key/value pairs. The
|
|
Packit |
a09cf7 |
following options are recognized:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- maxlength => $num
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
How much of the content to show. The default is 512. Set this to 0
|
|
Packit |
a09cf7 |
for unlimited.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
If the content is longer then the string is chopped at the limit and
|
|
Packit |
a09cf7 |
the string "...\\n(### more bytes not shown)" appended.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- no\_content => $str
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Replaces the "(no content)" marker.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
- prefix => $str
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
A string that will be prefixed to each line of the dump.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
All methods unknown to `HTTP::Message` itself are delegated to the
|
|
Packit |
a09cf7 |
`HTTP::Headers` object that is part of every message. This allows
|
|
Packit |
a09cf7 |
convenient access to these methods. Refer to [HTTP::Headers](https://metacpan.org/pod/HTTP::Headers) for
|
|
Packit |
a09cf7 |
details of these methods:
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$mess->header( $field => $val )
|
|
Packit |
a09cf7 |
$mess->push_header( $field => $val )
|
|
Packit |
a09cf7 |
$mess->init_header( $field => $val )
|
|
Packit |
a09cf7 |
$mess->remove_header( $field )
|
|
Packit |
a09cf7 |
$mess->remove_content_headers
|
|
Packit |
a09cf7 |
$mess->header_field_names
|
|
Packit |
a09cf7 |
$mess->scan( \&doit )
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
$mess->date
|
|
Packit |
a09cf7 |
$mess->expires
|
|
Packit |
a09cf7 |
$mess->if_modified_since
|
|
Packit |
a09cf7 |
$mess->if_unmodified_since
|
|
Packit |
a09cf7 |
$mess->last_modified
|
|
Packit |
a09cf7 |
$mess->content_type
|
|
Packit |
a09cf7 |
$mess->content_encoding
|
|
Packit |
a09cf7 |
$mess->content_length
|
|
Packit |
a09cf7 |
$mess->content_language
|
|
Packit |
a09cf7 |
$mess->title
|
|
Packit |
a09cf7 |
$mess->user_agent
|
|
Packit |
a09cf7 |
$mess->server
|
|
Packit |
a09cf7 |
$mess->from
|
|
Packit |
a09cf7 |
$mess->referer
|
|
Packit |
a09cf7 |
$mess->www_authenticate
|
|
Packit |
a09cf7 |
$mess->authorization
|
|
Packit |
a09cf7 |
$mess->proxy_authorization
|
|
Packit |
a09cf7 |
$mess->authorization_basic
|
|
Packit |
a09cf7 |
$mess->proxy_authorization_basic
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# AUTHOR
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
Gisle Aas <gisle@activestate.com>
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
# COPYRIGHT AND LICENSE
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This software is copyright (c) 1994-2017 by Gisle Aas.
|
|
Packit |
a09cf7 |
|
|
Packit |
a09cf7 |
This is free software; you can redistribute it and/or modify it under
|
|
Packit |
a09cf7 |
the same terms as the Perl 5 programming language system itself.
|