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

Unsupported API

401       "Apache2::Connection" also provides auto-generated Perl interface for a
402       few other methods which aren't tested at the moment and therefore their
403       API is a subject to change. These methods will be finalized later as a
404       need arises. If you want to rely on any of the following methods please
405       contact the the mod_perl development mailing list so we can help each
406       other take the steps necessary to shift the method to an officially
407       supported API.
408
409   "conn_config"
410       Config vector containing pointers to connections per-server config
411       structures
412
413         $ret = $c->conn_config();
414
415       obj: $c ( "Apache2::Connection object" )
416       ret: $ret ( "Apache2::ConfVector object" )
417       since: 2.0.00
418
419   "sbh"
420       META: Autogenerated - needs to be reviewed/completed
421
422       handle to scoreboard information for this connection
423
424         $sbh = $c->sbh();
425
426       obj: $c ( "Apache2::Connection object" )
427       ret: $sbh (XXX)
428       since: 2.0.00
429
430       META: Not sure how this can be used from mod_perl at the moment. Unless
431       "Apache2::Scoreboard" is extended to provide a hook to read from this
432       variable.
433

Copyright

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

Authors

442       The mod_perl development team and numerous contributors.
443
444
445
446perl v5.36.0                      2023-01-19 docs::api::Apache2::Connection(3)