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