mod_perl logo perl icon
previous page: Apache2::Access - A Perl API for Apache request object: Access,
Authentication and Authorization.page up: mod_perl 2.0 APInext page: Apache2::Command - Perl API for accessing Apache module command information

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






mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford
Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt
Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes


Table of Contents

Synopsis

  use Apache2::CmdParms ();
  use Apache2::Module ();
  use Apache2::Const -compile => qw(NOT_IN_LOCATION);
  
  my @directives = (
    {
      name => 'MyDirective',
      cmd_data => 'some extra data',
    },
  );
  
  Apache2::Module::add(__PACKAGE__, \@directives);
  
  sub MyDirective {
      my ($self, $parms, $args) = @_;
  
      # push config
      $parms->add_config(['ServerTokens off']);
  
      # this command's command object
      $cmd = $parms->cmd;
  
      # check the current command's context
      $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);
  
      # this command's context
      $context = $parms->context;
  
      # this command's directive object
      $directive = $parms->directive;
  
      # the extra information passed thru cmd_data to
      # Apache2::Module::add()
      $info = $parms->info;
  
      # which methods are <Limit>ed ?
      $is_limited = $parms->method_is_limited('GET');
  
      # which allow-override bits are set
      $override = $parms->override;
  
      # which Options are allowed by AllowOverride (since Apache 2.2)
      $override = $parms->override_opts;
  
      # the path this command is being invoked in
      $path = $parms->path;
  
      # this command's pool
      $p = $parms->pool;
  
      # this command's configuration time pool
      $p = $parms->temp_pool;
  }


TOP

Description

Apache2::CmdParms provides the Perl API for Apache command parameters object.



TOP

API

Apache2::CmdParms provides the following functions and/or methods:



TOP

add_config

Dynamically add Apache configuration at request processing runtime:

  $parms->add_config($lines);

See also: $s->add_config, $r->add_config



TOP

check_cmd_context

Check the current command against a context bitmask of forbidden contexts.

  $error = $parms->check_cmd_context($check);

For example here is how to check whether a command is allowed in the <Location> container:

  use Apache2::Const -compile qw(NOT_IN_LOCATION);
  if (my $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
      die "directive ... not allowed in <Location> context"
  }


TOP

cmd

This module's command information

  $cmd = $parms->cmd();


TOP

directive

This command's directive object in the configuration tree

  $directive = $parms->directive;


TOP

info

The extra information passed through cmd_data in Apache2::Module::add().

  $info = $parms->info;

For example here is how to pass arbitrary information to a directive subroutine:

  my @directives = (
    {
      name => 'MyDirective1',
      func => \&MyDirective,
      cmd_data => 'One',
    },
    {
      name => 'MyDirective2',
      func => \&MyDirective,
      cmd_data => 'Two',
    },
  );
  Apache2::Module::add(__PACKAGE__, \@directives);
  
  sub MyDirective {
    my ($self, $parms, $args) = @_;
    my $info = $parms->info;
  }

In this example $info will either be 'One' or 'Two' depending on whether the directive was called as MyDirective1 or MyDirective2.



TOP

method_is_limited

Discover if a method is <Limit>ed in the current scope

  $is_limited = $parms->method_is_limited($method);

For example, to check if the GET method is being <Limit>ed in the current scope, do:

  if ($parms->method_is_limited('GET') {
      die "...";
  }


TOP

override

Which allow-override bits are set (AllowOverride directive)

  $override = $parms->override;

For example to check that the AllowOverride's AuthConfig and FileInfo options are enabled for this command, do:

  use Apache2::Const -compile qw(:override);
  $wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
  $masked = $parms->override & $wanted;
  unless ($wanted == $masked) {
      die "...";
  }


TOP

override_opts

Which options are allowed to be overridden by .htaccess files. This is set by AllowOverride Options=....

  $override_opts = $parms->override_opts;

Enabling single options was introduced with Apache 2.2. For Apache 2.0 this function simply returns a bitmask with all options allowed.



TOP

path

The current pathname/location/match of the block this command is in

  $path = $parms->path;

For example for a container block:

  <Location /foo>
  ...
  </Location>

'/foo' will be returned.



TOP

pool

Pool associated with this command

  $p = $parms->pool;


TOP

server

The (vhost) server this command was defined in httpd.conf

  $s = $parms->server;


TOP

temp_pool

Pool for scratch memory; persists during configuration, but destroyed before the first request is served.

  $temp_pool = $parms->temp_pool;

Most likely you shouldn't use this pool object, unless you know what you are doing. Use $parms->pool instead.



TOP

Unsupported API

Apache2::CmdParms also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API 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 API.



TOP

context

Get context containing pointers to modules' per-dir config structures.

  $context = $parms->context;


TOP

See Also

mod_perl 2.0 documentation.



TOP

Copyright

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



TOP

Authors

The mod_perl development team and numerous contributors.






TOP
previous page: Apache2::Access - A Perl API for Apache request object: Access,
Authentication and Authorization.page up: mod_perl 2.0 APInext page: Apache2::Command - Perl API for accessing Apache module command information