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