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 - most
  23 acceptable URLs are also acceptable URIs.
  24
  25 wxURI can be used to validate URIs:
  26 \begin{verbatim}
  27 URI myuri;
  28
  29 //will not print "Bad URI" because this is a valid URI
  30 if(!myuri.Create(("ftp://mysiteftp.com/mydir")))
  31         wxPrintf("Bad URI");
  32
  33 URI mybaduri;
  34
  35 //will print "Bad URI" because ::x:: is not a valid URI
  36 if(!mybaduri.Create(("::x::")))
  37         wxPrintf("Bad URI");
  38 \end{verbatim}
  39
  40 wxURI also has some uses that may not be apparent at first,
  41 such as skipping past a URI in a string:
  42 \begin{verbatim}
  43 URI myuri;
  44 wxString mystring = wxT("http://mysite.com A Good Website");
  45
  46 //mystring will contain " A Good Website" after URI::Create()
  47 mystring = myuri.Extract(mystring);
  48 \end{verbatim}
  49
  50 wxURI supports copy construction and standard assignment
  51 operators.  wxURI can also be inherited from to provide
  52 furthur functionality.
  53
  54 \wxheading{Derived from}
  55
  56 No base class
  57
  58 \wxheading{Include files}
  59
  60 <uri.h>
  61
  62 \latexignore{\rtfignore{\wxheading{Members}}}
  63
  64 \membersection{Obtaining individual components}
  65
  66 To obtain individual components you can use
  67 one of the following methods:
  68
  69 \helpref{GetScheme}{wxurigetscheme}\\
  70 \helpref{GetUser}{wxurigetuser}\\
  71 \helpref{GetServer}{wxurigetserver}\\
  72 \helpref{GetPort}{wxurigetserver}\\
  73 \helpref{GetPath}{wxurigetpath}\\
  74 \helpref{GetQuery}{wxurigetquery}\\
  75 \helpref{GetFragment}{wxurigetfragment}
  76
  77 However, you should check HasXXX before
  78 calling a get method:
  79
  80 \helpref{HasScheme}{wxurihasscheme}\\
  81 \helpref{HasUser}{wxurihasuser}\\
  82 \helpref{HasServer}{wxurihasserver}\\
  83 \helpref{HasPort}{wxurihasserver}\\
  84 \helpref{HasPath}{wxurihaspath}\\
  85 \helpref{HasQuery}{wxurihasquery}\\
  86 \helpref{HasFragment}{wxurihasfragment}
  87
  88 Example:
  89 \begin{verbatim}
  90 //protocol will hold the http protocol (i.e. "http")
  91 wxString protocol;
  92 wxURI myuri(wxT("http://mysite.com"));
  93 if(myuri.HasScheme())
  94    protocol = myuri.GetScheme();
  95 \end{verbatim}
  96
  97 Also, you can get the numeric value of the URI's port
  98 component by calling \helpref{GetPortValue}{wxurigetportvalue},
  99 and the host type of the server component by calling
 100 \helpref{GetHostType}{wxurigethosttype}
 101
 102 \membersection{wxURI::wxURI}\label{wxuriwxuri}
 103
 104 \func{}{wxURI}{\void}
 105
 106 Creates an empty URI.  In order for the URI to be
 107 useful, Create needs to be called eventually.
 108
 109 \membersection{wxURI::\destruct{wxURI}}\label{wxuridtor}
 110
 111 \func{}{wxURI}{\param{const wxChar* }{uri}}
 112
 113 Constructor for quick creation
 114
 115 \docparam{uri}{string to initialize with}
 116
 117
 118 \func{}{wxURI}{\param{const wxURI& }{uri}}
 119
 120 Copies this URI from another URI.
 121
 122 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
 123
 124
 125 \membersection{wxURI::Create}\label{wxuricreate}
 126
 127 \func{const wxChar*}{Create}{\param{const wxChar* }{uri}}
 128
 129 Creates this URI from a string, and parses \arg{uri} for validity.
 130 Returns the position where parsing stopped in string,
 131 or false if \arg{uri} is not a valid URI.
 132
 133 \docparam{uri}{string to initialize from}
 134
 135 \membersection{wxURI::Get}\label{wxuriget}
 136
 137 \constfunc{wxString}{Get}{\void}
 138
 139 Obtains the full URI.
 140
 141 If the URI is not a reference or is not resolved,
 142 the URI that is returned from Get is the same one
 143 passed to Create.
 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 \membersection{wxURI::GetPath}\label{wxurigetpath}
 173
 174 \constfunc{const wxString&}{GetPath}{\void}
 175
 176 Returns the (normalized) path of the URI.
 177
 178 The path component of a URI comes
 179 directly after the scheme component
 180 if followed by zero or one slashes ('/'),
 181 or after the server/port component.
 182
 183 Absolute paths include the leading '/'
 184 character.
 185
 186 \tt{http://mysite.com<path>}
 187
 188 \membersection{wxURI::GetPort}\label{wxurigetport}
 189
 190 \constfunc{const wxString&}{GetPort}{\void}
 191
 192 Returns a string representation of the URI's port.
 193
 194 The Port of a URI is a value after the server, and
 195 must come after a colon (:).
 196
 197 \tt{http://mysite.com:<port>}
 198
 199 Note that you can easily get the numeric value of the port
 200 by using wxAtoi or wxString::Format.
 201
 202 \membersection{wxURI::GetQuery}\label{wxurigetquery}
 203
 204 \constfunc{const wxString&}{GetQuery}{\void}
 205
 206 Returns the Query component of the URI.
 207
 208 The query component is what is commonly passed to a
 209 cgi application, and must come after the path component,
 210 and after a '?' character.
 211
 212 \tt{http://mysite.com/mypath?<query>}
 213
 214
 215 \membersection{wxURI::GetScheme}\label{wxurigetscheme}
 216
 217 \constfunc{const wxString&}{GetScheme}{\void}
 218
 219 Returns the Scheme component of the URI.
 220
 221 The first part of the uri.
 222
 223 \tt{<scheme>://mysite.com}
 224
 225
 226 \membersection{wxURI::GetServer}\label{wxurigetserver}
 227
 228 \constfunc{const wxString&}{GetServer}{\void}
 229
 230 Returns the Server component of the URI.
 231
 232 The server of the uri can be a server name or
 233 a type of ip address.  See
 234 \helpref{GetHostType}{wxurigethosttype} for the
 235 possible values for the host type of the
 236 server component.
 237
 238 \tt{http://<server>/mypath}
 239
 240
 241 \membersection{wxURI::GetUser}\label{wxurigetuser}
 242
 243 \constfunc{const wxString&}{GetUser}{\void}
 244
 245 Returns the User component of the URI.
 246
 247 The component of a URI before the server component
 248 that is postfixed by a '@' character.
 249
 250 \tt{http://<user>@mysite.com/mypath}
 251
 252 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 253
 254 \constfunc{bool}{HasFragment}{\void}
 255
 256 Returns true if the Fragment component of the URI exists.
 257
 258 \membersection{wxURI::HasPath}\label{wxurihaspath}
 259
 260 \constfunc{bool}{HasPath}{\void}
 261
 262 Returns true if the Path component of the URI exists.
 263
 264 \membersection{wxURI::HasPort}\label{wxurihasport}
 265
 266 \constfunc{bool}{HasPort}{\void}
 267
 268 Returns true if the Port component of the URI exists.
 269
 270
 271 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 272
 273 \constfunc{bool}{HasQuery}{\void}
 274
 275 Returns true if the Query component of the URI exists.
 276
 277
 278 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 279
 280 \constfunc{bool}{HasScheme}{\void}
 281
 282 Returns true if the Scheme component of the URI exists.
 283
 284
 285 \membersection{wxURI::HasServer}\label{wxurihasserver}
 286
 287 \constfunc{bool}{HasServer}{\void}
 288
 289 Returns true if the Server component of the URI exists.
 290
 291
 292 \membersection{wxURI::HasUser}\label{wxurihasuser}
 293
 294 \constfunc{bool}{HasUser}{\void}
 295
 296 Returns true if the User component of the URI exists.
 297
 298
 299 \membersection{wxURI::IsOk}\label{wxuriisok}
 300
 301 \constfunc{bool}{IsOk}{\void}
 302
 303 Returns true if this is a valid URI.
 304
 305
 306 \membersection{wxURI::IsReference}\label{wxuriisreference}
 307
 308 \constfunc{bool}{IsReference}{\void}
 309
 310 Returns true if a valid [absolute] URI, otherwise this URI
 311 is a URI reference and not a full URI, and IsReference
 312 returns false.
 313
 314
 315 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 316
 317 \func{void}{operator ==}{\param{const wxURI& }{uricomp}}
 318
 319 Compares this URI to another URI, and returns true if
 320 this URI equals uricomp, otherwise it returns false.
 321
 322 \docparam{uricomp}{URI to compare to}
 323
 324
 325 \membersection{wxURI::Extract}\label{wxuriextract}
 326
 327 \func{static const wxChar*}{Extract}{\param{const wxChar*}{uri}}
 328
 329 Used to determine where a URI ends in a string.
 330
 331 Returns the position at which parsing stopped
 332 (will return NULL on malformed URIs).
 333
 334 \docparam{uri}{String to create from}
 335
 336
 337 \membersection{wxURI::Resolve}\label{wxuriresolve}
 338
 339 \func{void}{Resolve}{\param{const wxURI\& }{base}, \param{const bool\& }{bStrict = true}}
 340
 341 Inherits this URI from a base URI - components that do not
 342 exist in this URI are copied from the base, and if this URI's
 343 path is not an absolute path (prefixed by a '/'), then this URI's
 344 path is merged with the base's path.
 345
 346 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 347 results in the scheme (http) and server (mysite.com) being copied into
 348 this URI, since they do not exist.  In addition, since the path
 349 of this URI is not absolute (does not begin with '/'), the path
 350 of the base's is merged with this URI's path, resulting in the URI
 351 "http://mysite.com/john/mydir".
 352
 353 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}
 354 \docparam{bStrict}{If false, some compatability layers are enabled to allow
 355                    loopholes from RFCs prior to 2396}
 356