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