Apache2::Connection - Perl API for Apache connection object

  use Apache2::Connection ();

  # is connection still open?
  $status = $c->aborted;

  # base server
  $base_server = $c->base_server();

  # needed for creating buckets/brigades
  $ba = $c->bucket_alloc();

  # client's socket
  $socket = $c->client_socket;

  # unique connection id
  $id = $c->id();

  # connection filters stack
  $input_filters = $c->input_filters();
  $output_filters = $c->output_filters();

  # keep the connection alive?
  $status = $c->keepalive();

  # how many requests served over the current connection
  $served = $c->keepalives();

  # this connection's local and remote socket addresses
  $local_sa  = $c->local_addr();
  $remote_sa = $c->remote_addr();

  # local and remote hostnames
  $local_host = $c->local_host();
  $remote_host = $c->get_remote_host();
  $remote_host = $c->remote_host();

  # server and remote client's IP addresses
  $local_ip = $c->local_ip();
  $remote_ip = $c->remote_ip();

  # connection level Apache notes
  $notes = $c->notes();

  # this connection's pool
  $p = $c->pool();

CWApache2::RequestRec provides the Perl API for Apache connection record object.

CWApache2::Connection provides the following functions and/or methods: Check whether the connection is still open

  $status = $c->aborted();

since: 2.0.00

Physical server this connection came in on (main server or vhost):

  $base_server = $c->base_server();

since: 2.0.00

The bucket allocator to use for all bucket/brigade creations

  $ba = $c->bucket_alloc();

since: 2.0.00

This object is needed by CWAPR::Bucket and CWAPR::Brigade methods/functions. Get/set the client socket

  $socket      = $c->client_socket;
  $prev_socket = $c->client_socket($new_socket);

since: 2.0.00

Lookup the client's DNS hostname or IP address

  $remote_host = $c->remote_host();
  $remote_host = $c->remote_host($type);
  $remote_host = $c->remote_host($type, $dir_config);

since: 2.0.00

The result of CWget_remote_host call is cached in CW$c->remote_host. If the latter is set, CWget_remote_host will return that value immediately, w/o doing any checkups. ID of this connection; unique at any point in time

  $id = $c->id();

since: 2.0.00

Get/set the first filter in a linked list of protocol level input filters:

  $input_filters      = $c->input_filters();
  $prev_input_filters = $c->input_filters($new_input_filters);

since: 2.0.00

For an example see: Bucket Brigades-based Protocol Module 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);

since: 2.0.00

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

For example:

  use Apache2::RequestRec ();
  use Apache2::Connection ();

  use Apache2::Const -compile => qw(:conn_keepalive);
  ...
  my $c = $r->connection;
  if ($c->keepalive == Apache2::Const::CONN_KEEPALIVE) {
      # do something
  }
  elsif ($c->keepalive == Apache2::Const::CONN_CLOSE) {
      # do something else
  }
  elsif ($c->keepalive == Apache2::Const::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. How many requests were already served over the current connection.

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

since: 2.0.00

This method is only relevant for keepalive connections. The core connection output filter CWap_http_header_filter increments this value when the response headers are sent and it decides that the connection should not be closed (see CWap_set_keepalive()).

If you send your own set of HTTP headers with CW$r->assbackwards, which includes the CWKeep-Alive HTTP response header, you must make sure to increment the CWkeepalives counter. Get this connection's local socket address

  $local_sa = $c->local_addr();

since: 2.0.00

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

  $local_host = $c->local_host();

since: 2.0.00

META: you probably shouldn't use this method, but ( CWget_server_name ) if inside request and CW$r is available. server IP address

  $local_ip = $c->local_ip();

since: 2.0.00

Get/set text notes for the duration of this connection. These notes can be passed from one module to another (not only mod_perl, but modules in any other language):

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

since: 2.0.00

Also see CW$r->notes Get the first filter in a linked list of protocol level output filters:

  $output_filters = $c->output_filters();
  $prev_output_filters = $r->output_filters($new_output_filters);

since: 2.0.00

For an example see: Bucket Brigades-based Protocol Module Pool associated with this connection

  $p = $c->pool();

since: 2.0.00

Get this connection's remote socket address

  $remote_sa = $c->remote_addr();

since: 2.0.00

Client's IP address

  $remote_ip      = $c->remote_ip();
  $prev_remote_ip = $c->remote_ip($new_remote_ip);

since: 2.0.00

Client's DNS name:

  $remote_host = $c->remote_host();

since: 2.0.00

It's best to to call CW$c->get_remote_host instead of directly accessing this variable.

CWApache2::Connection 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. Config vector containing pointers to connections per-server config structures

  $ret = $c->conn_config();

since: 2.0.00

META: Autogenerated - needs to be reviewed/completed

handle to scoreboard information for this connection

  $sbh = $c->sbh();

since: 2.0.00

META: Not sure how this can be used from mod_perl at the moment. Unless CWApache2::Scoreboard is extended to provide a hook to read from this variable.

mod_perl 2.0 documentation.

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

The mod_perl development team and numerous contributors.