1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 %% Author: Ryan Norton <wxprojects@comcast.net>
8 %% Copyright: (c) Ryan Norton
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxURI
}}\label{wxuri
}
14 wxURI is used to extract information from
15 a URI (Uniform Resource Identifier).
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
}.
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.
25 wxURI supports copy construction and standard assignment
26 operators. wxURI can also be inherited from to provide
27 furthur functionality.
29 \wxheading{Derived from
}
33 \wxheading{Include files
}
37 \latexignore{\rtfignore{\wxheading{Members
}}}
39 \membersection{Obtaining individual components
}
41 To obtain individual components you can use
42 one of the following methods:
44 \helpref{GetScheme
}{wxurigetscheme
}\\
45 \helpref{GetUser
}{wxurigetuser
}\\
46 \helpref{GetServer
}{wxurigetserver
}\\
47 \helpref{GetPort
}{wxurigetserver
}\\
48 \helpref{GetPath
}{wxurigetpath
}\\
49 \helpref{GetQuery
}{wxurigetquery
}\\
50 \helpref{GetFragment
}{wxurigetfragment
}
52 However, you should check HasXXX before
53 calling a get method:\\
55 \helpref{HasScheme
}{wxurihasscheme
}\\
56 \helpref{HasUser
}{wxurihasuser
}\\
57 \helpref{HasServer
}{wxurihasserver
}\\
58 \helpref{HasPort
}{wxurihasserver
}\\
59 \helpref{HasPath
}{wxurihaspath
}\\
60 \helpref{HasQuery
}{wxurihasquery
}\\
61 \helpref{HasFragment
}{wxurihasfragment
}
65 //protocol will hold the http protocol (i.e. "http")
67 wxURI myuri(wxT("http://mysite.com"));
69 protocol = myuri.GetScheme();
72 \membersection{wxURI::wxURI
}\label{wxuriwxuri
}
78 \func{}{wxURI
}{\param{const wxChar*
}{uri
}}
80 Constructor for quick creation.
82 \docparam{uri
}{string to initialize with
}
84 \func{}{wxURI
}{\param{const wxURI\&
}{uri
}}
86 Copies this URI from another URI.
88 \docparam{uri
}{URI (Uniform Resource Identifier) to initialize with
}
91 \membersection{wxURI::Create
}\label{wxuricreate
}
93 \func{void
}{Create
}{\param{const wxChar*
}{uri
}}
95 Creates this URI from the string
{\tt uri
}.
97 \docparam{uri
}{string to initialize from
}
99 \membersection{wxURI::Get
}\label{wxuriget
}
101 \constfunc{wxString
}{Get
}{\void}
103 Obtains the full URI.
105 If the URI is not a reference or is not resolved,
106 the URI that is returned from Get is the same one
109 \membersection{wxURI::GetFragment
}\label{wxurigetfragment
}
111 \constfunc{const wxString&
}{GetFragment
}{\void}
113 Obtains the fragment of this URI.
115 The fragment of a URI is the last value of the URI,
116 and is the value after a '#' character after the path
119 \tt{http://mysite.com/mypath\#<fragment>
}
121 \membersection{wxURI::GetHostType
}\label{wxurigethosttype
}
123 \constfunc{const HostType\&
}{GetHostType
}{\void}
125 Obtains the host type of this URI, which is of type
129 \begin{twocollist
}\itemsep=
0pt
130 \twocolitem{{\bf wxURI
\_REGNAME}}{Server is a host name, or the Server component itself is undefined.
}
131 \twocolitem{{\bf wxURI
\_IPV4ADDRESS}}{Server is a IP version
4 address (XXX.XXX.XXX.XXX)
}
132 \twocolitem{{\bf wxURI
\_IPV6ADDRESS}}{Server is a IP version
6 address ((XXX:)XXX::(XXX)XXX:XXX
}
133 \twocolitem{{\bf wxURI
\_IPVFUTURE}}{Server is an IP address, but not versions
4 or
6}
136 \membersection{wxURI::GetPath
}\label{wxurigetpath
}
138 \constfunc{const wxString&
}{GetPath
}{\void}
140 Returns the (normalized) path of the URI.
142 The path component of a URI comes
143 directly after the scheme component
144 if followed by zero or one slashes ('/'),
145 or after the server/port component.
147 Absolute paths include the leading '/'
150 \tt{http://mysite.com<path>
}
152 \membersection{wxURI::GetPort
}\label{wxurigetport
}
154 \constfunc{const wxString&
}{GetPort
}{\void}
156 Returns a string representation of the URI's port.
158 The Port of a URI is a value after the server, and
159 must come after a colon (:).
161 \tt{http://mysite.com:<port>
}
163 Note that you can easily get the numeric value of the port
164 by using wxAtoi or wxString::Format.
166 \membersection{wxURI::GetQuery
}\label{wxurigetquery
}
168 \constfunc{const wxString&
}{GetQuery
}{\void}
170 Returns the Query component of the URI.
172 The query component is what is commonly passed to a
173 cgi application, and must come after the path component,
174 and after a '?' character.
176 \tt{http://mysite.com/mypath?<query>
}
179 \membersection{wxURI::GetScheme
}\label{wxurigetscheme
}
181 \constfunc{const wxString&
}{GetScheme
}{\void}
183 Returns the Scheme component of the URI.
185 The first part of the uri.
187 \tt{<scheme>://mysite.com
}
190 \membersection{wxURI::GetServer
}\label{wxurigetserver
}
192 \constfunc{const wxString&
}{GetServer
}{\void}
194 Returns the Server component of the URI.
196 The server of the uri can be a server name or
197 a type of ip address. See
198 \helpref{GetHostType
}{wxurigethosttype
} for the
199 possible values for the host type of the
202 \tt{http://<server>/mypath
}
205 \membersection{wxURI::GetUser
}\label{wxurigetuser
}
207 \constfunc{const wxString&
}{GetUser
}{\void}
209 Returns the User component of the URI.
211 The component of a URI before the server component
212 that is postfixed by a '@' character.
214 \tt{http://<user>@mysite.com/mypath
}
216 \membersection{wxURI::HasFragment
}\label{wxurihasfragment
}
218 \constfunc{bool
}{HasFragment
}{\void}
220 Returns true if the Fragment component of the URI exists.
222 \membersection{wxURI::HasPath
}\label{wxurihaspath
}
224 \constfunc{bool
}{HasPath
}{\void}
226 Returns true if the Path component of the URI exists.
228 \membersection{wxURI::HasPort
}\label{wxurihasport
}
230 \constfunc{bool
}{HasPort
}{\void}
232 Returns true if the Port component of the URI exists.
235 \membersection{wxURI::HasQuery
}\label{wxurihasquery
}
237 \constfunc{bool
}{HasQuery
}{\void}
239 Returns true if the Query component of the URI exists.
242 \membersection{wxURI::HasScheme
}\label{wxurihasscheme
}
244 \constfunc{bool
}{HasScheme
}{\void}
246 Returns true if the Scheme component of the URI exists.
249 \membersection{wxURI::HasServer
}\label{wxurihasserver
}
251 \constfunc{bool
}{HasServer
}{\void}
253 Returns true if the Server component of the URI exists.
256 \membersection{wxURI::HasUser
}\label{wxurihasuser
}
258 \constfunc{bool
}{HasUser
}{\void}
260 Returns true if the User component of the URI exists.
263 \membersection{wxURI::IsReference
}\label{wxuriisreference
}
265 \constfunc{bool
}{IsReference
}{\void}
267 Returns true if a valid
[absolute
] URI, otherwise this URI
268 is a URI reference and not a full URI, and IsReference
272 \membersection{wxURI::operator ==
}\label{wxurioperatorcompare
}
274 \func{void
}{operator ==
}{\param{const wxURI\&
}{uricomp
}}
276 Compares this URI to another URI, and returns true if
277 this URI equals
{\tt uricomp
}, otherwise it returns false.
279 \docparam{uricomp
}{URI to compare to
}
282 \membersection{wxURI::Resolve
}\label{wxuriresolve
}
284 \func{void
}{Resolve
}{\param{const wxURI\&
}{base
},
\param{int
}{flags =
\texttt{wxURI
\_STRICT}}}
286 Inherits this URI from a base URI - components that do not
287 exist in this URI are copied from the base, and if this URI's
288 path is not an absolute path (prefixed by a '/'), then this URI's
289 path is merged with the base's path.
291 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
292 results in the scheme (http) and server (mysite.com) being copied into
293 this URI, since they do not exist. In addition, since the path
294 of this URI is not absolute (does not begin with '/'), the path
295 of the base's is merged with this URI's path, resulting in the URI
296 "http://mysite.com/john/mydir".
298 \docparam{base
}{Base URI to inherit from. Must be a full URI and not a reference
}
299 \docparam{flags
}{Currently either
\texttt{wxURI
\_STRICT} or $
0$, in non strict
300 mode some compatability layers are enabled to allow loopholes from RFCs prior