Apache2::RequestRec(3pm)

1docs::api::Apache2::ReqUuseesrtRCeocn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::RequestRec(3)
2
3
4

NAME

6       Apache2::RequestRec - Perl API for Apache request record accessors
7

Synopsis

9         use Apache2::RequestRec ();
10
11         # set supported by the handler HTTP methods
12         $allowed = $r->allowed();
13
14         # auth type
15         $auth_type = $r->ap_auth_type();
16
17         # QUERY_STRING
18         $args = $r->args();
19
20         # non-parsed-headers handler
21         $status = $r->assbackwards();
22
23         # how many bytes were sent
24         $bytes_sent = $r->bytes_sent();
25
26         # client connection record
27         $c = $r->connection();
28
29         # "Content-Encoding" HTTP response header
30         $r->content_encoding("gzip");
31
32         # the languages of the content
33         $languages = $r->content_languages();
34
35         # "Content-Encoding" HTTP response header
36         $r->content_type('text/plain');
37
38         # special response headers table
39         $err_headers_out = $r->err_headers_out();
40
41         # request mapped filename
42         $filename = $r->filename();
43
44         # request finfo
45         $finfo = $r->finfo();
46
47         # 'SetHandler perl-script' equivalent
48         $r->handler('perl-script');
49
50         # was it a HEAD request?
51         $status = $r->header_only();
52
53         # request input headers table
54         $headers_in = $r->headers_in();
55
56         # request output headers table
57         $headers_out = $r->headers_out();
58
59         # hostname
60         $hostname = $r->hostname();
61
62         # input filters stack
63         $input_filters = $r->input_filters();
64
65         # get the main request obj in a sub-request
66         $main_r = $r->main();
67
68         # what's the current request (GET/POST/etc)?
69         $method = $r->method();
70
71         # what's the current method number?
72         $methnum = $r->method_number();
73
74         # current resource last modified time
75         $mtime = $r->mtime();
76
77         # next request object (in redirect)
78         $next_r = $r->next();
79
80         # there is no local copy
81         $r->no_local_copy();
82
83         # Apache ascii notes table
84         $notes = $r->notes();
85
86         # output filters stack
87         $output_filters = $r->output_filters();
88
89         # PATH_INFO
90         $path_info = $r->path_info();
91
92         # used in configuration directives modules
93         $per_dir_config = $r->per_dir_config();
94
95         # pool with life span of the current request
96         $p = $r->pool();
97
98         # previous request object in the internal redirect
99         $prev_r = $r->prev();
100
101         # connection level input filters stack
102         $proto_input_filters = $r->proto_input_filters();
103
104         # HTTP protocol version number
105         $proto_num = $r->proto_num();
106
107         # connection level output filters stack
108         $proto_output_filters = $r->proto_output_filters();
109
110         # the protocol, the client speaks: "HTTP/1.0", "HTTP/1.1", etc.
111         $protocol = $r->protocol();
112
113         # is it a proxy request
114         $status = $r->proxyreq($val);
115
116         # Time when the request started
117         $request_time = $r->request_time();
118
119         # server object
120         $s = $r->server();
121
122         # response status
123         $status = $r->status();
124
125         # response status line
126         $status_line = $r->status_line();
127
128         # manipulate %ENV of the subprocess
129         $r->subprocess_env;
130         $r->subprocess_env($key => $val);
131
132         # first HTTP request header
133         $request = $r->the_request();
134
135         # the URI without any parsing performed
136         $unparsed_uri = $r->unparsed_uri();
137
138         # The path portion of the URI
139         $uri = $r->uri();
140
141         # auth username
142         $user = $r->user();
143

Description

145       "Apache2::RequestRec" provides the Perl API for Apache request_rec
146       object.
147
148       The following packages extend the "Apache2::RequestRec" functionality:
149       "Apache2::Access", "Apache2::Log", "Apache2::RequestIO",
150       "Apache2::RequestUtil", "Apache2::Response", "Apache2::SubRequest" and
151       "Apache2::URI".
152

API

154       "Apache2::RequestRec" provides the following functions and/or methods:
155
156       "allowed"
157
158       Get/set the allowed methods bitmask.
159
160         $allowed      = $r->allowed();
161         $prev_allowed = $r->allowed($new_allowed);
162
163       obj: $r ( "Apache2::RequestRec object" )
164       opt arg1: $new_allowed ( bitmask )
165           Set the bitvector.
166
167       ret: $allowed ( bitmask )
168           returns $allowed, which is a bitvector of the allowed methods.
169
170           If the $new_allowed argument is passed, the value before the change
171           is returned.
172
173       since: 2.0.00
174
175       A handler must ensure that the request method is one that it is capable
176       of handling.  Generally modules should "Apache2::DECLINE" any request
177       methods they do not handle.  Prior to aborting the handler like this
178       the handler should set "$r->allowed" to the list of methods that it is
179       willing to handle.  This bitvector is used to construct the "Allow:"
180       header required for "OPTIONS" requests, and
181       "Apache2::Const::HTTP_METHOD_NOT_ALLOWED" (405) and
182       "Apache2::Const::HTTP_NOT_IMPLEMENTED" (501) status codes.
183
184       Since the default Apache handler deals with the "OPTIONS" method, all
185       response handlers can usually decline to deal with "OPTIONS". For exam‐
186       ple if the response handler handles only "GET" and "POST" methods, and
187       not "OPTIONS", it may want to say:
188
189          use Apache2::Const -compile => qw(OK DECLINED M_GET M_POST M_OPTIONS);
190          if ($r->method_number == Apache2::Const::M_OPTIONS) {
191              $r->allowed($r->allowed ⎪ (1<<Apache2::Const::M_GET) ⎪ (1<<Apache2::Const::M_POST));
192              return Apache2::Const::DECLINED;
193          }
194
195       "TRACE" is always allowed, modules don't need to set it explicitly.
196
197       Since the default_handler will always handle a "GET", a module which
198       does *not* implement "GET" should probably return
199       "Apache2::Const::HTTP_METHOD_NOT_ALLOWED".  Unfortunately this means
200       that a script "GET" handler can't be installed by mod_actions.
201
202       For example, if the module can handle only POST method it could start
203       with:
204
205          use Apache2::Const -compile => qw(M_POST HTTP_METHOD_NOT_ALLOWED);
206          unless ($r->method_number == Apache2::Const::M_POST) {
207              $r->allowed($r->allowed ⎪ (1<<Apache2::Const::M_POST));
208              return Apache2::Const::HTTP_METHOD_NOT_ALLOWED;
209          }
210
211       "ap_auth_type"
212
213       If an authentication check was made, get or set the ap_auth_type slot
214       in the request record
215
216         $auth_type = $r->ap_auth_type();
217         $r->ap_auth_type($newval);
218
219       obj: $r ( "Apache2::RequestRec object" )
220       opt arg1: $newval (string)
221           If this argument is passed then a new auth type is assigned. For
222           example:
223
224             $r->auth_type('Basic');
225
226       ret: $auth_type (string)
227           If $newval is passed, nothing is returned. Otherwise the current
228           auth type is returned.
229
230       since: 2.0.00
231
232       ap_auth_type holds the authentication type that has been negotiated
233       between the client and server during the actual request.  Generally,
234       ap_auth_type is populated automatically when you call
235       "$r->get_basic_auth_pw" so you don't really need to worry too much
236       about it, but if you want to roll your own authentication mechanism
237       then you will have to populate ap_auth_type yourself.
238
239       Note that "$r->ap_auth_type" was "$r->connection->auth_type" in the
240       mod_perl 1.0 API.
241
242       "args"
243
244       Get/set the request QUERY string
245
246         $args      = $r->args();
247         $prev_args = $r->args($new_args);
248
249       obj: $r ( "Apache2::RequestRec object" )
250       opt arg1: $new_args ( string )
251           Optinally set the new QUERY string
252
253       ret: $args ( string )
254           The current QUERY string
255
256           If $new_args was passed, returns the value before the change.
257
258       since: 2.0.00
259
260       "assbackwards"
261
262       When set to a true value, Apache won't send any HTTP response headers
263       allowing you to send any headers.
264
265         $status      = $r->assbackwards();
266         $prev_status = $r->assbackwards($newval);
267
268       obj: $r ( "Apache2::RequestRec object" )
269       opt arg1: $newval (integer)
270           assign a new state.
271
272       ret: $status (integer)
273           current state.
274
275       since: 2.0.00
276
277       If you send your own set of headers, which includes the "Keep-Alive"
278       HTTP response header, you must make sure to increment the number of
279       requests served over this connection (which is normally done by the
280       core connection output filter "ap_http_header_filter", but skipped when
281       "assbackwards" is enabled).
282
283         $r->connection->keepalives($r->connection->keepalives + 1);
284
285       otherwise code relying on the value of "$r->connection->keepalives" may
286       malfunction. For example, this counter is used to tell when a new
287       request is coming in over the same connection to a filter that wants to
288       parse only HTTP headers (like "Apache2::Filter::HTTPHeadersFixup"). Of
289       course you will need to set "$r->connection->keepalive(1)" ) as well.
290
291       "bytes_sent"
292
293       The number of bytes sent to the client, handy for logging, etc.
294
295         $bytes_sent = $r->bytes_sent();
296
297       obj: $r ( "Apache2::RequestRec object" )
298       ret: $bytes_sent (integer)
299       since: 2.0.00
300
301       Though as of this writing in Apache 2.0 it doesn't really do what it
302       did in Apache 1.3. It's just set to the size of the response body.  The
303       issue is that buckets from one request may get buffered and not sent
304       during the lifetime of the request, so it's not easy to give a truly
305       accurate count of "bytes sent to the network for this response".
306
307       "connection"
308
309       Get the client connection record
310
311         $c = $r->connection();
312
313       obj: $r ( "Apache2::RequestRec object" )
314       ret: $c ( "Apache2::Connection object" )
315       since: 2.0.00
316
317       "content_encoding"
318
319       Get/set content encoding (the "Content-Encoding" HTTP header).  Content
320       encodings are string like "gzip" or "compress".
321
322         $ce      = $r->content_encoding();
323         $prev_ce = $r->content_encoding($new_ce);
324
325       obj: $r ( "Apache2::RequestRec object" )
326       opt arg1: $new_ce ( string )
327           If passed, sets the content encoding to a new value. It must be a
328           lowercased string.
329
330       ret: $ce ( string )
331           The current content encoding.
332
333           If $new_ce is passed, then the previous value is returned.
334
335       since: 2.0.00
336
337       For example, here is how to send a gzip'ed response:
338
339         require Compress::Zlib;
340         $r->content_type("text/plain");
341         $r->content_encoding("gzip");
342         $r->print(Compress::Zlib::memGzip("some text to be gzipped));
343
344       "content_languages"
345
346       Get/set content languages (the "Content-Language" HTTP header).  Con‐
347       tent languages are string like "en" or "fr".
348
349         $languages = $r->content_languages();
350         $prev_lang = $r->content_languages($nev_lang);
351
352       obj: $r ( "Apache2::RequestRec object" )
353       opt arg1: $new_lang ( ARRAY ref )
354           If passed, sets the content languages to new values. It must be an
355           ARRAY reference of language names, like "en" or "fr"
356
357       ret: $languages ( ARRAY ref )
358           The current list of content languages, as an ARRAY reference.
359
360           If $new_lang is passed, then the previous value is returned.
361
362       since: 2.0.00
363
364       "content_type"
365
366       Get/set the HTTP response Content-type header value.
367
368         my $content_type      = $r->content_type();
369         my $prev_content_type = $r->content_type($new_content_type);
370
371       obj: $r ( "Apache2::RequestRec object" )
372       opt arg1: $new_content_type (MIME type string)
373           Assign a new HTTP response content-type. It will affect the
374           response only if HTTP headers weren't sent yet.
375
376       ret: $content_type
377           The current content-type value.
378
379           If $new_content_type was passed, the previous value is returned
380           instead.
381
382       since: 2.0.00
383
384       For example, set the "Content-type" header to text/plain.
385
386         $r->content_type('text/plain');
387
388       If you set this header via the "headers_out" table directly, it will be
389       ignored by Apache. So do not do that.
390
391       "err_headers_out"
392
393       Get/set MIME response headers, printed even on errors and persist
394       across internal redirects.
395
396         $err_headers_out = $r->err_headers_out();
397
398       obj: $r ( "Apache2::RequestRec object" )
399       ret: $err_headers_out ( "APR::Table object" )
400       since: 2.0.00
401
402       The difference between "headers_out" and "err_headers_out", is that the
403       latter are printed even on error, and persist across internal redirects
404       (so the headers printed for "ErrorDocument" handlers will have them).
405
406       For example, if a handler wants to return a 404 response, but neverthe‐
407       less to set a cookie, it has to be:
408
409         $r->err_headers_out->add('Set-Cookie' => $cookie);
410         return Apache2::Const::NOT_FOUND;
411
412       If the handler does:
413
414         $r->headers_out->add('Set-Cookie' => $cookie);
415         return Apache2::Const::NOT_FOUND;
416
417       the "Set-Cookie" header won't be sent.
418
419       "filename"
420
421       Get/set the filename on disk corresponding to this response (the result
422       of the URI --> filename translation).
423
424         $filename      = $r->filename();
425         $prev_filename = $r->filename($new_filename);
426
427       obj: $r ( "Apache2::RequestRec object" )
428       opt arg1: $new_filename ( string )
429           new value
430
431       ret: $filename ( string )
432           the current filename, or the previous value if the optional
433           $new_filename argument was passed
434
435       since: 2.0.00
436
437       Note that if you change the filename after the "PerlMapToStorageHan‐
438       dler" phase was run and expect Apache to serve it, you need to update
439       its "stat" record, like so:
440
441         use Apache2::RequestRec ();
442         use APR::Finfo ();
443         use APR::Const -compile => qw(FINFO_NORM);
444         $r->filename($newfile);
445         $r->finfo(APR::Finfo::stat($newfile, APR::Const::FINFO_NORM, $r->pool));
446
447       if you don't, Apache will still try to use the previously cached infor‐
448       mation about the previously set value of the filename.
449
450       "finfo"
451
452       Get and set the finfo request record member:
453
454         $finfo = $r->finfo();
455         $r->finfo($finfo);
456
457       obj: $r ( "Apache2::RequestRec object" )
458       opt arg1: $finfo ( "APR::Finfo object" )
459       ret: $finfo ( "APR::Finfo object" )
460           Always returns the current object.
461
462           Due to the internal Apache implementation it's not possible to have
463           two different objects originating from "$r->finfo" at the same
464           time. Whenever "$r->finfo" is updated all objects will be updated
465           too to the latest value.
466
467       since: 2.0.00
468
469       Most of the time, this method is used to get the "finfo" member. The
470       only reason you may want to set it is you need to use it before the
471       Apache's default map_to_storage phase is called.
472
473       Examples:
474
475       ·   What Apache thinks is the current request filename (post the
476           "PerlMapToStorageHandler" phase):
477
478             use Apache2::RequestRec ();
479             use APR::Finfo ();
480             print $r->finfo->fname;
481
482       ·   Populate the "finfo" member (normally, before the "PerlMapToStor‐
483           ageHandler" phase):
484
485             use APR::Finfo ();
486             use APR::Const -compile => qw(FINFO_NORM);
487
488             my $finfo = APR::Finfo::stat(__FILE__, APR::Const::FINFO_NORM, $r->pool);
489             $r->finfo($finfo);
490
491       "handler"
492
493       Get/set the equivalent of the "SetHandler" directive.
494
495         $handler      = $r->handler();
496         $prev_handler = $r->handler($new_handler);
497
498       obj: $r ( "Apache2::RequestRec object" )
499       opt arg1: $new_handler ( string )
500           the new handler.
501
502       ret: $handler ( string )
503           the current handler.
504
505           If $new_handler is passed, the previous value is returned.
506
507       since: 2.0.00
508
509       "header_only"
510
511       Did the client has asked for headers only? e.g. if the request method
512       was HEAD.
513
514         $status = $r->header_only();
515
516       obj: $r ( "Apache2::RequestRec object" )
517       ret: $status ( boolean )
518           Returns true if the client is asking for headers only, false other‐
519           wise
520
521       since: 2.0.00
522
523       "headers_in"
524
525       Get/set the request MIME headers:
526
527         $headers_in = $r->headers_in();
528
529       obj: $r ( "Apache2::RequestRec object" )
530       ret: $headers_in ( "APR::Table object" )
531       since: 2.0.00
532
533       This table is available starting from the "PerlHeaderParserHandler"
534       phase.
535
536       For example you can use it to retrieve the cookie value sent by the
537       client, in the "Cookie:" header:
538
539           my $cookie = $r->headers_in->{Cookie} ⎪⎪ '';
540
541       "headers_out"
542
543       Get/set MIME response headers, printed only on 2xx responses.
544
545         $headers_out = $r->headers_out();
546
547       obj: $r ( "Apache2::RequestRec object" )
548       ret: $headers_out ( "APR::Table object" )
549       since: 2.0.00
550
551       See also "err_headers_out", which allows to set headers for non-2xx
552       responses and persist across internal redirects.
553
554       "hostname"
555
556       Host, as set by full URI or Host:
557
558         $hostname = $r->hostname();
559         $prev_hostname = $r->hostname($new_hostname);
560
561       obj: $r ( "Apache2::RequestRec object" )
562       opt arg1: $new_hostname ( string )
563           new value
564
565       ret: $hostname ( string )
566           the current hostname, or the previous value if the optional
567           $new_hostname argument was passed
568
569       since: 2.0.00
570
571       "input_filters"
572
573       Get/set the first filter in a linked list of request level input fil‐
574       ters:
575
576         $input_filters      = $r->input_filters();
577         $prev_input_filters = $r->input_filters($new_input_filters);
578
579       obj: $r ( "Apache2::RequestRec object" )
580       opt arg1: $new_input_filters
581           Set a new value
582
583       ret: $input_filters ( "Apache2::Filter object" )
584           The first filter in the request level input filters chain.
585
586           If $new_input_filters was passed, returns the previous value.
587
588       since: 2.0.00
589
590       For example instead of using "$r->read()" to read the POST data, one
591       could use an explicit walk through incoming bucket brigades to get that
592       data. The following function "read_post()" does just that (in fact
593       that's what "$r->read()" does behind the scenes):
594
595         use APR::Brigade ();
596         use APR::Bucket ();
597         use Apache2::Filter ();
598
599         use Apache2::Const -compile => qw(MODE_READBYTES);
600         use APR::Const    -compile => qw(SUCCESS BLOCK_READ);
601
602         use constant IOBUFSIZE => 8192;
603
604         sub read_post {
605             my $r = shift;
606
607             my $bb = APR::Brigade->new($r->pool,
608                                        $r->connection->bucket_alloc);
609
610             my $data = '';
611             my $seen_eos = 0;
612             do {
613                 $r->input_filters->get_brigade($bb, Apache2::Const::MODE_READBYTES,
614                                                APR::Const::BLOCK_READ, IOBUFSIZE);
615
616                 for (my $b = $bb->first; $b; $b = $bb->next($b)) {
617                     if ($b->is_eos) {
618                         $seen_eos++;
619                         last;
620                     }
621
622                     if ($b->read(my $buf)) {
623                         $data .= $buf;
624                     }
625
626                     $b->remove; # optimization to reuse memory
627                 }
628
629             } while (!$seen_eos);
630
631             $bb->destroy;
632
633             return $data;
634         }
635
636       As you can see "$r->input_filters" gives us a pointer to the last of
637       the top of the incoming filters stack.
638
639       "main"
640
641       Get the main request record
642
643         $main_r = $r->main();
644
645       obj: $r ( "Apache2::RequestRec object" )
646       ret: $main_r ( "Apache2::RequestRec object" )
647           If the current request is a sub-request, this method returns a
648           blessed reference to the main request structure. If the current
649           request is the main request, then this method returns "undef".
650
651           To figure out whether you are inside a main request or a
652           sub-request/internal redirect, use "$r->is_initial_req".
653
654       since: 2.0.00
655
656       "method"
657
658       Get/set the current request method (e.g. "GET", "HEAD", "POST", etc.):
659
660         $method     = $r->method();
661         $pre_method = $r->method($new_method);
662
663       obj: $r ( "Apache2::RequestRec object" )
664       opt arg1: $new_method ( string )
665           a new value
666
667       ret: $method ( string )
668           The current method as a string
669
670           if $new_method was passed the previous value is returned.
671
672       since: 2.0.00
673
674       "method_number"
675
676       Get/set the HTTP method, issued by the client ("Apache2::Const::M_GET",
677       "Apache2::Const::M_POST", etc.)
678
679         $methnum      = $r->method_number();
680         $prev_methnum = $r->method_number($new_methnum);
681
682       obj: $r ( "Apache2::RequestRec object" )
683       opt arg1: $new_methnum ( "Apache2::Const :methods constant" )
684           a new value
685
686       ret: $methnum ( "Apache2::Const :methods constant" )
687           The current method as a number
688
689           if $new_methnum was passed the previous value is returned.
690
691       since: 2.0.00
692
693       See the "$r->allowed" entry for examples.
694
695       "mtime"
696
697       Last modified time of the requested resource
698
699         $mtime      = $r->mtime();
700         $prev_mtime = $r->mtime($new_mtime);
701
702       obj: $r ( "Apache2::RequestRec object" )
703       opt arg1: $new_mtime (epoch seconds).
704           a new value
705
706       ret: $mtime (epoch seconds).
707           the current value
708
709           if $new_mtime was passed the previous value is returned.
710
711       since: 2.0.00
712
713       "next"
714
715       Pointer to the redirected request if this is an external redirect
716
717         $next_r = $r->next();
718
719       obj: $r ( "Apache2::RequestRec object" )
720       ret: $next_r ( "Apache2::RequestRec object" )
721           returns a blessed reference to the next (internal) request struc‐
722           ture or "undef" if there is no next request.
723
724       since: 2.0.00
725
726       "no_local_copy"
727
728       There is no local copy of this response
729
730         $status = $r->no_local_copy();
731
732       obj: $r ( "Apache2::RequestRec object" )
733       ret: $status (integer)
734       since: 2.0.00
735
736       Used internally in certain sub-requests to prevent sending
737       "Apache2::Const::HTTP_NOT_MODIFIED" for a fragment or error documents.
738       For example see the implementation in modules/filters/mod_include.c.
739
740       Also used internally in "$r->meets_conditions" -- if set to a true
741       value, the conditions are always met.
742
743       "notes"
744
745       Get/set text notes for the duration of this request. These notes can be
746       passed from one module to another (not only mod_perl, but modules in
747       any other language):
748
749         $notes      = $r->notes();
750         $prev_notes = $r->notes($new_notes);
751
752       obj: $r ( "Apache2::RequestRec object" )
753       opt arg1: $new_notes ( "APR::Table object" )
754       ret: $notes ( "APR::Table object" )
755           the current notes table.
756
757           if the $new_notes argument was passed, returns the previous value.
758
759       since: 2.0.00
760
761       If you want to pass Perl structures, you can use "$r->pnotes".
762
763       Also see "$c->notes"
764
765       "output_filters"
766
767       Get the first filter in a linked list of request level output filters:
768
769         $output_filters      = $r->output_filters();
770         $prev_output_filters = $r->output_filters($new_output_filters);
771
772       obj: $r ( "Apache2::RequestRec object" )
773       opt arg1: $new_output_filters
774           Set a new value
775
776       ret: $output_filters ( "Apache2::Filter object" )
777           The first filter in the request level output filters chain.
778
779           If $new_output_filters was passed, returns the previous value.
780
781       since: 2.0.00
782
783       For example instead of using "$r->print()" to send the response body,
784       one could send the data directly to the first output filter. The fol‐
785       lowing function "send_response_body()" does just that:
786
787         use APR::Brigade ();
788         use APR::Bucket ();
789         use Apache2::Filter ();
790
791         sub send_response_body {
792             my ($r, $data) = @_;
793
794             my $bb = APR::Brigade->new($r->pool,
795                                        $r->connection->bucket_alloc);
796
797             my $b = APR::Bucket->new($bb->bucket_alloc, $data);
798             $bb->insert_tail($b);
799             $r->output_filters->fflush($bb);
800             $bb->destroy;
801         }
802
803       In fact that's what "$r->read()" does behind the scenes. But it also
804       knows to parse HTTP headers passed together with the data and it also
805       implements buffering, which the above function does not.
806
807       "path_info"
808
809       Get/set the "PATH_INFO", what is left in the path after the URI -->
810       filename translation:
811
812         $path_info      = $r->path_info();
813         $prev_path_info = $r->path_info($path_info);
814
815       obj: $r ( "Apache2::RequestRec object" )
816       opt arg1: $path_info ( string )
817           Set a new value
818
819       ret: $path_info ( string )
820           Return the current value.
821
822           If the optional argument $path_info is passed, the previous value
823           is returned.
824
825       since: 2.0.00
826
827       "per_dir_config"
828
829       Get the dir config vector:
830
831         $per_dir_config = $r->per_dir_config();
832
833       obj: $r ( "Apache2::RequestRec object" )
834       ret: $per_dir_config ( "Apache2::ConfVector object" )
835       since: 2.0.00
836
837       For an indepth discussion, refer to the Apache Server Configuration
838       Customization in Perl chapter.
839
840       "pool"
841
842       The pool associated with the request
843
844         $p = $r->pool();
845
846       obj: $r ( "Apache2::RequestRec object" )
847       ret: $p ( "APR::Pool object" )
848       since: 2.0.00
849
850       "prev"
851
852       Pointer to the previous request if this is an internal redirect
853
854         $prev_r = $r->prev();
855
856       obj: $r ( "Apache2::RequestRec object" )
857       ret: $prev_r ( "Apache2::RequestRec object" )
858           a blessed reference to the previous (internal) request structure or
859           "undef" if there is no previous request.
860
861       since: 2.0.00
862
863       "proto_input_filters"
864
865       Get the first filter in a linked list of protocol level input filters:
866
867         $proto_input_filters      = $r->proto_input_filters();
868         $prev_proto_input_filters = $r->proto_input_filters($new_proto_input_filters);
869
870       obj: $r ( "Apache2::RequestRec object" )
871       opt arg1: $new_proto_input_filters
872           Set a new value
873
874       ret: $proto_input_filters ( "Apache2::Filter object" )
875           The first filter in the protocol level input filters chain.
876
877           If $new_proto_input_filters was passed, returns the previous value.
878
879       since: 2.0.00
880
881       "$r->proto_input_filters" points to the same filter as "$r->connec‐
882       tion->input_filters".
883
884       "proto_num"
885
886       Get current request's HTTP protocol version number
887
888         $proto_num = $r->proto_num();
889
890       obj: $r ( "Apache2::RequestRec object" )
891       ret: $proto_num (integer)
892           current request's HTTP protocol version number, e.g.: HTTP/1.0 ==
893           1000, HTTP/1.1 = 1001
894
895       since: 2.0.00
896
897       "proto_output_filters"
898
899       Get the first filter in a linked list of protocol level output filters:
900
901         $proto_output_filters      = $r->proto_output_filters();
902         $prev_proto_output_filters = $r->proto_output_filters($new_proto_output_filters);
903
904       obj: $r ( "Apache2::RequestRec object" )
905       opt arg1: $new_proto_output_filters
906           Set a new value
907
908       ret: $proto_output_filters ( "Apache2::Filter object" )
909           The first filter in the protocol level output filters chain.
910
911           If $new_proto_output_filters was passed, returns the previous
912           value.
913
914       since: 2.0.00
915
916       "$r->proto_output_filters" points to the same filter as "$r->connec‐
917       tion->output_filters".
918
919       "protocol"
920
921       Get a string identifying the protocol that the client speaks.
922
923         $protocol = $r->protocol();
924
925       obj: $r ( "Apache2::RequestRec object" )
926       ret: $protocl ( string )
927           Typical values are "HTTP/1.0" or "HTTP/1.1".
928
929           If the client didn't specify the protocol version, the default is
930           "HTTP/0.9"
931
932       since: 2.0.00
933
934       "proxyreq"
935
936       Get/set the proxyrec request record member and optionally adjust other
937       related fields.
938
939         $status = $r->proxyreq($val);
940
941       obj: $r ( "Apache2::RequestRec object" )
942       opt arg1: $val ( integer )
943           0, 1 or none.
944
945       ret: $status ( integer )
946           If $val is 0 or 1, the proxyrec member will be set to that value
947           and previous value will be returned.
948
949           If $val is not passed, and "$r->proxyreq" is not true, and the
950           proxy request is matching the current vhost (scheme, hostname and
951           port), the proxyrec member will be set to 1 and that value will be
952           returned. In addition "$r->uri" is set to "$r->unparsed_uri" and
953           "$r->filename" is set to ""modperl-proxy:".$r->uri". If those con‐
954           ditions aren't true 0 is returned.
955
956       since: 2.0.00
957
958       For example to turn a normal request into a proxy request to be handled
959       on the same server in the "PerlTransHandler" phase run:
960
961         my $real_url = $r->unparsed_uri;
962         $r->proxyreq(1);
963         $r->uri($real_url);
964         $r->filename("proxy:$real_url");
965         $r->handler('proxy-server');
966
967       Also remember that if you want to turn a proxy request into a non-proxy
968       request, it's not enough to call:
969
970         $r->proxyreq(0);
971
972       You need to adjust "$r->uri" and "$r->filename" as well if you run that
973       code in "PerlPostReadRequestHandler" phase, since if you don't --
974       "mod_proxy"'s own post_read_request handler will override your settings
975       (as it will run after the mod_perl handler).
976
977       "request_time"
978
979       Time when the request started
980
981         $request_time = $r->request_time();
982
983       obj: $r ( "Apache2::RequestRec object" )
984       ret: $request_time (epoch seconds).
985       since: 2.0.00
986
987       "server"
988
989       Get the "Apache2::Server" object for the server the request $r is run‐
990       ning under.
991
992         $s = $r->server();
993
994       obj: $r ( "Apache2::RequestRec object" )
995       ret: $s ( "Apache2::ServerRec object" )
996       since: 2.0.00
997
998       "status"
999
1000       Get/set the reply status for the client request.
1001
1002         $status      = $r->status();
1003         $prev_status = $r->status($new_status);
1004
1005       obj: $r ( "Apache2::RequestRec object" )
1006       opt arg1: $new_status ( integer )
1007           If $new_status is passed the new status is assigned.
1008
1009           Normally you would use some "Apache2::Const constant", e.g.
1010           "Apache2::Const::REDIRECT".
1011
1012       ret: $newval ( integer )
1013           The current value.
1014
1015           If $new_status is passed the old value is returned.
1016
1017       since: 2.0.00
1018
1019       Usually you will set this value indirectly by returning the status code
1020       as the handler's function result.  However, there are rare instances
1021       when you want to trick Apache into thinking that the module returned an
1022       "Apache2::Const::OK" status code, but actually send the browser a non-
1023       OK status. This may come handy when implementing an HTTP proxy handler.
1024       The proxy handler needs to send to the client, whatever status code the
1025       proxied server has returned, while returning "Apache2::Const::OK" to
1026       Apache. e.g.:
1027
1028         $r->status($some_code);
1029         return Apache2::Const::OK
1030
1031       See also "$r->status_line", which. if set, overrides "$r->status".
1032
1033       "status_line"
1034
1035       Get/set the response status line.  The status line is a string like
1036       "200 Document follows" and it will take precedence over the value spec‐
1037       ified using the "$r->status()" described above.
1038
1039         $status_line      = $r->status_line();
1040         $prev_status_line = $r->status_line($new_status_line);
1041
1042       obj: $r ( "Apache2::RequestRec object" )
1043       opt arg1: $new_status_line ( string )
1044       ret: $status_line ( string )
1045       since: 2.0.00
1046
1047       When discussing "$r->status" we have mentioned that sometimes a handler
1048       runs to a successful completion, but may need to return a different
1049       code, which is the case with the proxy server. Assuming that the proxy
1050       handler forwards to the client whatever response the proxied server has
1051       sent, it'll usually use "status_line()", like so:
1052
1053         $r->status_line($response->code() . ' ' . $response->message());
1054         return Apache2::Const::OK;
1055
1056       In this example $response could be for example an "HTTP::Response"
1057       object, if "LWP::UserAgent" was used to implement the proxy.
1058
1059       This method is also handy when you extend the HTTP protocol and add new
1060       response codes. For example you could invent a new error code and tell
1061       Apache to use that in the response like so:
1062
1063         $r->status_line("499 We have been FooBared");
1064         return Apache2::Const::OK;
1065
1066       Here 499 is the new response code, and We have been FooBared is the
1067       custom response message.
1068
1069       "subprocess_env"
1070
1071       Get/set the Apache "subprocess_env" table, or optionally set the value
1072       of a named entry.
1073
1074                      $r->subprocess_env;
1075         $env_table = $r->subprocess_env;
1076
1077                $r->subprocess_env($key => $val);
1078         $val = $r->subprocess_env($key);
1079
1080       obj: $r ( "Apache2::RequestRec object" )
1081       opt arg1: $key ( string )
1082       opt arg2: $val ( string )
1083       ret: "..."
1084       since: 2.0.00
1085
1086       When called in VOID context with no arguments, it populate %ENV with
1087       special variables (e.g. $ENV{QUERY_STRING}) like mod_cgi does.
1088
1089       When called in a non-VOID context with no arguments, it returns an
1090       "APR::Table object".
1091
1092       When the $key argument (string) is passed, it returns the corresponding
1093       value (if such exists, or "undef". The following two lines are equiva‐
1094       lent:
1095
1096         $val = $r->subprocess_env($key);
1097         $val = $r->subprocess_env->get($key);
1098
1099       When the $key and the $val arguments (strings) are passed, the value is
1100       set. The following two lines are equivalent:
1101
1102         $r->subprocess_env($key => $val);
1103         $r->subprocess_env->set($key => $val);
1104
1105       The "subprocess_env" "table" is used by "Apache2::SubProcess", to pass
1106       environment variables to externally spawned processes. It's also used
1107       by various Apache modules, and you should use this table to pass the
1108       environment variables. For example if in "PerlHeaderParserHandler" you
1109       do:
1110
1111          $r->subprocess_env(MyLanguage => "de");
1112
1113       you can then deploy "mod_include" and write in .shtml document:
1114
1115          <!--#if expr="$MyLanguage = en" -->
1116          English
1117          <!--#elif expr="$MyLanguage = de" -->
1118          Deutsch
1119          <!--#else -->
1120          Sorry
1121          <!--#endif -->
1122
1123       "the_request"
1124
1125       First HTTP request header
1126
1127         $request = $r->the_request();
1128
1129       obj: $r ( "Apache2::RequestRec object" )
1130       ret: $request ( string )
1131           For example:
1132
1133             GET /foo/bar/my_path_info?args=3 HTTP/1.0
1134
1135       since: 2.0.00
1136
1137       "unparsed_uri"
1138
1139       The URI without any parsing performed
1140
1141         $unparsed_uri = $r->unparsed_uri();
1142
1143       obj: $r ( "Apache2::RequestRec object" )
1144       ret: $unparsed_uri ( string )
1145       since: 2.0.00
1146
1147       If for example the request was:
1148
1149         GET /foo/bar/my_path_info?args=3 HTTP/1.0
1150
1151       "$r->uri" returns:
1152
1153         /foo/bar/my_path_info
1154
1155       whereas "$r->unparsed_uri" returns:
1156
1157         /foo/bar/my_path_info?args=3
1158
1159       "uri"
1160
1161       The path portion of the URI
1162
1163         $uri         = $r->uri();
1164         my $prec_uri = $r->uri($new_uri);
1165
1166       obj: $r ( "Apache2::RequestRec object" )
1167       opt arg1: $new_uri ( string )
1168       ret: $uri ( string )
1169       since: 2.0.00
1170
1171       See the example in the "$r->unparsed_uri" section.
1172
1173       "user"
1174
1175       Get the user name, if an authentication process was successful. Or set
1176       it.
1177
1178         $user      = $r->user();
1179         $prev_user = $r->user($new_user);
1180
1181       obj: $r ( "Apache2::RequestRec object" )
1182       opt arg1: $new_user ( string )
1183           Pass $new_user to set a new value
1184
1185       ret: $user ( string )
1186           The current username if an authentication process was successful.
1187
1188           If $new_user was passed, the previous value is returned.
1189
1190       since: 2.0.00
1191
1192       For example, let's print the username passed by the client:
1193
1194         my ($res, $sent_pw) = $r->get_basic_auth_pw;
1195         return $res if $res != Apache2::Const::OK;
1196         print "User: ", $r->user;
1197

Unsupported API

1199       "Apache2::RequestRec" also provides auto-generated Perl interface for a
1200       few other methods which aren't tested at the moment and therefore their
1201       API is a subject to change. These methods will be finalized later as a
1202       need arises. If you want to rely on any of the following methods please
1203       contact the the mod_perl development mailing list so we can help each
1204       other take the steps necessary to shift the method to an officially
1205       supported API.
1206
1207       "allowed_methods"
1208
1209       META: Autogenerated - needs to be reviewed/completed
1210
1211       List of allowed methods
1212
1213         $list = $r->allowed_methods();
1214
1215       obj: $r ( "Apache2::RequestRec object" )
1216       ret: $list ( "Apache2::MethodList object" )
1217       since: 2.0.00
1218
1219       META: Apache2::MethodList is not available at the moment
1220
1221       "allowed_xmethods"
1222
1223       META: Autogenerated - needs to be reviewed/completed
1224
1225       Array of extension methods
1226
1227         $array = $r->allowed_xmethods();
1228
1229       obj: $r ( "Apache2::RequestRec object" )
1230       ret: $array ( "APR::ArrayHeader object" )
1231       since: 2.0.00
1232
1233       META: APR::ArrayHeader is not available at the moment
1234
1235       "request_config"
1236
1237       Config vector containing pointers to request's per-server config struc‐
1238       tures
1239
1240         $ret = $r->request_config($newval);
1241
1242       obj: $r ( "Apache2::RequestRec object" )
1243       opt arg1: $newval ( "Apache2::ConfVector object" )
1244       since: 2.0.00
1245
1246       "used_path_info"
1247
1248       META: Autogenerated - needs to be reviewed/completed
1249
1250       Flag for the handler to accept or reject path_info on the current
1251       request.  All modules should respect the AP_REQ_ACCEPT_PATH_INFO and
1252       AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO indi‐
1253       cates they may follow existing conventions.  This is set to the user's
1254       preference upon HOOK_VERY_FIRST of the fixups.
1255
1256         $ret = $r->used_path_info($newval);
1257
1258       obj: $r ( "Apache2::RequestRec object" )
1259       arg1: $newval (integer)
1260       since: 2.0.00
1261

Copyright

1266       mod_perl 2.0 and its core modules are copyrighted under The Apache
1267       Software License, Version 2.0.
1268

Authors

1270       The mod_perl development team and numerous contributors.
1271
1272
1273
1274perl v5.8.8                       2006-11-19 docs::api::Apache2::RequestRec(3)