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 supports copy construction and standard assignment
  26 operators.  wxURI can also be inherited from to provide
  27 furthur functionality.
  28
  29 \wxheading{Derived from}
  30
  31 No base class
  32
  33 \wxheading{Include files}
  34
  35 <uri.h>
  36
  37 \latexignore{\rtfignore{\wxheading{Members}}}
  38
  39 \membersection{Obtaining individual components}
  40
  41 To obtain individual components you can use
  42 one of the following methods:
  43
  44 \helpref{GetScheme}{wxurigetscheme}\\
  45 \helpref{GetUser}{wxurigetuser}\\
  46 \helpref{GetServer}{wxurigetserver}\\
  47 \helpref{GetPort}{wxurigetserver}\\
  48 \helpref{GetPath}{wxurigetpath}\\
  49 \helpref{GetQuery}{wxurigetquery}\\
  50 \helpref{GetFragment}{wxurigetfragment}
  51
  52 However, you should check HasXXX before
  53 calling a get method:\\
  54
  55 \helpref{HasScheme}{wxurihasscheme}\\
  56 \helpref{HasUser}{wxurihasuser}\\
  57 \helpref{HasServer}{wxurihasserver}\\
  58 \helpref{HasPort}{wxurihasserver}\\
  59 \helpref{HasPath}{wxurihaspath}\\
  60 \helpref{HasQuery}{wxurihasquery}\\
  61 \helpref{HasFragment}{wxurihasfragment}
  62
  63 Example:
  64 \begin{verbatim}
  65 //protocol will hold the http protocol (i.e. "http")
  66 wxString protocol;
  67 wxURI myuri(wxT("http://mysite.com"));
  68 if(myuri.HasScheme())
  69    protocol = myuri.GetScheme();
  70 \end{verbatim}
  71
  72 \membersection{wxURI::wxURI}\label{wxuriwxuri}
  73
  74 \func{}{wxURI}{\void}
  75
  76 Creates an empty URI.  In order for the URI to be
  77 useful, Create needs to be called eventually.
  78
  79 \membersection{wxURI::\destruct{wxURI}}\label{wxuridtor}
  80
  81 \func{}{wxURI}{\param{const wxChar* }{uri}}
  82
  83 Constructor for quick creation
  84
  85 \docparam{uri}{string to initialize with}
  86
  87
  88 \func{}{wxURI}{\param{const wxURI& }{uri}}
  89
  90 Copies this URI from another URI.
  91
  92 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
  93
  94
  95 \membersection{wxURI::Create}\label{wxuricreate}
  96
  97 \func{void}{Create}{\param{const wxChar* }{uri}}
  98
  99 Creates this URI from the string {\tt uri}.
 100
 101 \docparam{uri}{string to initialize from}
 102
 103 \membersection{wxURI::Get}\label{wxuriget}
 104
 105 \constfunc{wxString}{Get}{\void}
 106
 107 Obtains the full URI.
 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 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
 114
 115 \constfunc{const wxString&}{GetFragment}{\void}
 116
 117 Obtains the fragment of this URI.
 118
 119 The fragment of a URI is the last value of the URI,
 120 and is the value after a '#' character after the path
 121 of the URI.
 122
 123 \tt{http://mysite.com/mypath\#<fragment>}
 124
 125 \membersection{wxURI::GetHostType}\label{wxurigethosttype}
 126
 127 \constfunc{const HostType\&}{GetHostType}{\void}
 128
 129 Obtains the host type of this URI, which is of type
 130 wxURI::HostType:
 131
 132 \twocolwidtha{7cm}
 133 \begin{twocollist}\itemsep=0pt
 134 \twocolitem{{\bf wxURI\_REGNAME}}{Server is a host name, or the Server component itself is undefined.}
 135 \twocolitem{{\bf wxURI\_IPV4ADDRESS}}{Server is a IP version 4 address (XXX.XXX.XXX.XXX)}
 136 \twocolitem{{\bf wxURI\_IPV6ADDRESS}}{Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX}
 137 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
 138 \end{twocollist}
 139
 140 \membersection{wxURI::GetPath}\label{wxurigetpath}
 141
 142 \constfunc{const wxString&}{GetPath}{\void}
 143
 144 Returns the (normalized) path of the URI.
 145
 146 The path component of a URI comes
 147 directly after the scheme component
 148 if followed by zero or one slashes ('/'),
 149 or after the server/port component.
 150
 151 Absolute paths include the leading '/'
 152 character.
 153
 154 \tt{http://mysite.com<path>}
 155
 156 \membersection{wxURI::GetPort}\label{wxurigetport}
 157
 158 \constfunc{const wxString&}{GetPort}{\void}
 159
 160 Returns a string representation of the URI's port.
 161
 162 The Port of a URI is a value after the server, and
 163 must come after a colon (:).
 164
 165 \tt{http://mysite.com:<port>}
 166
 167 Note that you can easily get the numeric value of the port
 168 by using wxAtoi or wxString::Format.
 169
 170 \membersection{wxURI::GetQuery}\label{wxurigetquery}
 171
 172 \constfunc{const wxString&}{GetQuery}{\void}
 173
 174 Returns the Query component of the URI.
 175
 176 The query component is what is commonly passed to a
 177 cgi application, and must come after the path component,
 178 and after a '?' character.
 179
 180 \tt{http://mysite.com/mypath?<query>}
 181
 182
 183 \membersection{wxURI::GetScheme}\label{wxurigetscheme}
 184
 185 \constfunc{const wxString&}{GetScheme}{\void}
 186
 187 Returns the Scheme component of the URI.
 188
 189 The first part of the uri.
 190
 191 \tt{<scheme>://mysite.com}
 192
 193
 194 \membersection{wxURI::GetServer}\label{wxurigetserver}
 195
 196 \constfunc{const wxString&}{GetServer}{\void}
 197
 198 Returns the Server component of the URI.
 199
 200 The server of the uri can be a server name or
 201 a type of ip address.  See
 202 \helpref{GetHostType}{wxurigethosttype} for the
 203 possible values for the host type of the
 204 server component.
 205
 206 \tt{http://<server>/mypath}
 207
 208
 209 \membersection{wxURI::GetUser}\label{wxurigetuser}
 210
 211 \constfunc{const wxString&}{GetUser}{\void}
 212
 213 Returns the User component of the URI.
 214
 215 The component of a URI before the server component
 216 that is postfixed by a '@' character.
 217
 218 \tt{http://<user>@mysite.com/mypath}
 219
 220 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 221
 222 \constfunc{bool}{HasFragment}{\void}
 223
 224 Returns true if the Fragment component of the URI exists.
 225
 226 \membersection{wxURI::HasPath}\label{wxurihaspath}
 227
 228 \constfunc{bool}{HasPath}{\void}
 229
 230 Returns true if the Path component of the URI exists.
 231
 232 \membersection{wxURI::HasPort}\label{wxurihasport}
 233
 234 \constfunc{bool}{HasPort}{\void}
 235
 236 Returns true if the Port component of the URI exists.
 237
 238
 239 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 240
 241 \constfunc{bool}{HasQuery}{\void}
 242
 243 Returns true if the Query component of the URI exists.
 244
 245
 246 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 247
 248 \constfunc{bool}{HasScheme}{\void}
 249
 250 Returns true if the Scheme component of the URI exists.
 251
 252
 253 \membersection{wxURI::HasServer}\label{wxurihasserver}
 254
 255 \constfunc{bool}{HasServer}{\void}
 256
 257 Returns true if the Server component of the URI exists.
 258
 259
 260 \membersection{wxURI::HasUser}\label{wxurihasuser}
 261
 262 \constfunc{bool}{HasUser}{\void}
 263
 264 Returns true if the User component of the URI exists.
 265
 266
 267 \membersection{wxURI::IsReference}\label{wxuriisreference}
 268
 269 \constfunc{bool}{IsReference}{\void}
 270
 271 Returns true if a valid [absolute] URI, otherwise this URI
 272 is a URI reference and not a full URI, and IsReference
 273 returns false.
 274
 275
 276 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 277
 278 \func{void}{operator ==}{\param{const wxURI& }{uricomp}}
 279
 280 Compares this URI to another URI, and returns true if
 281 this URI equals uricomp, otherwise it returns false.
 282
 283 \docparam{uricomp}{URI to compare to}
 284
 285
 286 \membersection{wxURI::Resolve}\label{wxuriresolve}
 287
 288 \func{void}{Resolve}{\param{const wxURI\& }{base}, \param{const bool\& }{bStrict = true}}
 289
 290 Inherits this URI from a base URI - components that do not
 291 exist in this URI are copied from the base, and if this URI's
 292 path is not an absolute path (prefixed by a '/'), then this URI's
 293 path is merged with the base's path.
 294
 295 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 296 results in the scheme (http) and server (mysite.com) being copied into
 297 this URI, since they do not exist.  In addition, since the path
 298 of this URI is not absolute (does not begin with '/'), the path
 299 of the base's is merged with this URI's path, resulting in the URI
 300 "http://mysite.com/john/mydir".
 301
 302 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}
 303 \docparam{bStrict}{If false, some compatability layers are enabled to allow
 304                    loopholes from RFCs prior to 2396}
 305