=head1 NAME

Apache::Connection - Perl API for Apache connection object




=head1 Synopsis

  use Apache::Connection ();

META: to be completed




=head1 Description

META: to be completed




=head1 API

C<Apache::Connection> provides the following functions and/or methods:





=head2 C<aborted>

Check whether the connection is still open

  $status = $c->aborted();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$status> (number)

true if the connection has been aborted, false if still open

=back






=head2 C<base_server>

Physical vhost this connection came in on

  $base_server = $c->base_server();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$base_server> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)

=back





=head2 C<bucket_alloc>

META: Autogenerated - needs to be reviewed/completed

The bucket allocator to use for all bucket/brigade creations

  $ba = $c->bucket_alloc();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$ba> (C<L<APR::BucketAlloc|docs::2.0::api::APR::BucketAlloc>>)

=back





=head2 C<conn_config>

META: Autogenerated - needs to be reviewed/completed

Notes on *this* connection

  $ret = $c->conn_config();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$ret> (C<L<Apache::ConfVector|docs::2.0::api::Apache::ConfVector>>)

=back







=head2 C<id>

ID of this connection; unique at any point in time

  $id = $c->id();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back





=head2 C<input_filters>

A list of input filters to be used for this connection

  $input_filters = $c->input_filters();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$input_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

The first filter in the connection input filters chain.

=back





=head2 C<keepalive>

This method answers the question: Should the the connection be kept
alive for another HTTP request after the current request is completed?

  $status = $c->keepalive();
  $status = $c->keepalive($new_status);

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item arg2 opt: C<$new_status> (C<L<:conn_keepalive
constant|docs::2.0::api::Apache::Const/C__conn_keepalive_>>)

Normally you should not mess with setting this option when handling
the HTTP protocol. If you do (for example when sending your own
headers set with
C<L<$r-E<gt>assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_>>)
-- take a look at the ap_set_keepalive() function in
F<httpd-2.0/modules/http/http_protocol.c>.

=item ret: C<$status> (C<L<:conn_keepalive
constant|docs::2.0::api::Apache::Const/C__conn_keepalive_>>)

The method does B<not> return true or false, but one of the states
which can be compared against (C<L<:conn_keepalive
constants|docs::2.0::api::Apache::Const/C__conn_keepalive_>>).

=item since: 1.99_13

=back

Unless you set this value yourself when implementing non-HTTP
protocols, it's only relevant for HTTP requests.

For example:

  use Apache::RequestRec ();
  use Apache::Connection ();
  
  use Apache::Const -compile => qw(:conn_keepalive);
  ...
  my $c = $r->connection;
  if ($c->keepalive == Apache::CONN_KEEPALIVE) {
      # do something
  }
  elsif ($c->keepalive == Apache::CONN_CLOSE) {
      # do something else
  }
  elsif ($c->keepalive == Apache::CONN_UNKNOWN) {
      # do yet something else
  }
  else {
      # die "unknown state";
  }

Notice that new states could be added later by Apache, so your code
should make no assumptions and do things only if the desired state
matches.




=head2 C<keepalives>

How many requests were already served over the current connection.

  $served = $c->keepalives();
  $served = $c->keepalives($new_served);

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item arg1 opt: C<$new_served> (integer)

Set the number of served requests over the current
connection. Normally you won't do that when handling HTTP
requests. (But see below a note regarding
C<L<$r-E<gt>assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_>>).

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

How many requests were already served over the current connection.

In most handlers, but HTTP output filter handlers, that value doesn't
count the current request. For the latter it'll count the current
request.

=item since: 1.99_13

=back

This method is only relevant for L<keepalive|/C_keepalive_>
connections. The core connection output filter
C<ap_http_header_filter> increments this value when the response
headers are sent and it decides that the connection should not be
closed (see C<ap_set_keepalive()>).

If you send your own set of HTTP headers with
C<L<$r-E<gt>assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_>>,
which includes the C<Keep-Alive> HTTP response header, you must make
sure to increment the C<keepalives> counter.





=head2 C<local_addr>

Get this connection's local socket address

  $sa = $c->local_addr();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$sa> (C<L<APR::SockAddr|docs::2.0::api::APR::SockAddr>>)

=back





=head2 C<local_host>

used for ap_get_server_name when UseCanonicalName is set to DNS
(ignores setting of HostnameLookups)

  $local_host = $c->local_host();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back







=head2 C<local_ip>

server IP address

  $local_ip = $c->local_ip();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back




=head2 C<notes>

META: Autogenerated - needs to be reviewed/completed

send note from one module to another, must remain valid for all
requests on this conn

  $c->notes($notes);
  $notes = $c->notes();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item arg2: C<$notes> (C<L<APR::Table|docs::2.0::api::APR::Table>>)

=item ret:

=back





=head2 C<output_filters>

META: Autogenerated - needs to be reviewed/completed

A list of output filters to be used for this connection

  $output_filters = $c->output_filters();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$output_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

The first filter in the connection output filters chain.

=back




=head2 C<pool>

Pool associated with this connection

  $p = $c->pool();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)

=back







=head2 C<remote_addr>

Get this connection's remote socket address

  $sa = $c->remote_addr();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$sa> (C<L<APR::SockAddr|docs::2.0::api::APR::SockAddr>>)

=back





=head2 C<remote_ip>

Client's IP address

  $remote_ip = $c->remote_ip();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back





=head2 C<remote_host>

Client's DNS name, if known.  NULL if DNS hasn't been checked, "" if
it has and no address was found.  N.B. Only access this though
get_remote_host()

  $remote_host = $c->remote_host();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back





=head2 C<remote_logname>

Only ever set if doing rfc1413 lookups.  N.B. Only access this through
get_remote_logname()

  $remote_logname = $c->remote_logname();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

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

=back





=head2 C<sbh>

META: Autogenerated - needs to be reviewed/completed

handle to scoreboard information for this connection

  $sbh = $c->sbh();

=over 4

=item arg1: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=item ret: C<$sbh> (XXX)

=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 1.1.




=head1 Authors

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

=cut

