3
Apache::RequestUtil - Perl API for Apache request record utils
10
use Apache::RequestUtil ();
12
# directory level PerlOptions flags lookup
13
$r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
26
=head1 Class methods API
31
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) object
32
for the current request.
38
=item obj: C<Apache> (class name)
42
=item ret: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
48
This method is only available if C<L<PerlOptions
49
+GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_>> is
57
=head2 C<default_type>
59
META: Autogenerated - needs to be reviewed/completed
61
Retrieve the value of the DefaultType directive, or text/plain if not set
63
$ret = $r->default_type();
67
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
71
=item ret: C<$ret> (string)
81
=head2 C<document_root>
83
META: Autogenerated - needs to be reviewed/completed
85
Retrieve the document root for this server
87
$ret = $r->document_root();
91
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
95
=item ret: C<$ret> (string)
105
=head2 C<get_limit_req_body>
107
META: Autogenerated - needs to be reviewed/completed
109
Return the limit on bytes in request msg body
111
$ret = $r->get_limit_req_body();
115
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
119
=item ret: C<$ret> (integer)
121
the maximum number of bytes in the request msg body
129
=head2 C<get_server_name>
131
META: Autogenerated - needs to be reviewed/completed
133
Get the current server name from the request
135
$ret = $r->get_server_name();
139
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
143
=item ret: C<$ret> (string)
153
=head2 C<get_server_port>
155
META: Autogenerated - needs to be reviewed/completed
157
Get the current server port
159
$ret = $r->get_server_port();
163
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
167
=item ret: C<$ret> (integer)
177
=head2 C<get_status_line>
179
META: Autogenerated - needs to be reviewed/completed
181
Return the Status-Line for a given status code (excluding the
182
HTTP-Version field). If an invalid or unknown status code is
183
passed, "500 Internal Server Error" will be returned.
185
$ret = get_status_line($status);
189
=item obj: C<$status> (integer)
193
=item ret: C<$ret> (string)
203
=head2 C<is_initial_req>
205
META: Autogenerated - needs to be reviewed/completed
207
Determine if the current request is the main request or a sub requests
209
$ret = $r->is_initial_req();
213
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
217
=item ret: C<$ret> (integer)
227
=head2 C<method_register>
229
META: Autogenerated - needs to be reviewed/completed
231
Register a new request method, and return the offset that will be
232
associated with that method.
234
$ret = $p->method_register($methname);
238
=item obj: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
240
The pool to create registered method numbers from.
242
=item arg1: C<$methname> (string)
244
The name of the new method to register.
246
=item ret: C<$ret> (integer)
248
Ab int value representing an offset into a bitmask.
258
META: Autogenerated - needs to be reviewed/completed
262
$ret = $r->add_config($lines, $path, $override);
266
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
268
=item arg1: C<$lines> (ARRAY ref)
270
=item opt arg3: C<$path> (scalar)
272
=item opt arg4: C<$override> (string)
274
=item ret: C<$ret> (string)
279
C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_add_config_>>
284
META: Autogenerated - needs to be reviewed/completed
288
$location = $r->location($location);
292
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
294
=item opt arg2: C<$location> (string)
296
=item ret: C<$location> (integer)
303
=head2 C<location_merge>
305
META: Autogenerated - needs to be reviewed/completed
309
$ret = $r->location_merge($location);
313
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
315
=item arg1: C<$location> (string)
317
=item ret: C<$ret> (integer)
325
META: Autogenerated - needs to be reviewed/completed
327
Notes from one module to another
329
$pnotes = $r->pnotes();
330
$pnotes = $r->pnotes($new_pnotes);
334
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
336
=item opt arg2: C<$new_pnotes> (C<L<APR::Table|docs::2.0::api::APR::Table>>)
338
=item ret: C<$pnotes> (C<L<APR::Table|docs::2.0::api::APR::Table>>)
344
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec/C_notes_>>),
345
but values can be any perl variables. That also means that it can be
346
used only between perl modules.
354
META: Autogenerated - needs to be reviewed/completed
357
$ret = $r->no_cache($flag);
361
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
363
=item arg1: C<$flag> (number)
365
=item ret: C<$ret> (integer)
374
META: Autogenerated - needs to be reviewed/completed
376
$string = $r->as_string();
380
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
382
=item ret: C<$string> (string)
389
=head2 C<get_handlers>
391
Returns a reference to a list of handlers enabled for
394
$handlers_list = $r->get_handlers($hook_name);
398
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
400
=item arg1: C<$hook_name> (string)
402
a string representing the phase to handle.
404
=item ret: C<@handlers> (CODE ref or ref to ARRAY of CODE refs)
406
a list of handler subroutines CODE references
412
A list of handlers configured to run at the response phase:
414
my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
419
=head2 C<push_handlers>
421
Add one or more handlers to a list of handlers to be called for a
424
$r->push_handlers($hook_name => \&handler);
425
$r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
429
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
431
=item arg1: C<$hook_name> (string)
433
a string representing the phase to handle.
435
=item arg2: C<$handlers> (CODE ref or SUB name or ref to an ARRAY of CODE refs)
437
a single handler CODE reference or just a name of the subroutine
438
(fully qualified unless defined in the current package).
440
if more than one passed, use a reference to an array of CODE refs
441
and/or subroutine names.
443
=item ret: no return value
451
$r->push_handlers(PerlResponseHandler => \&handler);
455
$r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
459
$r->push_handlers(PerlLogHandler => sub { return Apache::OK });
464
=head2 C<set_handlers>
466
Set a list of handlers to be called for a given phase. Any previously
467
set handlers are forgotten.
469
$r->set_handlers($hook_name => \&handler);
470
$r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
471
$r->set_handlers($hook_name => []);
472
$r->set_handlers($hook_name => undef);
476
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
478
=item arg1: C<$hook_name> (string)
480
a string representing the phase to handle.
482
=item arg2: C<$handlers> (CODE ref or SUB name or ref to an ARRAY of CODE refs)
484
a reference to a single handler CODE reference or just a name of the
485
subroutine (fully qualified unless defined in the current package).
487
if more than one passed, use a reference to an array of CODE refs
488
and/or subroutine names.
490
if the argument is C<undef> or [] the list of handlers is reset to
493
=item ret: no return value
501
$r->set_handlers(PerlResponseHandler => \&handler);
505
$r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
509
$r->set_handlers(PerlLogHandler => sub { return Apache::OK });
511
Reset any previously set handlers:
513
$r->set_handlers(PerlCleanupHandler => []);
517
$r->set_handlers(PerlCleanupHandler => undef);
522
=head2 C<set_basic_credentials>
524
META: Autogenerated - needs to be reviewed/completed
528
$r->set_basic_credentials($username, $password);
532
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
534
=item arg1: C<$username> (string)
536
=item arg2: C<$password> (string)
538
=item ret: no return value
546
=head2 C<slurp_filename>
548
META: Autogenerated - needs to be reviewed/completed
551
Return a reference to contents of C<$r-E<gt>filename>.
553
$content = $r->slurp_filename($tainted);
557
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
559
=item arg1: C<$tainted> (number)
561
By default the returned data is tainted (if run under C<-T>). If an
562
optional C<$tainted> flag is set to zero, the data will be marked as
563
non-tainted. Do not set this flag to zero unless you know what you are
564
doing, you may create a security hole in your program if you do. For
565
more information see the I<perlsec> manpage. If you wonder why this
566
option is available, it is used internally by the
567
C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> handler and
568
friends, because the CGI scripts that it reads are considered safe
569
(you could just as well C<require()> them).
571
=item ret: C<$content> (scalar)
576
=head2 C<is_perl_option_enabled>
578
check whether a directory level PerlOptions flag is enabled or not.
580
$result = $r->is_perl_option_enabled($flag);
585
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
587
=item arg1: C<$flag> (string)
589
=item ret: C<$result> (integer)
593
For example to check whether the C<SetupEnv> option is enabled for the
594
current request (which can be disabled with C<PerlOptions -SetupEnv>)
595
and populate the environment variables table if disabled:
597
$r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
600
L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> and
601
L<the equivalent function for server level PerlOptions
602
flags|docs::2.0::api::Apache::ServerUtil/C_is_perl_option_enabled_>.
610
dir_config() provides an interface for the per-directory variable
611
specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
612
can be manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
615
$table = $r->dir_config();
616
$value = $r->dir_config($key);
617
@values = $r->dir_config($key);
618
$r->dir_config($key, $val);
622
=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
624
=item opt arg2: C<$key> (string)
626
=item opt arg3: C<$val> (string)
628
=item ret: C<$ret> (scalar)
630
Depends on the passed arguments, see further discussion
635
The keys are case-insensitive.
637
$apr_table = $r->dir_config();
639
dir_config() called in a scalar context without the C<$key> argument
640
returns a I<HASH> reference blessed into the
641
C<L<APR::Table|docs::2.0::api::APR::Table>> class. This object can be
642
manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
643
methods. For available methods see
644
the C<L<APR::Table|docs::2.0::api::APR::Table>> manpage.
646
@values = $r->dir_config($key);
648
If the C<$key> argument is passed in the list context a list of all
649
matching values will be returned. This method is ineffective for big
650
tables, as it does a linear search of the table. Thefore avoid using
651
this way of calling dir_config() unless you know that there could be
652
more than one value for the wanted key and all the values are wanted.
654
$value = $r->dir_config($key);
656
If the C<$key> argument is passed in the scalar context only a single
657
value will be returned. Since the table preserves the insertion order,
658
if there is more than one value for the same key, the oldest value
659
assosiated with the desired key is returned. Calling in the scalar
660
context is also much faster, as it'll stop searching the table as soon
661
as the first match happens.
663
$r->dir_config($key => $val);
665
If the C<$key> and the C<$val> arguments are used, the set() operation
666
will happen: all existing values associated with the key C<$key> (and
667
the key itself) will be deleted and C<$value> will be placed instead.
669
$r->dir_config($key => undef);
671
If C<$val> is I<undef> the unset() operation will happen: all existing
672
values associated with the key C<$key> (and the key itself) will be
681
L<mod_perl 2.0 documentation|docs::2.0::index>.
688
mod_perl 2.0 and its core modules are copyrighted under
689
The Apache Software License, Version 1.1.
696
L<The mod_perl development team and numerous
697
contributors|about::contributors::people>.
added
removed
docs/api/Apache/RequestUtil.pod
