1HTTP::Message(3) User Contributed Perl Documentation HTTP::Message(3)
2
6 HTTP::Message - HTTP style message (base class)
7
9 version 6.36
10
12 use base 'HTTP::Message';
13
15 An "HTTP::Message" object contains some headers and a content body.
16 The following methods are available:
17 $mess = HTTP::Message->new
19 $mess = HTTP::Message->new( $headers )
20 $mess = HTTP::Message->new( $headers, $content )
21 This constructs a new message object. Normally you would want
22 construct "HTTP::Request" or "HTTP::Response" objects instead.
23 The optional $header argument should be a reference to an
25 "HTTP::Headers" object or a plain array reference of key/value
26 pairs. If an "HTTP::Headers" object is provided then a copy of it
27 will be embedded into the constructed message, i.e. it will not be
28 owned and can be modified afterwards without affecting the message.
29 The optional $content argument should be a string of bytes.
31 $mess = HTTP::Message->parse( $str )
33 This constructs a new message object by parsing the given string.
34 $mess->headers
36 Returns the embedded "HTTP::Headers" object.
37 $mess->headers_as_string
39 $mess->headers_as_string( $eol )
40 Call the as_string() method for the headers in the message. This
41 will be the same as
42 $mess->headers->as_string
44 but it will make your program a whole character shorter :-)
46 $mess->content
48 $mess->content( $bytes )
49 The content() method sets the raw content if an argument is given.
50 If no argument is given the content is not touched. In either case
51 the original raw content is returned.
52 If the "undef" argument is given, the content is reset to its
54 default value, which is an empty string.
55 Note that the content should be a string of bytes. Strings in perl
57 can contain characters outside the range of a byte. The "Encode"
58 module can be used to turn such strings into a string of bytes.
59 $mess->add_content( $bytes )
61 The add_content() methods appends more data bytes to the end of the
62 current content buffer.
63 $mess->add_content_utf8( $string )
65 The add_content_utf8() method appends the UTF-8 bytes representing
66 the string to the end of the current content buffer.
67 $mess->content_ref
69 $mess->content_ref( \$bytes )
70 The content_ref() method will return a reference to content buffer
71 string. It can be more efficient to access the content this way if
72 the content is huge, and it can even be used for direct
73 manipulation of the content, for instance:
74 ${$res->content_ref} =~ s/\bfoo\b/bar/g;
76 This example would modify the content buffer in-place.
78 If an argument is passed it will setup the content to reference
80 some external source. The content() and add_content() methods will
81 automatically dereference scalar references passed this way. For
82 other references content() will return the reference itself and
83 add_content() will refuse to do anything.
84 $mess->content_charset
86 This returns the charset used by the content in the message. The
87 charset is either found as the charset attribute of the
88 "Content-Type" header or by guessing.
89 See
91 <http://www.w3.org/TR/REC-html40/charset.html#spec-char-encoding>
92 for details about how charset is determined.
93 $mess->decoded_content( %options )
95 Returns the content with any "Content-Encoding" undone and, for
96 textual content ("Content-Type" values starting with "text/",
97 exactly matching "application/xml", or ending with "+xml"), the raw
98 content's character set decoded into Perl's Unicode string format.
99 Note that this does not currently <https://github.com/libwww-
100 perl/HTTP-Message/pull/99> attempt to decode declared character
101 sets for any other content types like "application/json" or
102 "application/javascript". If the "Content-Encoding" or "charset"
103 of the message is unknown, this method will fail by returning
104 "undef".
105 The following options can be specified.
107 "charset"
109 This override the charset parameter for text content. The
110 value "none" can used to suppress decoding of the charset.
111 "default_charset"
113 This override the default charset guessed by content_charset()
114 or if that fails "ISO-8859-1".
115 "alt_charset"
117 If decoding fails because the charset specified in the Content-
118 Type header isn't recognized by Perl's Encode module, then try
119 decoding using this charset instead of failing. The
120 "alt_charset" might be specified as "none" to simply return the
121 string without any decoding of charset as alternative.
122 "charset_strict"
124 Abort decoding if malformed characters is found in the content.
125 By default you get the substitution character ("\x{FFFD}") in
126 place of malformed characters.
127 "raise_error"
129 If TRUE then raise an exception if not able to decode content.
130 Reason might be that the specified "Content-Encoding" or
131 "charset" is not supported. If this option is FALSE, then
132 decoded_content() will return "undef" on errors, but will still
133 set $@.
134 "ref"
136 If TRUE then a reference to decoded content is returned. This
137 might be more efficient in cases where the decoded content is
138 identical to the raw content as no data copying is required in
139 this case.
140 $mess->decodable
142 HTTP::Message::decodable()
143 This returns the encoding identifiers that decoded_content() can
144 process. In scalar context returns a comma separated string of
145 identifiers.
146 This value is suitable for initializing the "Accept-Encoding"
148 request header field.
149 $mess->decode
151 This method tries to replace the content of the message with the
152 decoded version and removes the "Content-Encoding" header. Returns
153 TRUE if successful and FALSE if not.
154 If the message does not have a "Content-Encoding" header this
156 method does nothing and returns TRUE.
157 Note that the content of the message is still bytes after this
159 method has been called and you still need to call decoded_content()
160 if you want to process its content as a string.
161 $mess->encode( $encoding, ... )
163 Apply the given encodings to the content of the message. Returns
164 TRUE if successful. The "identity" (non-)encoding is always
165 supported; other currently supported encodings, subject to
166 availability of required additional modules, are "gzip", "deflate",
167 "x-bzip2" and "base64".
168 A successful call to this function will set the "Content-Encoding"
170 header.
171 Note that "multipart/*" or "message/*" messages can't be encoded
173 and this method will croak if you try.
174 $mess->parts
176 $mess->parts( @parts )
177 $mess->parts( \@parts )
178 Messages can be composite, i.e. contain other messages. The
179 composite messages have a content type of "multipart/*" or
180 "message/*". This method give access to the contained messages.
181 The argumentless form will return a list of "HTTP::Message"
183 objects. If the content type of $msg is not "multipart/*" or
184 "message/*" then this will return the empty list. In scalar
185 context only the first object is returned. The returned message
186 parts should be regarded as read-only (future versions of this
187 library might make it possible to modify the parent by modifying
188 the parts).
189 If the content type of $msg is "message/*" then there will only be
191 one part returned.
192 If the content type is "message/http", then the return value will
194 be either an "HTTP::Request" or an "HTTP::Response" object.
195 If a @parts argument is given, then the content of the message will
197 be modified. The array reference form is provided so that an empty
198 list can be provided. The @parts array should contain
199 "HTTP::Message" objects. The @parts objects are owned by $mess
200 after this call and should not be modified or made part of other
201 messages.
202 When updating the message with this method and the old content type
204 of $mess is not "multipart/*" or "message/*", then the content type
205 is set to "multipart/mixed" and all other content headers are
206 cleared.
207 This method will croak if the content type is "message/*" and more
209 than one part is provided.
210 $mess->add_part( $part )
212 This will add a part to a message. The $part argument should be
213 another "HTTP::Message" object. If the previous content type of
214 $mess is not "multipart/*" then the old content (together with all
215 content headers) will be made part #1 and the content type made
216 "multipart/mixed" before the new part is added. The $part object
217 is owned by $mess after this call and should not be modified or
218 made part of other messages.
219 There is no return value.
221 $mess->clear
223 Will clear the headers and set the content to the empty string.
224 There is no return value
225 $mess->protocol
227 $mess->protocol( $proto )
228 Sets the HTTP protocol used for the message. The protocol() is a
229 string like "HTTP/1.0" or "HTTP/1.1".
230 $mess->clone
232 Returns a copy of the message object.
233 $mess->as_string
235 $mess->as_string( $eol )
236 Returns the message formatted as a single string.
237 The optional $eol parameter specifies the line ending sequence to
239 use. The default is "\n". If no $eol is given then as_string will
240 ensure that the returned string is newline terminated (even when
241 the message content is not). No extra newline is appended if an
242 explicit $eol is passed.
243 $mess->dump( %opt )
245 Returns the message formatted as a string. In void context print
246 the string.
247 This differs from "$mess->as_string" in that it escapes the bytes
249 of the content so that it's safe to print them and it limits how
250 much content to print. The escapes syntax used is the same as for
251 Perl's double quoted strings. If there is no content the string
252 "(no content)" is shown in its place.
253 Options to influence the output can be passed as key/value pairs.
255 The following options are recognized:
256 maxlength => $num
258 How much of the content to show. The default is 512. Set this
259 to 0 for unlimited.
260 If the content is longer then the string is chopped at the
262 limit and the string "...\n(### more bytes not shown)"
263 appended.
264 no_content => $str
266 Replaces the "(no content)" marker.
267 prefix => $str
269 A string that will be prefixed to each line of the dump.
270 All methods unknown to "HTTP::Message" itself are delegated to the
272 "HTTP::Headers" object that is part of every message. This allows
273 convenient access to these methods. Refer to HTTP::Headers for details
274 of these methods:
275 $mess->header( $field => $val )
277 $mess->push_header( $field => $val )
278 $mess->init_header( $field => $val )
279 $mess->remove_header( $field )
280 $mess->remove_content_headers
281 $mess->header_field_names
282 $mess->scan( \&doit )
283 $mess->date
285 $mess->expires
286 $mess->if_modified_since
287 $mess->if_unmodified_since
288 $mess->last_modified
289 $mess->content_type
290 $mess->content_encoding
291 $mess->content_length
292 $mess->content_language
293 $mess->title
294 $mess->user_agent
295 $mess->server
296 $mess->from
297 $mess->referer
298 $mess->www_authenticate
299 $mess->authorization
300 $mess->proxy_authorization
301 $mess->authorization_basic
302 $mess->proxy_authorization_basic
303
305 Gisle Aas <gisle@activestate.com>
306
308 This software is copyright (c) 1994 by Gisle Aas.
309 This is free software; you can redistribute it and/or modify it under
311 the same terms as the Perl 5 programming language system itself.
312perl v5.34.0 2022-01-21 HTTP::Message(3)