=head1 NAME

Apache2::Module - Perl API for creating and working with Apache modules




=head1 Synopsis

  use Apache2::Module ();
  
  #Define a configuration directive
  my @directives = (
      {
          name => 'MyDirective',
      }
  );
  
  Apache2::Module::add(__PACKAGE__, \@directives);
  
  # iterate over the whole module list
  for (my $modp = Apache2::Module::top_module(); $modp; $modp = $modp->next) {
      my $name                  = $modp->name;
      my $index                 = $modp->module_index;
      my $ap_api_major_version  = $modp->ap_api_major_version;
      my $ap_api_minor_version  = $modp->ap_api_minor_version;
      my $commands              = $modp->cmds;
  }
  
  # find a specific module
  my $module = Apache2::Module::find_linked_module('mod_ssl.c');
  
  # remove a specific module
  $module->remove_loaded_module();
  
  # access module configuration from a directive
  sub MyDirective {
      my ($self, $parms, $args) = @_;
      my  $srv_cfg = Apache2::Module::get_config($self, $parms->server);
      [...]
  }
  
  # test if an Apache module is loaded
  if (Apache2::Module::loaded('mod_ssl.c')) {
      [...]
  }
  
  # test if a Perl module is loaded
  if (Apache2::Module::loaded('Apache2::Status')) {
      [...]
  }







=head1 Description

C<Apache2::Module> provides the Perl API for creating and working with
Apache modules

See L<Apache Server Configuration Customization in
Perl|docs::2.0::user::config::custom>.





=head1 API

C<Apache2::Module> provides the following functions and/or methods:





=head2 C<add>

Add a module's custom configuration directive to Apache.

  Apache2::Module::add($package, $cmds);

=over 4

=item arg1: C<$package> ( string )

the package of the module to add

=item arg2: C<$cmds> ( ARRAY of HASH refs )

the list of configuration directives to add

=item ret: no return value

=item since: 2.0.00

=back

See also L<Apache Server Configuration Customization in
Perl|docs::2.0::user::config::custom>.







=head2 C<ap_api_major_version>

Get the httpd API version this module was build against, B<not> the
module's version.

  $major_version = $module->ap_api_major_version();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$major_version> ( integer )

=item since: 2.0.00

=back

This methid is used to check that module is compatible with this
version of the server before loading it.






=head2 C<ap_api_minor_version>

Get the module API minor version.

  $minor_version = $module->ap_api_minor_version();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$minor_version> ( integer )

=item since: 2.0.00

=back

C<ap_api_minor_version()> provides API feature milestones.

It's not checked during module init.





=head2 C<cmds>

Get the C<L<Apache2::Command|docs::2.0::api::Apache2::Command>> object,
describing all of the directives this module defines.

  $command = $module->cmds();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$command>
( C<L<Apache2::Command object|docs::2.0::api::Apache2::Command>> )

=item since: 2.0.00

=back







=head2 C<get_config>

Retrieve a module's configuration. Used by configuration directives.

  $cfg = Apache2::Module::get_config($class, $server, $dir_config);
  $cfg = Apache2::Module::get_config($class, $server);
  $cfg =          $self->get_config($server, $dir_config);
  $cfg =          $self->get_config($server);

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item arg1: C<$class> ( string )

The Perl package this configuration is for

=item arg2: C<$server>
( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )

The current server, typically
C<L<$r-E<gt>server|docs::2.0::api::Apache2::ServerUtil>> or
C<L<$parms-E<gt>server|docs::2.0::api::Apache2::CmdParms>>.

=item opt arg3: C<$dir_config>
( C<L<Apache2::ConfVector object|docs::2.0::api::Apache2::RequestRec/C_per_dir_config_>> )

By default, the configuration returned is the server level one. To
retrieve the per directory configuration, use
C<L<$r-E<gt>per_dir_config|docs::2.0::api::Apache2::RequestRec>> as a
last argument.

=item ret: C<$cfg> (HASH reference)

A reference to the hash holding the module configuration data.

=item since: 2.0.00

=back

See also L<Apache Server Configuration Customization in
Perl|docs::2.0::user::config::custom>.






=head2 C<find_linked_module>

Find a module based on the name of the module

  $module = Apache2::Module::find_linked_module($name);

=over 4

=item arg1: C<$name> ( string )

The name of the module ending in C<.c>

=item ret: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

The module object if found, C<undef> otherwise.

=item since: 2.0.00

=back

For example:

  my $module = Apache2::Module::find_linked_module('mod_ssl.c');






=head2 C<loaded>

Determine if a certain module is loaded

  $loaded = Apache2::Module::loaded($module);

=over 4

=item name: C<$module> ( string )

The name of the module to search for.

If C<$module> ends with C<.c>, search all the modules, statically
compiled and dynamically loaded.

If C<$module> ends with C<.so>, search only the dynamically loaded
modules.

If C<$module> doesn't contain a C<.>, search the loaded Perl modules
(checks C<%INC>).

=item ret: C<$loaded> ( boolean )

Returns true if the module is loaded, false otherwise.

=item since: 2.0.00

=back

For example, to test if this server supports ssl:

  if (Apache2::Module::loaded('mod_ssl.c')) {
      [...]
  }

To test is this server dynamically loaded mod_perl:

  if (Apache2::Module::loaded('mod_perl.so')) {
      [...]
  }

To test if C<L<Apache2::Status|docs::2.0::api::Apache2::Status>> is
loaded:

  if (Apache2::Module::loaded('Apache2::Status')) {
      [...]
  }







=head2 C<module_index>

Get the index to this modules structures in config vectors.

  $index = $module->module_index();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$index> ( integer )

=item since: 2.0.00

=back





=head2 C<name>

Get the name of the module's I<.c> file

  $name = $module->name();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$name> ( string )

=item since: 2.0.00

=back

For example a mod_perl module, will return: I<mod_perl.c>.








=head2 C<next>

Get the next module in the list, C<undef> if this is the last module
in the list.

  $next_module = $module->next();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: C<$next_module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item since: 2.0.00

=back








=head2 C<remove_loaded_module>

Remove a module from the list of loaded modules permanently.

  $module->remove_loaded_module();

=over 4

=item obj: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item ret: no return value

=item since: 2.0.00

=back






=head2 C<top_module>

Returns the first module in the module list. Usefull to start a
module iteration.

  $module = Apache2::Module::top_module();

=over 4

=item ret: C<$module>
( C<L<Apache2::Module object|docs::2.0::api::Apache2::Module>> )

=item since: 2.0.00

=back





=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.




=head1 Copyright

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




=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut