1docs::api::Apache2::URIU(s3e)r Contributed Perl Documentadtoicosn::api::Apache2::URI(3)
2
3
4

NAME

6       Apache2::URI - Perl API for manipulating URIs
7

Synopsis

9         use Apache2::URI ();
10
11         $hostport = $r->construct_server();
12         $hostport = $r->construct_server($hostname);
13         $hostport = $r->construct_server($hostname, $port);
14         $hostport = $r->construct_server($hostname, $port, $pool);
15
16         $url = $r->construct_url();
17         $url = $r->construct_url($rel_uri);
18         $url = $r->construct_url($rel_uri, $pool);
19
20         $parsed_uri = $r->parse_uri($uri);
21
22         $parsed_uri = $r->parsed_uri();
23
24         $url = join '%20', qw(one two three);
25         Apache2::URI::unescape_url($url);
26

Description

28       While "APR::URI" provides a generic API to dissect, adjust and put
29       together any given URI string, "Apache2::URI" provides an API specific
30       to Apache, by taking the information directly from the $r object.
31       Therefore when manipulating the URI of the current HTTP request usually
32       methods from both classes are used.
33

API

35       "Apache2::URI" provides the following functions and methods:
36
37       "construct_server"
38
39       Construct a string made of hostname and port
40
41         $hostport = $r->construct_server();
42         $hostport = $r->construct_server($hostname);
43         $hostport = $r->construct_server($hostname, $port);
44         $hostport = $r->construct_server($hostname, $port, $pool);
45
46       obj: $r ( "Apache2::RequestRec object" )
47           The current request object
48
49       opt arg1: $hostname ( string )
50           The hostname of the server.
51
52           If that argument is not passed, "$r->get_server_name" is used.
53
54       opt arg2: $port ( string )
55           The port the server is running on.
56
57           If that argument is not passed, "$r->get_server_port" is used.
58
59       opt arg3: $pool ( "APR::Pool object" )
60           The pool to allocate the string from.
61
62           If that argument is not passed, "$r->pool" is used.
63
64       ret: $hostport ( string )
65           The server's hostport string
66
67       since: 2.0.00
68
69       Examples:
70
71       ·   Assuming that:
72
73             $r->get_server_name == "localhost";
74             $r->get_server_port == 8001;
75
76           The code:
77
78             $hostport = $r->construct_server();
79
80           returns a string:
81
82             localhost:8001
83
84       ·   The following code sets the values explicitly:
85
86             $hostport = $r->construct_server("my.example.com", 8888);
87
88           and it returns a string:
89
90             my.example.com:8888
91
92       "construct_url"
93
94       Build a fully qualified URL from the uri and information in the request
95       rec:
96
97         $url = $r->construct_url();
98         $url = $r->construct_url($rel_uri);
99         $url = $r->construct_url($rel_uri, $pool);
100
101       obj: $r ( "Apache2::RequestRec object" )
102           The current request object
103
104       opt arg1: $rel_uri ( string )
105           The path to the requested file (it may include a concatenation of
106           path, query and fragment components).
107
108           If that argument is not passed, "$r->uri" is used.
109
110       opt arg2: $pool ( "APR::Pool object" )
111           The pool to allocate the URL from
112
113           If that argument is not passed, "$r->pool" is used.
114
115       ret: $url ( string )
116           A fully qualified URL
117
118       since: 2.0.00
119
120       Examples:
121
122       ·   Assuming that the request was
123
124             http://localhost.localdomain:8529/test?args
125
126           The code:
127
128             my $url = $r->construct_url;
129
130           returns the string:
131
132             http://localhost.localdomain:8529/test
133
134           notice that the query (args) component is not in the string. You
135           need to append it manually if it's needed.
136
137       ·   Assuming that the request was
138
139             http://localhost.localdomain:8529/test?args
140
141           The code:
142
143             my $rel_uri = "/foo/bar?tar";
144             my $url = $r->construct_url($rel_uri);
145
146           returns the string:
147
148             http://localhost.localdomain:8529/foo/bar?tar
149
150       "parse_uri"
151
152       Break apart URI (affecting the current request's uri components)
153
154         $r->parse_uri($uri);
155
156       obj: $r ( "Apache2::RequestRec object" )
157           The current request object
158
159       arg1: $uri ( string )
160           The uri to break apart
161
162       ret: no return value
163       warning:
164           This method has several side-effects explained below
165
166       since: 2.0.00
167
168       This method call has the following side-effects:
169
170       1   sets "$r->args" to the rest after '?' if such exists in the passed
171           $uri, otherwise sets it to "undef".
172
173       2   sets "$r->uri" to the passed $uri without the "$r->args" part.
174
175       3   sets "$r->hostname" (if not set already) using the
176           ("scheme://host:port") parts of the passed $uri.
177
178       "parsed_uri"
179
180       Get the current request's parsed uri object
181
182         my $uri = $r->parsed_uri();
183
184       obj: $r ( "Apache2::RequestRec object" )
185           The current request object
186
187       ret: $uri ( "APR::URI object" )
188           The parsed uri
189
190       since: 2.0.00
191           This object is suitable for using with "APR::URI::rpath"
192
193       "unescape_url"
194
195       Unescape URLs
196
197         Apache2::URI::unescape_url($url);
198
199       obj: $url ( string )
200           The URL to unescape
201
202       ret: no return value
203           The argument $url is now unescaped
204
205       since: 2.0.00
206
207       Example:
208
209         my $url = join '%20', qw(one two three);
210         Apache2::URI::unescape_url($url);
211
212       $url now contains the string:
213
214         "one two three";
215

See Also

217       "APR::URI", mod_perl 2.0 documentation.
218

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

Authors

224       The mod_perl development team and numerous contributors.
225
226
227
228perl v5.8.8                       2006-11-19        docs::api::Apache2::URI(3)
Impressum