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: uri.tex 41263 2006-09-17 10:59:18Z RR $ 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\wxheading{See also} 40 41\helpref{wxURL}{wxurl} 42 43\latexignore{\rtfignore{\wxheading{Members}}} 44 45\membersection{Obtaining individual components}\label{obtainingwxuricomponents} 46 47To obtain individual components you can use 48one of the following methods 49 50\helpref{GetScheme}{wxurigetscheme}\\ 51\helpref{GetUserInfo}{wxurigetuserinfo}\\ 52\helpref{GetServer}{wxurigetserver}\\ 53\helpref{GetPort}{wxurigetport}\\ 54\helpref{GetPath}{wxurigetpath}\\ 55\helpref{GetQuery}{wxurigetquery}\\ 56\helpref{GetFragment}{wxurigetfragment} 57 58However, you should check HasXXX before 59calling a get method, which determines whether or not the component referred 60to by the method is defined according to RFC 2396. 61 62Consider an undefined component equivalent to a 63NULL C string.\\ 64\\ 65\helpref{HasScheme}{wxurihasscheme}\\ 66\helpref{HasUserInfo}{wxurihasuserinfo}\\ 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 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 88\membersection{wxURI::wxURI}\label{wxuriwxuri} 89 90\func{}{wxURI}{\void} 91 92Creates an empty URI. 93 94\func{}{wxURI}{\param{const wxChar* }{uri}} 95 96Constructor for quick creation. 97 98\docparam{uri}{string to initialize with} 99 100\func{}{wxURI}{\param{const wxURI\& }{uri}} 101 102Copies this URI from another URI. 103 104\docparam{uri}{URI (Uniform Resource Identifier) to initialize with} 105 106 107\membersection{wxURI::BuildURI}\label{wxuribuilduri} 108 109\constfunc{wxString}{BuildURI}{\void} 110 111Builds the URI from its individual components and adds proper separators. 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 122Builds the URI from its individual components, adds proper separators, and 123returns escape sequences to normal characters. 124 125Note that it is preferred to call this over Unescape(BuildURI()) since 126\helpref{BuildUnescapedURI}{wxuribuildunescapeduri} performs some optimizations over the plain method. 127 128 129\membersection{wxURI::Create}\label{wxuricreate} 130 131\func{const wxChar*}{Create}{\param{const wxString&}{uri}} 132 133Creates this URI from the string \arg{uri}. 134 135Returns the position at which parsing stopped (there 136is no such thing as an "invalid" wxURI). 137 138\docparam{uri}{string to initialize from} 139 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 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 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 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. 265 266The component of a URI before the server component 267that is postfixed by a '@' character. 268 269\tt{http://<userinfo>@mysite.com/mypath} 270 271 272\membersection{wxURI::HasFragment}\label{wxurihasfragment} 273 274\constfunc{bool}{HasFragment}{\void} 275 276Returns \true if the Fragment component of the URI exists. 277 278 279\membersection{wxURI::HasPath}\label{wxurihaspath} 280 281\constfunc{bool}{HasPath}{\void} 282 283Returns \true if the Path component of the URI exists. 284 285 286\membersection{wxURI::HasPort}\label{wxurihasport} 287 288\constfunc{bool}{HasPort}{\void} 289 290Returns \true if the Port component of the URI exists. 291 292 293\membersection{wxURI::HasQuery}\label{wxurihasquery} 294 295\constfunc{bool}{HasQuery}{\void} 296 297Returns \true if the Query component of the URI exists. 298 299 300\membersection{wxURI::HasScheme}\label{wxurihasscheme} 301 302\constfunc{bool}{HasScheme}{\void} 303 304Returns \true if the Scheme component of the URI exists. 305 306 307\membersection{wxURI::HasServer}\label{wxurihasserver} 308 309\constfunc{bool}{HasServer}{\void} 310 311Returns \true if the Server component of the URI exists. 312 313 314\membersection{wxURI::HasUser}\label{wxurihasuserinfo} 315 316\constfunc{bool}{HasUser}{\void} 317 318Returns \true if the User component of the URI exists. 319 320 321\membersection{wxURI::IsReference}\label{wxuriisreference} 322 323\constfunc{bool}{IsReference}{\void} 324 325Returns \true if a valid [absolute] URI, otherwise this URI 326is a URI reference and not a full URI, and IsReference 327returns \false. 328 329 330\membersection{wxURI::operator ==}\label{wxurioperatorcompare} 331 332\func{void}{operator ==}{\param{const wxURI\& }{uricomp}} 333 334Compares this URI to another URI, and returns \true if 335this URI equals \arg{uricomp}, otherwise it returns \false. 336 337\docparam{uricomp}{URI to compare to} 338 339 340\membersection{wxURI::Resolve}\label{wxuriresolve} 341 342\func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}} 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} 357\docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non-strict 358mode some compatibility layers are enabled to allow loopholes from RFCs prior 359to 2396} 360 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 368This is the preferred over deprecated wxURL::ConvertFromURI. 369 370If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead, 371as it performs some optimizations over this method. 372 373\docparam{uri}{string with escaped characters to convert} 374 375 376