]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: uri.h | |
3 | // Purpose: interface of wxURI | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | Host type of URI returned from wxURI::GetHostType(). | |
11 | */ | |
12 | enum wxURIHostType | |
13 | { | |
14 | wxURI_REGNAME, ///< Host is a normal register name (@c "www.mysite.com"). | |
15 | wxURI_IPV4ADDRESS, ///< Host is a version 4 ip address (@c "192.168.1.100"). | |
16 | wxURI_IPV6ADDRESS, ///< Host is a version 6 ip address (@c "[aa:aa:aa:aa::aa:aa]:5050"). | |
17 | wxURI_IPVFUTURE ///< Host is a future ip address, wxURI is unsure what kind. | |
18 | }; | |
19 | ||
20 | /** | |
21 | @class wxURI | |
22 | ||
23 | wxURI is used to extract information from a URI (Uniform Resource Identifier). | |
24 | ||
25 | For information about URIs, see RFC 3986 (http://www.ietf.org/rfc/rfc3986.txt). | |
26 | ||
27 | In short, a URL is a URI. In other words, URL is a subset of a URI - all | |
28 | acceptable URLs are also acceptable URIs. | |
29 | ||
30 | wxURI automatically escapes invalid characters in a string, so there is no | |
31 | chance of wxURI "failing" on construction/creation. | |
32 | ||
33 | wxURI supports copy construction and standard assignment operators. wxURI | |
34 | can also be inherited from to provide furthur functionality. | |
35 | ||
36 | To obtain individual components you can use one of the GetXXX() methods. | |
37 | However, you should check HasXXX() before calling a get method, which | |
38 | determines whether or not the component referred to by the method is | |
39 | defined according to RFC 2396. Consider an undefined component equivalent | |
40 | to a @NULL C string. | |
41 | ||
42 | Example: | |
43 | @code | |
44 | // protocol will hold the http protocol (i.e. "http") | |
45 | wxString protocol; | |
46 | wxURI myuri("http://mysite.com"); | |
47 | if( myuri.HasScheme() ) | |
48 | protocol = myuri.GetScheme(); | |
49 | @endcode | |
50 | ||
51 | @note On URIs with a "file" scheme wxURI does not parse the userinfo, | |
52 | server, or port portion. This is to keep compatability with | |
53 | wxFileSystem, the old wxURL, and older url specifications. | |
54 | ||
55 | @library{wxbase} | |
56 | @category{net} | |
57 | ||
58 | @see wxURL | |
59 | */ | |
60 | class wxURI : public wxObject | |
61 | { | |
62 | public: | |
63 | /** | |
64 | Creates an empty URI. | |
65 | */ | |
66 | wxURI(); | |
67 | ||
68 | /** | |
69 | Constructor for quick creation. | |
70 | ||
71 | @param uri | |
72 | URI (Uniform Resource Identifier) to initialize with. | |
73 | */ | |
74 | wxURI(const wxString& uri); | |
75 | ||
76 | /** | |
77 | Copies this URI from another URI. | |
78 | ||
79 | @param uri | |
80 | URI (Uniform Resource Identifier) to initialize with. | |
81 | */ | |
82 | wxURI(const wxURI& uri); | |
83 | ||
84 | /** | |
85 | Builds the URI from its individual components and adds proper | |
86 | separators. | |
87 | ||
88 | If the URI is not a reference or is not resolved, the URI that is | |
89 | returned is the same one passed to the constructor or Create(). | |
90 | */ | |
91 | wxString BuildURI() const; | |
92 | ||
93 | /** | |
94 | Builds the URI from its individual components, adds proper separators, | |
95 | and returns escape sequences to normal characters. | |
96 | ||
97 | @note It is preferred to call this over Unescape(BuildURI()) since | |
98 | BuildUnescapedURI() performs some optimizations over the plain | |
99 | method. | |
100 | */ | |
101 | wxString BuildUnescapedURI() const; | |
102 | ||
103 | /** | |
104 | Creates this URI from the @a uri string. | |
105 | ||
106 | Returns @true if this instance was correctly initialized. | |
107 | ||
108 | @param uri | |
109 | String to initialize from. | |
110 | */ | |
111 | bool Create(const wxString& uri); | |
112 | ||
113 | /** | |
114 | Obtains the fragment of this URI. | |
115 | ||
116 | The fragment of a URI is the last value of the URI, and is the value | |
117 | after a "#" character after the path of the URI. | |
118 | ||
119 | @c "http://mysite.com/mypath#<fragment>" | |
120 | */ | |
121 | const wxString& GetFragment() const; | |
122 | ||
123 | /** | |
124 | Obtains the host type of this URI, which is one of wxURIHostType. | |
125 | */ | |
126 | wxURIHostType GetHostType() const; | |
127 | ||
128 | /** | |
129 | Returns the password part of the userinfo component of this URI. Note | |
130 | that this is explicitly depreciated by RFC 1396 and should generally be | |
131 | avoided if possible. | |
132 | ||
133 | @c "http://<user>:<password>@mysite.com/mypath" | |
134 | */ | |
135 | wxString GetPassword() const; | |
136 | ||
137 | /** | |
138 | Returns the (normalized) path of the URI. | |
139 | ||
140 | The path component of a URI comes directly after the scheme component | |
141 | if followed by zero or one slashes ('/'), or after the server/port | |
142 | component. | |
143 | ||
144 | Absolute paths include the leading '/' character. | |
145 | ||
146 | @c "http://mysite.com<path>" | |
147 | */ | |
148 | const wxString& GetPath() const; | |
149 | ||
150 | /** | |
151 | Returns a string representation of the URI's port. | |
152 | ||
153 | The Port of a URI is a value after the server, and must come after a | |
154 | colon (:). | |
155 | ||
156 | @c "http://mysite.com:<port>" | |
157 | ||
158 | @note You can easily get the numeric value of the port by using | |
159 | wxAtoi() or wxString::Format(). | |
160 | */ | |
161 | const wxString& GetPort() const; | |
162 | ||
163 | /** | |
164 | Returns the Query component of the URI. | |
165 | ||
166 | The query component is what is commonly passed to a cgi application, | |
167 | and must come after the path component, and after a '?' character. | |
168 | ||
169 | @c "http://mysite.com/mypath?<query>" | |
170 | */ | |
171 | const wxString& GetQuery() const; | |
172 | ||
173 | /** | |
174 | Returns the Scheme component of the URI. | |
175 | ||
176 | The first part of the URI. | |
177 | ||
178 | @c "<scheme>://mysite.com" | |
179 | */ | |
180 | const wxString& GetScheme() const; | |
181 | ||
182 | /** | |
183 | Returns the Server component of the URI. | |
184 | ||
185 | The server of the URI can be a server name or a type of IP address. See | |
186 | GetHostType() for the possible values for the host type of the server | |
187 | component. | |
188 | ||
189 | @c "http://<server>/mypath" | |
190 | */ | |
191 | const wxString& GetServer() const; | |
192 | ||
193 | /** | |
194 | Returns the username part of the userinfo component of this URI. Note | |
195 | that this is explicitly depreciated by RFC 1396 and should generally be | |
196 | avoided if possible. | |
197 | ||
198 | @c "http://<user>:<password>@mysite.com/mypath" | |
199 | */ | |
200 | wxString GetUser() const; | |
201 | ||
202 | /** | |
203 | Returns the UserInfo component of the URI. | |
204 | ||
205 | The component of a URI before the server component that is postfixed by | |
206 | a '@' character. | |
207 | ||
208 | @c "http://<userinfo>@mysite.com/mypath" | |
209 | */ | |
210 | const wxString& GetUserInfo() const; | |
211 | ||
212 | /** | |
213 | Returns @true if the Fragment component of the URI exists. | |
214 | */ | |
215 | bool HasFragment() const; | |
216 | ||
217 | /** | |
218 | Returns @true if the Path component of the URI exists. | |
219 | */ | |
220 | bool HasPath() const; | |
221 | ||
222 | /** | |
223 | Returns @true if the Port component of the URI exists. | |
224 | */ | |
225 | bool HasPort() const; | |
226 | ||
227 | /** | |
228 | Returns @true if the Query component of the URI exists. | |
229 | */ | |
230 | bool HasQuery() const; | |
231 | ||
232 | /** | |
233 | Returns @true if the Scheme component of the URI exists. | |
234 | */ | |
235 | bool HasScheme() const; | |
236 | ||
237 | /** | |
238 | Returns @true if the Server component of the URI exists. | |
239 | */ | |
240 | bool HasServer() const; | |
241 | ||
242 | /** | |
243 | Returns @true if the User component of the URI exists. | |
244 | */ | |
245 | bool HasUser() const; | |
246 | ||
247 | /** | |
248 | Returns @true if a valid [absolute] URI, otherwise this URI is a URI | |
249 | reference and not a full URI, and this function returns @false. | |
250 | */ | |
251 | bool IsReference() const; | |
252 | ||
253 | /** | |
254 | Inherits this URI from a base URI - components that do not exist in | |
255 | this URI are copied from the base, and if this URI's path is not an | |
256 | absolute path (prefixed by a '/'), then this URI's path is merged with | |
257 | the base's path. | |
258 | ||
259 | For instance, resolving "../mydir" from "http://mysite.com/john/doe" | |
260 | results in the scheme (http) and server ("mysite.com") being copied | |
261 | into this URI, since they do not exist. In addition, since the path of | |
262 | this URI is not absolute (does not begin with '/'), the path of the | |
263 | base's is merged with this URI's path, resulting in the URI | |
264 | "http://mysite.com/john/mydir". | |
265 | ||
266 | @param base | |
267 | Base URI to inherit from. Must be a full URI and not a reference. | |
268 | @param flags | |
269 | Currently either wxURI_STRICT or 0, in non-strict mode some | |
270 | compatibility layers are enabled to allow loopholes from RFCs prior | |
271 | to 2396. | |
272 | */ | |
273 | void Resolve(const wxURI& base, int flags = wxURI_STRICT); | |
274 | ||
275 | /** | |
276 | Translates all escape sequences (normal characters and returns the result. | |
277 | ||
278 | If you want to unescape an entire wxURI, use BuildUnescapedURI() | |
279 | instead, as it performs some optimizations over this method. | |
280 | ||
281 | @param uri | |
282 | String with escaped characters to convert. | |
283 | */ | |
284 | static wxString Unescape(const wxString& uri); | |
285 | ||
286 | /** | |
287 | Compares this URI to another URI, and returns @true if this URI equals | |
288 | @a uricomp, otherwise it returns @false. | |
289 | ||
290 | @param uricomp | |
291 | URI to compare to. | |
292 | */ | |
293 | bool operator==(const wxURI& uricomp) const; | |
294 | }; | |
295 |