]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/uri.tex
Removed method which belongs to wxArrayString (and is listed there already) [Bug...
[wxWidgets.git] / docs / latex / wx / uri.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: uri.tex
3 %% Purpose: wxURI docs
4 %% Author: Ryan Norton <wxprojects@comcast.net>
5 %% Modified by:
6 %% Created: 7/7/2004
7 %% RCS-ID: $Id$
8 %% Copyright: (c) Ryan Norton
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxURI}}\label{wxuri}
13
14 wxURI is used to extract information from
15 a URI (Uniform Resource Identifier).
16
17 For information about URIs, see
18 \urlref{RFC 2396}{http://www.ietf.org/rfc/rfc2396.txt} or
19 \urlref{RFC 2396.bis (Updated draft of RFC 2396)}{http://www.gbiv.com/protocols/uri/rev-2002/rfc2396bis.html}.
20
21 In short, a URL \em{is} a URI. In other
22 words, URL is a subset of a URI - all
23 acceptable URLs are also acceptable URIs.
24
25 wxURI automatically escapes invalid characters in a string,
26 so there is no chance of wxURI "failing" on construction/creation.
27
28 wxURI supports copy construction and standard assignment
29 operators. wxURI can also be inherited from to provide
30 furthur functionality.
31
32 \wxheading{Derived from}
33
34 \helpref{wxObject}{wxobject}
35
36 \wxheading{Include files}
37
38 <uri.h>
39
40 \latexignore{\rtfignore{\wxheading{Members}}}
41
42 \membersection{Obtaining individual components}\label{obtainingwxuricomponents}
43
44 To obtain individual components you can use
45 one of the following methods
46
47 \helpref{GetScheme}{wxurigetscheme}\\
48 \helpref{GetUser}{wxurigetuser}\\
49 \helpref{GetServer}{wxurigetserver}\\
50 \helpref{GetPort}{wxurigetserver}\\
51 \helpref{GetPath}{wxurigetpath}\\
52 \helpref{GetQuery}{wxurigetquery}\\
53 \helpref{GetFragment}{wxurigetfragment}
54
55 However, you should check HasXXX before
56 calling a get method, which determines whether or not the component referred
57 to by the method is defined according to RFC 2396.
58
59 Consider an undefined component equivilent to a
60 NULL C string.\\
61 \\
62 \helpref{HasScheme}{wxurihasscheme}\\
63 \helpref{HasUser}{wxurihasuser}\\
64 \helpref{HasServer}{wxurihasserver}\\
65 \helpref{HasPort}{wxurihasserver}\\
66 \helpref{HasPath}{wxurihaspath}\\
67 \helpref{HasQuery}{wxurihasquery}\\
68 \helpref{HasFragment}{wxurihasfragment}
69
70 Example:
71 \begin{verbatim}
72 //protocol will hold the http protocol (i.e. "http")
73 wxString protocol;
74 wxURI myuri(wxT("http://mysite.com"));
75 if(myuri.HasScheme())
76 protocol = myuri.GetScheme();
77 \end{verbatim}
78
79 \membersection{wxURI::wxURI}\label{wxuriwxuri}
80
81 \func{}{wxURI}{\void}
82
83 Creates an empty URI.
84
85 \func{}{wxURI}{\param{const wxChar* }{uri}}
86
87 Constructor for quick creation.
88
89 \docparam{uri}{string to initialize with}
90
91 \func{}{wxURI}{\param{const wxURI\& }{uri}}
92
93 Copies this URI from another URI.
94
95 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
96
97
98 \membersection{wxURI::BuildURI}\label{wxuribuilduri}
99
100 \constfunc{wxString}{BuildURI}{\void}
101
102 Builds the URI from its individual components and adds proper seperators.
103
104 If the URI is not a reference or is not resolved,
105 the URI that is returned from Get is the same one
106 passed to Create.
107
108
109 \membersection{wxURI::BuildUnescapedURI}\label{wxuribuildunescapeduri}
110
111 \constfunc{wxString}{BuildUnescapedURI}{\void}
112
113 Builds the URI from its individual components, adds proper seperators, and
114 returns escape sequences to normal characters.
115
116 Note that it is preferred to call this over Unescape(BuildURI()) since
117 BuildUnescapedURI performs some optimizations over the plain method.
118
119
120 \membersection{wxURI::Create}\label{wxuricreate}
121
122 \func{const wxChar*}{Create}{\param{const wxChar* }{uri}}
123
124 Creates this URI from the string \arg{uri}.
125
126 Returns the position at which parsing stopped (there
127 is no such thing as an "invalid" wxURI).
128
129 \docparam{uri}{string to initialize from}
130
131
132 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
133
134 \constfunc{const wxString&}{GetFragment}{\void}
135
136 Obtains the fragment of this URI.
137
138 The fragment of a URI is the last value of the URI,
139 and is the value after a '#' character after the path
140 of the URI.
141
142 \tt{http://mysite.com/mypath\#<fragment>}
143
144 \membersection{wxURI::GetHostType}\label{wxurigethosttype}
145
146 \constfunc{const HostType\&}{GetHostType}{\void}
147
148 Obtains the host type of this URI, which is of type
149 wxURI::HostType:
150
151 \twocolwidtha{7cm}
152 \begin{twocollist}\itemsep=0pt
153 \twocolitem{{\bf wxURI\_REGNAME}}{Server is a host name, or the Server component itself is undefined.}
154 \twocolitem{{\bf wxURI\_IPV4ADDRESS}}{Server is a IP version 4 address (XXX.XXX.XXX.XXX)}
155 \twocolitem{{\bf wxURI\_IPV6ADDRESS}}{Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX}
156 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
157 \end{twocollist}
158
159 \membersection{wxURI::GetPath}\label{wxurigetpath}
160
161 \constfunc{const wxString&}{GetPath}{\void}
162
163 Returns the (normalized) path of the URI.
164
165 The path component of a URI comes
166 directly after the scheme component
167 if followed by zero or one slashes ('/'),
168 or after the server/port component.
169
170 Absolute paths include the leading '/'
171 character.
172
173 \tt{http://mysite.com<path>}
174
175 \membersection{wxURI::GetPort}\label{wxurigetport}
176
177 \constfunc{const wxString&}{GetPort}{\void}
178
179 Returns a string representation of the URI's port.
180
181 The Port of a URI is a value after the server, and
182 must come after a colon (:).
183
184 \tt{http://mysite.com:<port>}
185
186 Note that you can easily get the numeric value of the port
187 by using wxAtoi or wxString::Format.
188
189 \membersection{wxURI::GetQuery}\label{wxurigetquery}
190
191 \constfunc{const wxString&}{GetQuery}{\void}
192
193 Returns the Query component of the URI.
194
195 The query component is what is commonly passed to a
196 cgi application, and must come after the path component,
197 and after a '?' character.
198
199 \tt{http://mysite.com/mypath?<query>}
200
201
202 \membersection{wxURI::GetScheme}\label{wxurigetscheme}
203
204 \constfunc{const wxString&}{GetScheme}{\void}
205
206 Returns the Scheme component of the URI.
207
208 The first part of the uri.
209
210 \tt{<scheme>://mysite.com}
211
212
213 \membersection{wxURI::GetServer}\label{wxurigetserver}
214
215 \constfunc{const wxString&}{GetServer}{\void}
216
217 Returns the Server component of the URI.
218
219 The server of the uri can be a server name or
220 a type of ip address. See
221 \helpref{GetHostType}{wxurigethosttype} for the
222 possible values for the host type of the
223 server component.
224
225 \tt{http://<server>/mypath}
226
227
228 \membersection{wxURI::GetUser}\label{wxurigetuser}
229
230 \constfunc{const wxString&}{GetUser}{\void}
231
232 Returns the User component of the URI.
233
234 The component of a URI before the server component
235 that is postfixed by a '@' character.
236
237 \tt{http://<user>@mysite.com/mypath}
238
239 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
240
241 \constfunc{bool}{HasFragment}{\void}
242
243 Returns \true if the Fragment component of the URI exists.
244
245 \membersection{wxURI::HasPath}\label{wxurihaspath}
246
247 \constfunc{bool}{HasPath}{\void}
248
249 Returns \true if the Path component of the URI exists.
250
251 \membersection{wxURI::HasPort}\label{wxurihasport}
252
253 \constfunc{bool}{HasPort}{\void}
254
255 Returns \true if the Port component of the URI exists.
256
257
258 \membersection{wxURI::HasQuery}\label{wxurihasquery}
259
260 \constfunc{bool}{HasQuery}{\void}
261
262 Returns \true if the Query component of the URI exists.
263
264
265 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
266
267 \constfunc{bool}{HasScheme}{\void}
268
269 Returns \true if the Scheme component of the URI exists.
270
271
272 \membersection{wxURI::HasServer}\label{wxurihasserver}
273
274 \constfunc{bool}{HasServer}{\void}
275
276 Returns \true if the Server component of the URI exists.
277
278
279 \membersection{wxURI::HasUser}\label{wxurihasuser}
280
281 \constfunc{bool}{HasUser}{\void}
282
283 Returns \true if the User component of the URI exists.
284
285
286 \membersection{wxURI::IsReference}\label{wxuriisreference}
287
288 \constfunc{bool}{IsReference}{\void}
289
290 Returns \true if a valid [absolute] URI, otherwise this URI
291 is a URI reference and not a full URI, and IsReference
292 returns \false.
293
294
295 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
296
297 \func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
298
299 Compares this URI to another URI, and returns \true if
300 this URI equals \arg{uricomp}, otherwise it returns \false.
301
302 \docparam{uricomp}{URI to compare to}
303
304
305 \membersection{wxURI::Resolve}\label{wxuriresolve}
306
307 \func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}}
308
309 Inherits this URI from a base URI - components that do not
310 exist in this URI are copied from the base, and if this URI's
311 path is not an absolute path (prefixed by a '/'), then this URI's
312 path is merged with the base's path.
313
314 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
315 results in the scheme (http) and server (mysite.com) being copied into
316 this URI, since they do not exist. In addition, since the path
317 of this URI is not absolute (does not begin with '/'), the path
318 of the base's is merged with this URI's path, resulting in the URI
319 "http://mysite.com/john/mydir".
320
321 \docparam{base}{Base URI to inherit from. Must be a full URI and not a reference}
322 \docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non strict
323 mode some compatability layers are enabled to allow loopholes from RFCs prior
324 to 2396}
325
326 \membersection{wxURI::Unescape}\label{wxuriunescape}
327
328 \func{wxString}{Unescape}{\param{const wxString\& }{uri}}
329
330 Translates all escape sequences (% hex hex) of \arg{uri} into
331 normal characters and returns the result.
332
333 This is the preferred over wxURL::ConvertFromURI.
334
335 If you want to unescape an entire wxURI, use BuildUnescapedURI instead,
336 as it performs some optimizations over this method.
337
338 \docparam{uri}{string with escaped characters to convert}
339
340