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