Apache2::CmdParms(3pm)

1docs::api::Apache2::CmdUPsaerrmsC(o3n)tributed Perl Docudmoecnst:a:taipoin::Apache2::CmdParms(3)
2
3
4

NAME

6       Apache2::CmdParms - Perl API for Apache command parameters object
7

Synopsis

9         use Apache2::CmdParms ();
10         use Apache2::Module ();
11         use Apache2::Const -compile => qw(NOT_IN_LOCATION);
12
13         my @directives = (
14           {
15             name => 'MyDirective',
16             cmd_data => 'some extra data',
17           },
18         );
19
20         Apache2::Module::add(__PACKAGE__, \@directives);
21
22         sub MyDirective {
23             my ($self, $parms, $args) = @_;
24
25             # push config
26             $parms->add_config(['ServerTokens off']);
27
28             # this command's command object
29             $cmd = $parms->cmd;
30
31             # check the current command's context
32             $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);
33
34             # this command's context
35             $context = $parms->context;
36
37             # this command's directive object
38             $directive = $parms->directive;
39
40             # the extra information passed thru cmd_data to
41             # Apache2::Module::add()
42             $info = $parms->info;
43
44             # which methods are <Limit>ed ?
45             $is_limited = $parms->method_is_limited('GET');
46
47             # which allow-override bits are set
48             $override = $parms->override;
49
50             # which Options are allowed by AllowOverride (since Apache 2.2)
51             $override = $parms->override_opts;
52
53             # the path this command is being invoked in
54             $path = $parms->path;
55
56             # this command's pool
57             $p = $parms->pool;
58
59             # this command's configuration time pool
60             $p = $parms->temp_pool;
61         }
62

Description

64       "Apache2::CmdParms" provides the Perl API for Apache command parameters
65       object.
66

API

68       "Apache2::CmdParms" provides the following functions and/or methods:
69
70       "add_config"
71
72       Dynamically add Apache configuration at request processing runtime:
73
74         $parms->add_config($lines);
75
76       obj: $parms ( "Apache2::CmdParms object" )
77       arg1: $lines (ARRAY ref)
78           An ARRAY reference containing configuration lines per element,
79           without the new line terminators.
80
81       ret: no return value
82       since: 2.0.00
83
84       See also: "$s->add_config", "$r->add_config"
85
86       "check_cmd_context"
87
88       Check the current command against a context bitmask of forbidden con‐
89       texts.
90
91         $error = $parms->check_cmd_context($check);
92
93       obj: $parms ( "Apache2::CmdParms object" )
94       arg1: $check ( "Apache2::Const :context constant" )
95           the context to check against.
96
97       ret: $error ( string / undef )
98           If the context is forbidden, this method returns a textual descrip‐
99           tion of why it was forbidden. If the context is permitted, this
100           method returns "undef".
101
102       since: 2.0.00
103
104       For example here is how to check whether a command is allowed in the
105       "<Location>" container:
106
107         use Apache2::Const -compile qw(NOT_IN_LOCATION);
108         if (my $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
109             die "directive ... not allowed in <Location> context"
110         }
111
112       "cmd"
113
114       This module's command information
115
116         $cmd = $parms->cmd();
117
118       obj: $parms ( "Apache2::CmdParms object" )
119       ret: $cmd ( "Apache2::Command object" )
120       since: 2.0.00
121
122       "directive"
123
124       This command's directive object in the configuration tree
125
126         $directive = $parms->directive;
127
128       obj: $parms ( "Apache2::CmdParms object" )
129       ret: $directive ( "Apache2::Directive object" )
130           The current directive node in the configuration tree
131
132       since: 2.0.00
133
134       "info"
135
136       The extra information passed through "cmd_data" in "Apache2::Mod‐
137       ule::add()".
138
139         $info = $parms->info;
140
141       obj: $parms ( "Apache2::CmdParms object" )
142       ret: $info ( string )
143           The string passed in "cmd_data"
144
145       since: 2.0.00
146
147       For example here is how to pass arbitrary information to a directive
148       subroutine:
149
150         my @directives = (
151           {
152             name => 'MyDirective1',
153             func => \&MyDirective,
154             cmd_data => 'One',
155           },
156           {
157             name => 'MyDirective2',
158             func => \&MyDirective,
159             cmd_data => 'Two',
160           },
161         );
162         Apache2::Module::add(__PACKAGE__, \@directives);
163
164         sub MyDirective {
165           my ($self, $parms, $args) = @_;
166           my $info = $parms->info;
167         }
168
169       In this example $info will either be 'One' or 'Two' depending on
170       whether the directive was called as MyDirective1 or MyDirective2.
171
172       "method_is_limited"
173
174       Discover if a method is <Limit>ed in the current scope
175
176         $is_limited = $parms->method_is_limited($method);
177
178       obj: $parms ( "Apache2::CmdParms object" )
179       arg1: $method (string)
180           The name of the method to check for
181
182       ret: $is_limited ( boolean )
183       since: 2.0.00
184
185       For example, to check if the "GET" method is being "<Limit>"ed in the
186       current scope, do:
187
188         if ($parms->method_is_limited('GET') {
189             die "...";
190         }
191
192       "override"
193
194       Which allow-override bits are set ("AllowOverride" directive)
195
196         $override = $parms->override;
197
198       obj: $parms ( "Apache2::CmdParms object" )
199       ret: $override ( bitmask )
200           the allow-override bits bitmask, which can be tested against
201           "Apache2::Const :override constants".
202
203       since: 2.0.00
204
205       For example to check that the "AllowOverride"'s "AuthConfig" and "File‐
206       Info" options are enabled for this command, do:
207
208         use Apache2::Const -compile qw(:override);
209         $wanted = Apache2::Const::OR_AUTHCFG ⎪ Apache2::Const::OR_FILEINFO;
210         $masked = $parms->override & $wanted;
211         unless ($wanted == $masked) {
212             die "...";
213         }
214
215       "override_opts"
216
217       Which options are allowed to be overridden by ".htaccess" files. This
218       is set by "AllowOverride Options=...".
219
220         $override_opts = $parms->override_opts;
221
222       Enabling single options was introduced with Apache 2.2. For Apache 2.0
223       this function simply returns a bitmask with all options allowed.
224
225       obj: $parms ( "Apache2::CmdParms object" )
226       ret: $override_opts ( bitmask )
227           the bitmask, which can be tested against "Apache2::Const :options
228           constants".
229
230       since: 2.0.3
231
232       "path"
233
234       The current pathname/location/match of the block this command is in
235
236         $path = $parms->path;
237
238       obj: $parms ( "Apache2::CmdParms object" )
239       ret: $path ( string / "undef" )
240           If configuring for a block like <Location>, <LocationMatch>,
241           <Directory>, etc., the pathname part of that directive. Otherwise,
242           "undef" is returned.
243
244       since: 2.0.00
245
246       For example for a container block:
247
248         <Location /foo>
249         ...
250         </Location>
251
252       '/foo' will be returned.
253
254       "pool"
255
256       Pool associated with this command
257
258         $p = $parms->pool;
259
260       obj: $parms ( "Apache2::CmdParms object" )
261       ret: $p ( "APR::Pool object" )
262       since: 2.0.00
263
264       "server"
265
266       The (vhost) server this command was defined in httpd.conf
267
268         $s = $parms->server;
269
270       obj: $parms ( "Apache2::CmdParms object" )
271       ret: $s ( "Apache2::Server object" )
272       since: 2.0.00
273
274       "temp_pool"
275
276       Pool for scratch memory; persists during configuration, but destroyed
277       before the first request is served.
278
279         $temp_pool = $parms->temp_pool;
280
281       obj: $parms ( "Apache2::CmdParms object" )
282       ret: $temp_pool ( "APR::Pool object" )
283       since: 2.0.00
284
285       Most likely you shouldn't use this pool object, unless you know what
286       you are doing. Use "$parms->pool" instead.
287

Unsupported API

289       "Apache2::CmdParms" also provides auto-generated Perl interface for a
290       few other methods which aren't tested at the moment and therefore their
291       API is a subject to change. These methods will be finalized later as a
292       need arises. If you want to rely on any of the following methods please
293       contact the the mod_perl development mailing list so we can help each
294       other take the steps necessary to shift the method to an officially
295       supported API.
296
297       "context"
298
299       Get context containing pointers to modules' per-dir config structures.
300
301         $context = $parms->context;
302
303       obj: $parms ( "Apache2::CmdParms object" )
304       ret: $newval ( "Apache2::ConfVector object" )
305           Returns the commands' per-dir config structures
306
307       since: 2.0.00
308

Copyright

313       mod_perl 2.0 and its core modules are copyrighted under The Apache
314       Software License, Version 2.0.
315

Authors

317       The mod_perl development team and numerous contributors.
318
319
320
321perl v5.8.8                       2006-11-19   docs::api::Apache2::CmdParms(3)