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