Apache2::Connection(3pm)

1docs::api::Apache2::ConUnseecrtiCoonn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::Connection(3)
2
3
4

NAME

6       Apache2::Connection - Perl API for Apache connection object
7

Synopsis

9         use Apache2::Connection ();
10         use Apache2::RequestRec ();
11
12         my $c = $r->connection;
13
14         my $c = $r->connection;
15         # is connection still open?
16         $status = $c->aborted;
17
18         # base server
19         $base_server = $c->base_server();
20
21         # needed for creating buckets/brigades
22         $ba = $c->bucket_alloc();
23
24         # client's socket
25         $socket = $c->client_socket;
26
27         # unique connection id
28         $id = $c->id();
29
30         # connection filters stack
31         $input_filters = $c->input_filters();
32         $output_filters = $c->output_filters();
33
34         # keep the connection alive?
35         $status = $c->keepalive();
36
37         # how many requests served over the current connection
38         $served = $c->keepalives();
39
40         # this connection's local and remote socket addresses
41         $local_sa  = $c->local_addr();
42         $remote_sa = $c->remote_addr();
43
44         # local and remote hostnames
45         $local_host = $c->local_host();
46         $remote_host = $c->get_remote_host();
47         $remote_host = $c->remote_host();
48
49         # server and remote client's IP addresses
50         $local_ip = $c->local_ip();
51         $remote_ip = $c->remote_ip();
52
53         # connection level Apache notes
54         $notes = $c->notes();
55
56         # this connection's pool
57         $p = $c->pool();
58

Description

60       "Apache2::RequestRec" provides the Perl API for Apache connection
61       record object.
62

API

64       "Apache2::Connection" provides the following functions and/or methods:
65
66       "aborted"
67
68       Check whether the connection is still open
69
70         $status = $c->aborted();
71
72       obj: $c ( "Apache2::Connection object" )
73       ret: $status ( boolean )
74           true if the connection has been aborted, false if still open
75
76       since: 2.0.00
77
78       "base_server"
79
80       Physical server this connection came in on (main server or vhost):
81
82         $base_server = $c->base_server();
83
84       obj: $c ( "Apache2::Connection object" )
85       ret: $base_server ( "Apache2::Server object" )
86       since: 2.0.00
87
88       "bucket_alloc"
89
90       The bucket allocator to use for all bucket/brigade creations
91
92         $ba = $c->bucket_alloc();
93
94       obj: $c ( "Apache2::Connection object" )
95       ret: $ba ( "APR::BucketAlloc object" )
96       since: 2.0.00
97
98       This object is needed by "APR::Bucket" and "APR::Brigade" methods/func‐
99       tions.
100
101       "client_socket"
102
103       Get/set the client socket
104
105         $socket      = $c->client_socket;
106         $prev_socket = $c->client_socket($new_socket);
107
108       obj: $c ( "Apache2::Connection object" )
109       opt arg1: $new_socket ( "APR::Socket object" object )
110           If passed a new socket will be set.
111
112       ret: $socket ( "APR::Socket object" object )
113           current client socket
114
115           if the optional argument $new_socket was passed the previous socket
116           object is returned.
117
118       since: 2.0.00
119
120       "get_remote_host"
121
122       Lookup the client's DNS hostname or IP address
123
124         $remote_host = $c->remote_host();
125         $remote_host = $c->remote_host($type);
126         $remote_host = $c->remote_host($type, $dir_config);
127
128       obj: $c ( "Apache2::Connection object" )
129           The current connection
130
131       opt arg1: $type ( ":remotehost constant" )
132           The type of lookup to perform:
133
134           "Apache2::Const::REMOTE_DOUBLE_REV"
135               will always force a DNS lookup, and also force a double reverse
136               lookup, regardless of the "HostnameLookups" setting.  The
137               result is the (double reverse checked) hostname, or undef if
138               any of the lookups fail.
139
140           "Apache2::Const::REMOTE_HOST"
141               returns the hostname, or "undef" if the hostname lookup fails.
142               It will force a DNS lookup according to the "HostnameLookups"
143               setting.
144
145           "Apache2::Const::REMOTE_NAME"
146               returns the hostname, or the dotted quad if the hostname lookup
147               fails.  It will force a DNS lookup according to the "Host‐
148               nameLookups" setting.
149
150           "Apache2::Const::REMOTE_NOLOOKUP"
151               is like "Apache2::Const::REMOTE_NAME" except that a DNS lookup
152               is never forced.
153
154           Default value is "Apache2::Const::REMOTE_NAME".
155
156       opt arg2: $dir_config ( "Apache2::ConfVector object" )
157           The directory config vector from the request. It's needed to find
158           the container in which the directive "HostnameLookups" is set. To
159           get one for the current request use "$r->per_dir_config".
160
161           By default, "undef" is passed, in which case it's the same as if
162           "HostnameLookups" was set to "Off".
163
164       ret: $remote_host ( string/undef )
165           The remote hostname.  If the configuration directive Host‐
166           NameLookups is set to off, this returns the dotted decimal repre‐
167           sentation of the client's IP address instead. Might return "undef"
168           if the hostname is not known.
169
170       since: 2.0.00
171
172       The result of "get_remote_host" call is cached in "$c->remote_host". If
173       the latter is set, "get_remote_host" will return that value immedi‐
174       ately, w/o doing any checkups.
175
176       "id"
177
178       ID of this connection; unique at any point in time
179
180         $id = $c->id();
181
182       obj: $c ( "Apache2::Connection object" )
183       ret: $id (integer)
184       since: 2.0.00
185
186       "input_filters"
187
188       Get/set the first filter in a linked list of protocol level input fil‐
189       ters:
190
191         $input_filters      = $c->input_filters();
192         $prev_input_filters = $c->input_filters($new_input_filters);
193
194       obj: $c ( "Apache2::Connection object" )
195       opt arg1: $new_input_filters
196           Set a new value
197
198       ret: $input_filters ( "Apache2::Filter object" )
199           The first filter in the connection input filters chain.
200
201           If $new_input_filters was passed, returns the previous value.
202
203       since: 2.0.00
204
205       For an example see: Bucket Brigades-based Protocol Module
206
207       "keepalive"
208
209       This method answers the question: Should the the connection be kept
210       alive for another HTTP request after the current request is completed?
211
212         $status = $c->keepalive();
213         $status = $c->keepalive($new_status);
214
215       obj: $c ( "Apache2::Connection object" )
216       opt arg1: $new_status ( ":conn_keepalive constant" )
217           Normally you should not mess with setting this option when handling
218           the HTTP protocol. If you do (for example when sending your own
219           headers set with "$r->assbackwards") -- take a look at the
220           ap_set_keepalive() function in httpd-2.0/modules/http/http_proto‐
221           col.c.
222
223       ret: $status ( ":conn_keepalive constant" )
224           The method does not return true or false, but one of the states
225           which can be compared against (":conn_keepalive constants").
226
227       since: 2.0.00
228
229       Unless you set this value yourself when implementing non-HTTP proto‐
230       cols, it's only relevant for HTTP requests.
231
232       For example:
233
234         use Apache2::RequestRec ();
235         use Apache2::Connection ();
236
237         use Apache2::Const -compile => qw(:conn_keepalive);
238         ...
239         my $c = $r->connection;
240         if ($c->keepalive == Apache2::Const::CONN_KEEPALIVE) {
241             # do something
242         }
243         elsif ($c->keepalive == Apache2::Const::CONN_CLOSE) {
244             # do something else
245         }
246         elsif ($c->keepalive == Apache2::Const::CONN_UNKNOWN) {
247             # do yet something else
248         }
249         else {
250             # die "unknown state";
251         }
252
253       Notice that new states could be added later by Apache, so your code
254       should make no assumptions and do things only if the desired state
255       matches.
256
257       "keepalives"
258
259       How many requests were already served over the current connection.
260
261         $served = $c->keepalives();
262         $served = $c->keepalives($new_served);
263
264       obj: $c ( "Apache2::Connection object" )
265       opt arg1: $new_served (integer)
266           Set the number of served requests over the current connection. Nor‐
267           mally you won't do that when handling HTTP requests. (But see below
268           a note regarding "$r->assbackwards").
269
270       ret: $served (integer)
271           How many requests were already served over the current connection.
272
273           In most handlers, but HTTP output filter handlers, that value
274           doesn't count the current request. For the latter it'll count the
275           current request.
276
277       since: 2.0.00
278
279       This method is only relevant for keepalive connections. The core con‐
280       nection output filter "ap_http_header_filter" increments this value
281       when the response headers are sent and it decides that the connection
282       should not be closed (see "ap_set_keepalive()").
283
284       If you send your own set of HTTP headers with "$r->assbackwards", which
285       includes the "Keep-Alive" HTTP response header, you must make sure to
286       increment the "keepalives" counter.
287
288       "local_addr"
289
290       Get this connection's local socket address
291
292         $local_sa = $c->local_addr();
293
294       obj: $c ( "Apache2::Connection object" )
295       ret: $local_sa ( "APR::SockAddr object" )
296       since: 2.0.00
297
298       "local_host"
299
300       used for ap_get_server_name when UseCanonicalName is set to DNS
301       (ignores setting of HostnameLookups)
302
303         $local_host = $c->local_host();
304
305       obj: $c ( "Apache2::Connection object" )
306       ret: $local_host (string)
307       since: 2.0.00
308
309       META: you probably shouldn't use this method, but ( "get_server_name" )
310       if inside request and $r is available.
311
312       "local_ip"
313
314       server IP address
315
316         $local_ip = $c->local_ip();
317
318       obj: $c ( "Apache2::Connection object" )
319       ret: $local_ip (string)
320       since: 2.0.00
321
322       "notes"
323
324       Get/set text notes for the duration of this connection. These notes can
325       be passed from one module to another (not only mod_perl, but modules in
326       any other language):
327
328         $notes      = $c->notes();
329         $prev_notes = $c->notes($new_notes);
330
331       obj: $c ( "Apache2::Connection object" )
332       opt arg1: $new_notes ( "APR::Table object" )
333       ret: $notes ( "APR::Table object" )
334           the current notes table.
335
336           if the $new_notes argument was passed, returns the previous value.
337
338       since: 2.0.00
339
340       Also see "$r->notes"
341
342       "output_filters"
343
344       Get the first filter in a linked list of protocol level output filters:
345
346         $output_filters = $c->output_filters();
347         $prev_output_filters = $r->output_filters($new_output_filters);
348
349       obj: $c ( "Apache2::Connection object" )
350       opt arg1: $new_output_filters
351           Set a new value
352
353       ret: $output_filters ( "Apache2::Filter object" )
354           The first filter in the connection output filters chain.
355
356           If $new_output_filters was passed, returns the previous value.
357
358       since: 2.0.00
359
360       For an example see: Bucket Brigades-based Protocol Module
361
362       "pool"
363
364       Pool associated with this connection
365
366         $p = $c->pool();
367
368       obj: $c ( "Apache2::Connection object" )
369       ret: $p ( "APR::Pool object" )
370       since: 2.0.00
371
372       "remote_addr"
373
374       Get this connection's remote socket address
375
376         $remote_sa = $c->remote_addr();
377
378       obj: $c ( "Apache2::Connection object" )
379       ret: $remote_sa ( "APR::SockAddr object" )
380       since: 2.0.00
381
382       "remote_ip"
383
384       Client's IP address
385
386         $remote_ip      = $c->remote_ip();
387         $prev_remote_ip = $c->remote_ip($new_remote_ip);
388
389       obj: $c ( "Apache2::Connection object" )
390       opt arg1: $new_remote_ip ( string )
391           If passed a new value will be set
392
393       ret: $remote_ip ( string )
394           current remote ip address
395
396           if the optional argument $new_remote_ip was passed the previous
397           value is returned.
398
399       since: 2.0.00
400
401       "remote_host"
402
403       Client's DNS name:
404
405         $remote_host = $c->remote_host();
406
407       obj: $c ( "Apache2::Connection object" )
408       ret: $remote_host ( string/undef )
409           If "$c->get_remote_host" was run it returns the cached value, which
410           is a client DNS name or "" if it wasn't found. If the check wasn't
411           run -- "undef" is returned.
412
413       since: 2.0.00
414
415       It's best to to call "$c->get_remote_host" instead of directly access‐
416       ing this variable.
417

Unsupported API

419       "Apache2::Connection" also provides auto-generated Perl interface for a
420       few other methods which aren't tested at the moment and therefore their
421       API is a subject to change. These methods will be finalized later as a
422       need arises. If you want to rely on any of the following methods please
423       contact the the mod_perl development mailing list so we can help each
424       other take the steps necessary to shift the method to an officially
425       supported API.
426
427       "conn_config"
428
429       Config vector containing pointers to connections per-server config
430       structures
431
432         $ret = $c->conn_config();
433
434       obj: $c ( "Apache2::Connection object" )
435       ret: $ret ( "Apache2::ConfVector object" )
436       since: 2.0.00
437
438       "sbh"
439
440       META: Autogenerated - needs to be reviewed/completed
441
442       handle to scoreboard information for this connection
443
444         $sbh = $c->sbh();
445
446       obj: $c ( "Apache2::Connection object" )
447       ret: $sbh (XXX)
448       since: 2.0.00
449
450       META: Not sure how this can be used from mod_perl at the moment. Unless
451       "Apache2::Scoreboard" is extended to provide a hook to read from this
452       variable.
453

Copyright

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

Authors

462       The mod_perl development team and numerous contributors.
463
464
465
466perl v5.8.8                       2006-11-19 docs::api::Apache2::Connection(3)