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{See also}
  40
  41 \helpref{wxURL}{wxurl}
  42
  43 \latexignore{\rtfignore{\wxheading{Members}}}
  44
  45 \membersection{Obtaining individual components}\label{obtainingwxuricomponents}
  46
  47 To obtain individual components you can use
  48 one 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
  58 However, you should check HasXXX before
  59 calling a get method, which determines whether or not the component referred
  60 to by the method is defined according to RFC 2396.
  61
  62 Consider an undefined component equivalent to a
  63 NULL 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
  73 Example:
  74 \begin{verbatim}
  75 //protocol will hold the http protocol (i.e. "http")
  76 wxString protocol;
  77 wxURI myuri(wxT("http://mysite.com"));
  78 if(myuri.HasScheme())
  79    protocol = myuri.GetScheme();
  80 \end{verbatim}
  81
  82 \membersection{Deviations from the RFC}\label{deviationsfromrfc}
  83
  84 Note that on URIs with a "file" scheme wxURI does not
  85 parse the userinfo, server, or port portion.  This is to keep
  86 compatability with wxFileSystem, the old wxURL, and older url specifications.
  87
  88 \membersection{wxURI::wxURI}\label{wxuriwxuri}
  89
  90 \func{}{wxURI}{\void}
  91
  92 Creates an empty URI.
  93
  94 \func{}{wxURI}{\param{const wxChar* }{uri}}
  95
  96 Constructor for quick creation.
  97
  98 \docparam{uri}{string to initialize with}
  99
 100 \func{}{wxURI}{\param{const wxURI\& }{uri}}
 101
 102 Copies 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
 111 Builds the URI from its individual components and adds proper separators.
 112
 113 If the URI is not a reference or is not resolved,
 114 the URI that is returned from Get is the same one
 115 passed to Create.
 116
 117
 118 \membersection{wxURI::BuildUnescapedURI}\label{wxuribuildunescapeduri}
 119
 120 \constfunc{wxString}{BuildUnescapedURI}{\void}
 121
 122 Builds the URI from its individual components, adds proper separators, and
 123 returns escape sequences to normal characters.
 124
 125 Note 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
 133 Creates this URI from the string \arg{uri}.
 134
 135 Returns the position at which parsing stopped (there
 136 is 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
 145 Obtains the fragment of this URI.
 146
 147 The fragment of a URI is the last value of the URI,
 148 and is the value after a '#' character after the path
 149 of 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
 157 Obtains the host type of this URI, which is of type
 158 wxURI::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
 173 Returns the password part of the userinfo component of
 174 this URI.  Note that this is explicitly depreciated by
 175 RFC 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
 184 Returns the (normalized) path of the URI.
 185
 186 The path component of a URI comes
 187 directly after the scheme component
 188 if followed by zero or one slashes ('/'),
 189 or after the server/port component.
 190
 191 Absolute paths include the leading '/'
 192 character.
 193
 194 \tt{http://mysite.com<path>}
 195
 196 \membersection{wxURI::GetPort}\label{wxurigetport}
 197
 198 \constfunc{const wxString&}{GetPort}{\void}
 199
 200 Returns a string representation of the URI's port.
 201
 202 The Port of a URI is a value after the server, and
 203 must come after a colon (:).
 204
 205 \tt{http://mysite.com:<port>}
 206
 207 Note that you can easily get the numeric value of the port
 208 by using wxAtoi or wxString::Format.
 209
 210 \membersection{wxURI::GetQuery}\label{wxurigetquery}
 211
 212 \constfunc{const wxString&}{GetQuery}{\void}
 213
 214 Returns the Query component of the URI.
 215
 216 The query component is what is commonly passed to a
 217 cgi application, and must come after the path component,
 218 and 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
 227 Returns the Scheme component of the URI.
 228
 229 The 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
 238 Returns the Server component of the URI.
 239
 240 The server of the uri can be a server name or
 241 a type of ip address.  See
 242 \helpref{GetHostType}{wxurigethosttype} for the
 243 possible values for the host type of the
 244 server component.
 245
 246 \tt{http://<server>/mypath}
 247
 248
 249 \membersection{wxURI::GetUser}\label{wxurigetuser}
 250
 251 \constfunc{const wxString&}{GetUser}{\void}
 252
 253 Returns the username part of the userinfo component of
 254 this URI.  Note that this is explicitly depreciated by
 255 RFC 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
 264 Returns the UserInfo component of the URI.
 265
 266 The component of a URI before the server component
 267 that 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
 276 Returns \true if the Fragment component of the URI exists.
 277
 278
 279 \membersection{wxURI::HasPath}\label{wxurihaspath}
 280
 281 \constfunc{bool}{HasPath}{\void}
 282
 283 Returns \true if the Path component of the URI exists.
 284
 285
 286 \membersection{wxURI::HasPort}\label{wxurihasport}
 287
 288 \constfunc{bool}{HasPort}{\void}
 289
 290 Returns \true if the Port component of the URI exists.
 291
 292
 293 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 294
 295 \constfunc{bool}{HasQuery}{\void}
 296
 297 Returns \true if the Query component of the URI exists.
 298
 299
 300 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 301
 302 \constfunc{bool}{HasScheme}{\void}
 303
 304 Returns \true if the Scheme component of the URI exists.
 305
 306
 307 \membersection{wxURI::HasServer}\label{wxurihasserver}
 308
 309 \constfunc{bool}{HasServer}{\void}
 310
 311 Returns \true if the Server component of the URI exists.
 312
 313
 314 \membersection{wxURI::HasUser}\label{wxurihasuserinfo}
 315
 316 \constfunc{bool}{HasUser}{\void}
 317
 318 Returns \true if the User component of the URI exists.
 319
 320
 321 \membersection{wxURI::IsReference}\label{wxuriisreference}
 322
 323 \constfunc{bool}{IsReference}{\void}
 324
 325 Returns \true if a valid [absolute] URI, otherwise this URI
 326 is a URI reference and not a full URI, and IsReference
 327 returns \false.
 328
 329
 330 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 331
 332 \func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
 333
 334 Compares this URI to another URI, and returns \true if
 335 this 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
 344 Inherits this URI from a base URI - components that do not
 345 exist in this URI are copied from the base, and if this URI's
 346 path is not an absolute path (prefixed by a '/'), then this URI's
 347 path is merged with the base's path.
 348
 349 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 350 results in the scheme (http) and server (mysite.com) being copied into
 351 this URI, since they do not exist.  In addition, since the path
 352 of this URI is not absolute (does not begin with '/'), the path
 353 of 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
 358 mode some compatibility layers are enabled to allow loopholes from RFCs prior
 359 to 2396}
 360
 361 \membersection{wxURI::Unescape}\label{wxuriunescape}
 362
 363 \func{wxString}{Unescape}{\param{const wxString\& }{uri}}
 364
 365 Translates all escape sequences (% hex hex) of \arg{uri} into
 366 normal characters and returns the result.
 367
 368 This is the preferred over deprecated wxURL::ConvertFromURI.
 369
 370 If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead,
 371 as it performs some optimizations over this method.
 372
 373 \docparam{uri}{string with escaped characters to convert}
 374
 375