D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
opt
/
lampp
/
share
/
man
/
man3
/
Filename :
Apache2::Response.3
back
Copy
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "docs::api::Apache2::Response 3" .TH docs::api::Apache2::Response 3 "2013-04-16" "perl v5.16.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Apache2::Response \- Perl API for Apache HTTP request response methods .SH "Synopsis" .IX Header "Synopsis" .Vb 1 \& use Apache2::Response (); \& \& $r\->custom_response(Apache2::Const::FORBIDDEN, "No Entry today"); \& \& $etag = $r\->make_etag($force_weak); \& $r\->set_etag(); \& $status = $r\->meets_conditions(); \& \& $mtime_rat = $r\->rationalize_mtime($mtime); \& $r\->set_last_modified($mtime); \& $r\->update_mtime($mtime); \& \& $r\->send_cgi_header($buffer); \& \& $r\->set_content_length($length); \& \& $ret = $r\->set_keepalive(); .Ve .SH "Description" .IX Header "Description" \&\f(CW\*(C`Apache2::Response\*(C'\fR provides the Apache request object utilities \s-1API\s0 for dealing with \s-1HTTP\s0 response generation process. .SH "API" .IX Header "API" \&\f(CW\*(C`Apache2::Response\*(C'\fR provides the following functions and/or methods: .ie n .SS """custom_response""" .el .SS "\f(CWcustom_response\fP" .IX Subsection "custom_response" Install a custom response handler for a given status .PP .Vb 1 \& $r\->custom_response($status, $string); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $status ( ""Apache2::Const constant"" )" 4 .el .IP "arg1: \f(CW$status\fR ( \f(CWApache2::Const constant\fR )" 4 .IX Item "arg1: $status ( Apache2::Const constant )" The status for which the custom response should be used (e.g. \f(CW\*(C`Apache2::Const::AUTH_REQUIRED\*(C'\fR) .ie n .IP "arg2: $string (string)" 4 .el .IP "arg2: \f(CW$string\fR (string)" 4 .IX Item "arg2: $string (string)" The custom response to use. This can be a static string, or a \s-1URL\s0, full or just the uri path (\fI/foo/bar.txt\fR). .IP "ret: no return value" 4 .IX Item "ret: no return value" .PD 0 .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .PP \&\f(CW\*(C`custom_response()\*(C'\fR doesn't alter the response code, but is used to replace the standard response body. For example, here is how to change the response body for the access handler failure: .PP .Vb 5 \& package MyApache2::MyShop; \& use Apache2::Response (); \& use Apache2::Const \-compile => qw(FORBIDDEN OK); \& sub access { \& my $r = shift; \& \& if (MyApache2::MyShop::tired_squirrels()) { \& $r\->custom_response(Apache2::Const::FORBIDDEN, \& "It\*(Aqs siesta time, please try later"); \& return Apache2::Const::FORBIDDEN; \& } \& \& return Apache2::Const::OK; \& } \& ... \& \& # httpd.conf \& PerlModule MyApache2::MyShop \& <Location /TestAPI_\|_custom_response> \& AuthName dummy \& AuthType none \& PerlAccessHandler MyApache2::MyShop::access \& PerlResponseHandler MyApache2::MyShop::response \& </Location> .Ve .PP When squirrels can't run any more, the handler will return 403, with the custom message: .PP .Vb 1 \& It\*(Aqs siesta time, please try later .Ve .ie n .SS """make_etag""" .el .SS "\f(CWmake_etag\fP" .IX Subsection "make_etag" Construct an entity tag from the resource information. If it's a real file, build in some of the file characteristics. .PP .Vb 1 \& $etag = $r\->make_etag($force_weak); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $force_weak (number)" 4 .el .IP "arg1: \f(CW$force_weak\fR (number)" 4 .IX Item "arg1: $force_weak (number)" Force the entity tag to be weak \- it could be modified again in as short an interval. .ie n .IP "ret: $etag (string)" 4 .el .IP "ret: \f(CW$etag\fR (string)" 4 .IX Item "ret: $etag (string)" The entity tag .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .ie n .SS """meets_conditions""" .el .SS "\f(CWmeets_conditions\fP" .IX Subsection "meets_conditions" Implements condition \f(CW\*(C`GET\*(C'\fR rules for \s-1HTTP/1\s0.1 specification. This function inspects the client headers and determines if the response fulfills the specified requirements. .PP .Vb 1 \& $status = $r\->meets_conditions(); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "ret: $status ( ""Apache2::Const status constant"" )" 4 .el .IP "ret: \f(CW$status\fR ( \f(CWApache2::Const status constant\fR )" 4 .IX Item "ret: $status ( Apache2::Const status constant )" \&\f(CW\*(C`Apache2::Const::OK\*(C'\fR if the response fulfills the condition \s-1GET\s0 rules. Otherwise some other status code (which should be returned to Apache). .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PP Refer to the Generating Correct \s-1HTTP\s0 Headers document for an indepth discussion of this method. .ie n .SS """rationalize_mtime""" .el .SS "\f(CWrationalize_mtime\fP" .IX Subsection "rationalize_mtime" Return the latest rational time from a request/mtime pair. .PP .Vb 1 \& $mtime_rat = $r\->rationalize_mtime($mtime); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $mtime ( time in seconds )" 4 .el .IP "arg1: \f(CW$mtime\fR ( time in seconds )" 4 .IX Item "arg1: $mtime ( time in seconds )" The last modified time .ie n .IP "ret: $mtime_rat ( time in seconds )" 4 .el .IP "ret: \f(CW$mtime_rat\fR ( time in seconds )" 4 .IX Item "ret: $mtime_rat ( time in seconds )" the latest rational time from a request/mtime pair. Mtime is returned unless it's in the future, in which case we return the current time. .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .ie n .SS """send_cgi_header""" .el .SS "\f(CWsend_cgi_header\fP" .IX Subsection "send_cgi_header" Parse the header .PP .Vb 1 \& $r\->send_cgi_header($buffer); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" .PD 0 .ie n .IP "arg1: $buffer (string)" 4 .el .IP "arg1: \f(CW$buffer\fR (string)" 4 .IX Item "arg1: $buffer (string)" .PD headers and optionally a response body .IP "ret: no return value" 4 .IX Item "ret: no return value" .PD 0 .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .PP This method is really for back-compatibility with mod_perl 1.0. It's very inefficient to send headers this way, because of the parsing overhead. .PP If there is a response body following the headers it'll be handled too (as if it was sent via \&\f(CW\*(C`print()\*(C'\fR). .PP Notice that if only \s-1HTTP\s0 headers are included they won't be sent until some body is sent (again the \*(L"send\*(R" part is retained from the mod_perl 1.0 method). .ie n .SS """set_content_length""" .el .SS "\f(CWset_content_length\fP" .IX Subsection "set_content_length" Set the content length for this request. .PP .Vb 1 \& $r\->set_content_length($length); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $length (integer)" 4 .el .IP "arg1: \f(CW$length\fR (integer)" 4 .IX Item "arg1: $length (integer)" The new content length .IP "ret: no return value" 4 .IX Item "ret: no return value" .PD 0 .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .ie n .SS """set_etag""" .el .SS "\f(CWset_etag\fP" .IX Subsection "set_etag" Set the E\-tag outgoing header .PP .Vb 1 \& $r\->set_etag(); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" .PD 0 .IP "ret: no return value" 4 .IX Item "ret: no return value" .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .ie n .SS """set_keepalive""" .el .SS "\f(CWset_keepalive\fP" .IX Subsection "set_keepalive" Set the keepalive status for this request .PP .Vb 1 \& $ret = $r\->set_keepalive(); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "ret: $ret ( boolean )" 4 .el .IP "ret: \f(CW$ret\fR ( boolean )" 4 .IX Item "ret: $ret ( boolean )" true if keepalive can be set, false otherwise .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PP It's called by \f(CW\*(C`ap_http_header_filter()\*(C'\fR. For the complete complicated logic implemented by this method see \&\fIhttpd\-2.0/server/http_protocol.c\fR. .ie n .SS """set_last_modified""" .el .SS "\f(CWset_last_modified\fP" .IX Subsection "set_last_modified" sets the \f(CW\*(C`Last\-Modified\*(C'\fR response header field to the value of the mtime field in the request structure \*(-- rationalized to keep it from being in the future. .PP .Vb 1 \& $r\->set_last_modified($mtime); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" .PD 0 .ie n .IP "opt arg1: $mtime ( time in seconds )" 4 .el .IP "opt arg1: \f(CW$mtime\fR ( time in seconds )" 4 .IX Item "opt arg1: $mtime ( time in seconds )" .PD if the \f(CW$mtime\fR argument is passed, \&\f(CW$r\fR\->update_mtime will be first run with that argument. .IP "ret: no return value" 4 .IX Item "ret: no return value" .PD 0 .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .ie n .SS """update_mtime""" .el .SS "\f(CWupdate_mtime\fP" .IX Subsection "update_mtime" Set the \&\f(CW\*(C`$r\->mtime\*(C'\fR field to the specified value if it's later than what's already there. .PP .Vb 1 \& $r\->update_mtime($mtime); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $mtime ( time in seconds )" 4 .el .IP "arg1: \f(CW$mtime\fR ( time in seconds )" 4 .IX Item "arg1: $mtime ( time in seconds )" .PD 0 .IP "ret: no return value" 4 .IX Item "ret: no return value" .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .PP See also: \f(CW$r\fR\->set_last_modified. .SH "Unsupported API" .IX Header "Unsupported API" \&\f(CW\*(C`Apache2::Response\*(C'\fR also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their \s-1API\s0 is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported \s-1API\s0. .ie n .SS """send_error_response""" .el .SS "\f(CWsend_error_response\fP" .IX Subsection "send_error_response" Send an \*(L"error\*(R" response back to client. It is used for any response that can be generated by the server from the request record. This includes all 204 (no content), 3xx (redirect), 4xx (client error), and 5xx (server error) messages that have not been redirected to another handler via the ErrorDocument feature. .PP .Vb 1 \& $r\->send_error_response($recursive_error); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $recursive_error ( boolean )" 4 .el .IP "arg1: \f(CW$recursive_error\fR ( boolean )" 4 .IX Item "arg1: $recursive_error ( boolean )" the error status in case we get an error in the process of trying to deal with an \f(CW\*(C`ErrorDocument\*(C'\fR to handle some other error. In that case, we print the default report for the first thing that went wrong, and more briefly report on the problem with the \f(CW\*(C`ErrorDocument\*(C'\fR. .IP "ret: no return value" 4 .IX Item "ret: no return value" .PD 0 .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PD .PP \&\s-1META:\s0 it's really an internal Apache method, I'm not quite sure how can it be used externally. .ie n .SS """send_mmap""" .el .SS "\f(CWsend_mmap\fP" .IX Subsection "send_mmap" \&\s-1META:\s0 Autogenerated \- needs to be reviewed/completed .PP Send an \s-1MMAP\s0'ed file to the client .PP .Vb 1 \& $ret = $r\->send_mmap($mm, $offset, $length); .Ve .ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4 .el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4 .IX Item "obj: $r ( Apache2::RequestRec object )" The current request .ie n .IP "arg1: $mm (""APR::Mmap"")" 4 .el .IP "arg1: \f(CW$mm\fR (\f(CWAPR::Mmap\fR)" 4 .IX Item "arg1: $mm (APR::Mmap)" The \s-1MMAP\s0'ed file to send .ie n .IP "arg2: $offset (number)" 4 .el .IP "arg2: \f(CW$offset\fR (number)" 4 .IX Item "arg2: $offset (number)" The offset into the \s-1MMAP\s0 to start sending .ie n .IP "arg3: $length (integer)" 4 .el .IP "arg3: \f(CW$length\fR (integer)" 4 .IX Item "arg3: $length (integer)" The amount of data to send .ie n .IP "ret: $ret (integer)" 4 .el .IP "ret: \f(CW$ret\fR (integer)" 4 .IX Item "ret: $ret (integer)" The number of bytes sent .IP "since: 2.0.00" 4 .IX Item "since: 2.0.00" .PP \&\s-1META:\s0 requires a working APR::Mmap, which is not supported at the moment. .SH "See Also" .IX Header "See Also" mod_perl 2.0 documentation. .SH "Copyright" .IX Header "Copyright" mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0. .SH "Authors" .IX Header "Authors" The mod_perl development team and numerous contributors.