mod_perl logo perl icon
previous page: Apache2::Command - Perl API for accessing Apache module command informationpage up: mod_perl 2.0 APInext page: Apache2::ConnectionUtil - Perl API for Apache connection utils

Apache2::Connection - Perl API for Apache connection object






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
mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford


Table of Contents

Synopsis

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

  my $c = $r->connection;

  my $c = $r->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();


TOP

Description

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



TOP

API

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



TOP

aborted

Check whether the connection is still open

  $status = $c->aborted();


TOP

base_server

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

  $base_server = $c->base_server();


TOP

bucket_alloc

The bucket allocator to use for all bucket/brigade creations

  $ba = $c->bucket_alloc();

This object is needed by APR::Bucket and APR::Brigade methods/functions.



TOP

client_socket

Get/set the client socket

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


TOP

get_remote_host

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);

The result of get_remote_host call is cached in $c->remote_host. If the latter is set, get_remote_host will return that value immediately, w/o doing any checkups.



TOP

id

ID of this connection; unique at any point in time

  $id = $c->id();


TOP

input_filters

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);

For an example see: Bucket Brigades-based Protocol Module



TOP

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);

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.



TOP

keepalives

How many requests were already served over the current connection.

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

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

If you send your own set of HTTP headers with $r->assbackwards, which includes the Keep-Alive HTTP response header, you must make sure to increment the keepalives counter.



TOP

local_addr

Get this connection's local socket address

  $local_sa = $c->local_addr();


TOP

local_host

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

  $local_host = $c->local_host();

META: you probably shouldn't use this method, but ( get_server_name ) if inside request and $r is available.



TOP

local_ip

server IP address

  $local_ip = $c->local_ip();


TOP

notes

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);

Also see $r->notes



TOP

output_filters

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);

For an example see: Bucket Brigades-based Protocol Module



TOP

pool

Pool associated with this connection

  $p = $c->pool();


TOP

remote_addr

Get this connection's remote socket address

  $remote_sa = $c->remote_addr();


TOP

remote_ip

Client's IP address

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


TOP

remote_host

Client's DNS name:

  $remote_host = $c->remote_host();

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



TOP

Unsupported API

Apache2::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.



TOP

conn_config

Config vector containing pointers to connections per-server config structures

  $ret = $c->conn_config();


TOP

sbh

META: Autogenerated - needs to be reviewed/completed

handle to scoreboard information for this connection

  $sbh = $c->sbh();

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



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::Command - Perl API for accessing Apache module command informationpage up: mod_perl 2.0 APInext page: Apache2::ConnectionUtil - Perl API for Apache connection utils