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{wxURI::wxURI}\label{wxuriwxuri}
  79
  80 \func{}{wxURI}{\void}
  81
  82 Creates an empty URI.
  83
  84 \func{}{wxURI}{\param{const wxChar* }{uri}}
  85
  86 Constructor for quick creation.
  87
  88 \docparam{uri}{string to initialize with}
  89
  90 \func{}{wxURI}{\param{const wxURI\& }{uri}}
  91
  92 Copies this URI from another URI.
  93
  94 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
  95
  96
  97 \membersection{wxURI::BuildURI}\label{wxuribuilduri}
  98
  99 \constfunc{wxString}{BuildURI}{\void}
 100
 101 Builds the URI from its individual components and adds proper separators.
 102
 103 If the URI is not a reference or is not resolved,
 104 the URI that is returned from Get is the same one
 105 passed to Create.
 106
 107
 108 \membersection{wxURI::BuildUnescapedURI}\label{wxuribuildunescapeduri}
 109
 110 \constfunc{wxString}{BuildUnescapedURI}{\void}
 111
 112 Builds the URI from its individual components, adds proper separators, and
 113 returns escape sequences to normal characters.
 114
 115 Note that it is preferred to call this over Unescape(BuildURI()) since
 116 \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} performs some optimizations over the plain method.
 117
 118
 119 \membersection{wxURI::Create}\label{wxuricreate}
 120
 121 \func{const wxChar*}{Create}{\param{const wxString&}{uri}}
 122
 123 Creates this URI from the string \arg{uri}.
 124
 125 Returns the position at which parsing stopped (there
 126 is no such thing as an "invalid" wxURI).
 127
 128 \docparam{uri}{string to initialize from}
 129
 130
 131 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
 132
 133 \constfunc{const wxString&}{GetFragment}{\void}
 134
 135 Obtains the fragment of this URI.
 136
 137 The fragment of a URI is the last value of the URI,
 138 and is the value after a '#' character after the path
 139 of the URI.
 140
 141 \tt{http://mysite.com/mypath\#<fragment>}
 142
 143 \membersection{wxURI::GetHostType}\label{wxurigethosttype}
 144
 145 \constfunc{const HostType\&}{GetHostType}{\void}
 146
 147 Obtains the host type of this URI, which is of type
 148 wxURI::HostType:
 149
 150 \twocolwidtha{7cm}
 151 \begin{twocollist}\itemsep=0pt
 152 \twocolitem{{\bf wxURI\_REGNAME}}{Server is a host name, or the Server component itself is undefined.}
 153 \twocolitem{{\bf wxURI\_IPV4ADDRESS}}{Server is a IP version 4 address (XXX.XXX.XXX.XXX)}
 154 \twocolitem{{\bf wxURI\_IPV6ADDRESS}}{Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX}
 155 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
 156 \end{twocollist}
 157
 158
 159 \membersection{wxURI::GetPassword}\label{wxurigetpassword}
 160
 161 \constfunc{const wxString&}{GetPassword}{\void}
 162
 163 Returns the password part of the userinfo component of
 164 this URI.  Note that this is explicitly depreciated by
 165 RFC 1396 and should generally be avoided if possible.
 166
 167 \tt{http://<user>:<password>@mysite.com/mypath}
 168
 169
 170 \membersection{wxURI::GetPath}\label{wxurigetpath}
 171
 172 \constfunc{const wxString&}{GetPath}{\void}
 173
 174 Returns the (normalized) path of the URI.
 175
 176 The path component of a URI comes
 177 directly after the scheme component
 178 if followed by zero or one slashes ('/'),
 179 or after the server/port component.
 180
 181 Absolute paths include the leading '/'
 182 character.
 183
 184 \tt{http://mysite.com<path>}
 185
 186 \membersection{wxURI::GetPort}\label{wxurigetport}
 187
 188 \constfunc{const wxString&}{GetPort}{\void}
 189
 190 Returns a string representation of the URI's port.
 191
 192 The Port of a URI is a value after the server, and
 193 must come after a colon (:).
 194
 195 \tt{http://mysite.com:<port>}
 196
 197 Note that you can easily get the numeric value of the port
 198 by using wxAtoi or wxString::Format.
 199
 200 \membersection{wxURI::GetQuery}\label{wxurigetquery}
 201
 202 \constfunc{const wxString&}{GetQuery}{\void}
 203
 204 Returns the Query component of the URI.
 205
 206 The query component is what is commonly passed to a
 207 cgi application, and must come after the path component,
 208 and after a '?' character.
 209
 210 \tt{http://mysite.com/mypath?<query>}
 211
 212
 213 \membersection{wxURI::GetScheme}\label{wxurigetscheme}
 214
 215 \constfunc{const wxString&}{GetScheme}{\void}
 216
 217 Returns the Scheme component of the URI.
 218
 219 The first part of the uri.
 220
 221 \tt{<scheme>://mysite.com}
 222
 223
 224 \membersection{wxURI::GetServer}\label{wxurigetserver}
 225
 226 \constfunc{const wxString&}{GetServer}{\void}
 227
 228 Returns the Server component of the URI.
 229
 230 The server of the uri can be a server name or
 231 a type of ip address.  See
 232 \helpref{GetHostType}{wxurigethosttype} for the
 233 possible values for the host type of the
 234 server component.
 235
 236 \tt{http://<server>/mypath}
 237
 238
 239 \membersection{wxURI::GetUser}\label{wxurigetuser}
 240
 241 \constfunc{const wxString&}{GetUser}{\void}
 242
 243 Returns the username part of the userinfo component of
 244 this URI.  Note that this is explicitly depreciated by
 245 RFC 1396 and should generally be avoided if possible.
 246
 247 \tt{http://<user>:<password>@mysite.com/mypath}
 248
 249
 250 \membersection{wxURI::GetUserInfo}\label{wxurigetuserinfo}
 251
 252 \constfunc{const wxString&}{GetUserInfo}{\void}
 253
 254 Returns the UserInfo component of the URI.
 255
 256 The component of a URI before the server component
 257 that is postfixed by a '@' character.
 258
 259 \tt{http://<userinfo>@mysite.com/mypath}
 260
 261
 262 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 263
 264 \constfunc{bool}{HasFragment}{\void}
 265
 266 Returns \true if the Fragment component of the URI exists.
 267
 268
 269 \membersection{wxURI::HasPath}\label{wxurihaspath}
 270
 271 \constfunc{bool}{HasPath}{\void}
 272
 273 Returns \true if the Path component of the URI exists.
 274
 275
 276 \membersection{wxURI::HasPort}\label{wxurihasport}
 277
 278 \constfunc{bool}{HasPort}{\void}
 279
 280 Returns \true if the Port component of the URI exists.
 281
 282
 283 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 284
 285 \constfunc{bool}{HasQuery}{\void}
 286
 287 Returns \true if the Query component of the URI exists.
 288
 289
 290 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 291
 292 \constfunc{bool}{HasScheme}{\void}
 293
 294 Returns \true if the Scheme component of the URI exists.
 295
 296
 297 \membersection{wxURI::HasServer}\label{wxurihasserver}
 298
 299 \constfunc{bool}{HasServer}{\void}
 300
 301 Returns \true if the Server component of the URI exists.
 302
 303
 304 \membersection{wxURI::HasUser}\label{wxurihasuserinfo}
 305
 306 \constfunc{bool}{HasUser}{\void}
 307
 308 Returns \true if the User component of the URI exists.
 309
 310
 311 \membersection{wxURI::IsReference}\label{wxuriisreference}
 312
 313 \constfunc{bool}{IsReference}{\void}
 314
 315 Returns \true if a valid [absolute] URI, otherwise this URI
 316 is a URI reference and not a full URI, and IsReference
 317 returns \false.
 318
 319
 320 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 321
 322 \func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
 323
 324 Compares this URI to another URI, and returns \true if
 325 this URI equals \arg{uricomp}, otherwise it returns \false.
 326
 327 \docparam{uricomp}{URI to compare to}
 328
 329
 330 \membersection{wxURI::Resolve}\label{wxuriresolve}
 331
 332 \func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}}
 333
 334 Inherits this URI from a base URI - components that do not
 335 exist in this URI are copied from the base, and if this URI's
 336 path is not an absolute path (prefixed by a '/'), then this URI's
 337 path is merged with the base's path.
 338
 339 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 340 results in the scheme (http) and server (mysite.com) being copied into
 341 this URI, since they do not exist.  In addition, since the path
 342 of this URI is not absolute (does not begin with '/'), the path
 343 of the base's is merged with this URI's path, resulting in the URI
 344 "http://mysite.com/john/mydir".
 345
 346 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}
 347 \docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non strict
 348 mode some compatibility layers are enabled to allow loopholes from RFCs prior
 349 to 2396}
 350
 351 \membersection{wxURI::Unescape}\label{wxuriunescape}
 352
 353 \func{wxString}{Unescape}{\param{const wxString\& }{uri}}
 354
 355 Translates all escape sequences (% hex hex) of \arg{uri} into
 356 normal characters and returns the result.
 357
 358 This is the preferred over deprecated wxURL::ConvertFromURI.
 359
 360 If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead,
 361 as it performs some optimizations over this method.
 362
 363 \docparam{uri}{string with escaped characters to convert}
 364
 365