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{GetUser}{wxurigetuser}\\
  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 equivilent to a
  60 NULL C string.\\
  61 \\
  62 \helpref{HasScheme}{wxurihasscheme}\\
  63 \helpref{HasUser}{wxurihasuser}\\
  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 wxChar* }{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 \membersection{wxURI::GetPath}\label{wxurigetpath}
 160
 161 \constfunc{const wxString&}{GetPath}{\void}
 162
 163 Returns the (normalized) path of the URI.
 164
 165 The path component of a URI comes
 166 directly after the scheme component
 167 if followed by zero or one slashes ('/'),
 168 or after the server/port component.
 169
 170 Absolute paths include the leading '/'
 171 character.
 172
 173 \tt{http://mysite.com<path>}
 174
 175 \membersection{wxURI::GetPort}\label{wxurigetport}
 176
 177 \constfunc{const wxString&}{GetPort}{\void}
 178
 179 Returns a string representation of the URI's port.
 180
 181 The Port of a URI is a value after the server, and
 182 must come after a colon (:).
 183
 184 \tt{http://mysite.com:<port>}
 185
 186 Note that you can easily get the numeric value of the port
 187 by using wxAtoi or wxString::Format.
 188
 189 \membersection{wxURI::GetQuery}\label{wxurigetquery}
 190
 191 \constfunc{const wxString&}{GetQuery}{\void}
 192
 193 Returns the Query component of the URI.
 194
 195 The query component is what is commonly passed to a
 196 cgi application, and must come after the path component,
 197 and after a '?' character.
 198
 199 \tt{http://mysite.com/mypath?<query>}
 200
 201
 202 \membersection{wxURI::GetScheme}\label{wxurigetscheme}
 203
 204 \constfunc{const wxString&}{GetScheme}{\void}
 205
 206 Returns the Scheme component of the URI.
 207
 208 The first part of the uri.
 209
 210 \tt{<scheme>://mysite.com}
 211
 212
 213 \membersection{wxURI::GetServer}\label{wxurigetserver}
 214
 215 \constfunc{const wxString&}{GetServer}{\void}
 216
 217 Returns the Server component of the URI.
 218
 219 The server of the uri can be a server name or
 220 a type of ip address.  See
 221 \helpref{GetHostType}{wxurigethosttype} for the
 222 possible values for the host type of the
 223 server component.
 224
 225 \tt{http://<server>/mypath}
 226
 227
 228 \membersection{wxURI::GetUser}\label{wxurigetuser}
 229
 230 \constfunc{const wxString&}{GetUser}{\void}
 231
 232 Returns the User component of the URI.
 233
 234 The component of a URI before the server component
 235 that is postfixed by a '@' character.
 236
 237 \tt{http://<user>@mysite.com/mypath}
 238
 239 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 240
 241 \constfunc{bool}{HasFragment}{\void}
 242
 243 Returns \true if the Fragment component of the URI exists.
 244
 245 \membersection{wxURI::HasPath}\label{wxurihaspath}
 246
 247 \constfunc{bool}{HasPath}{\void}
 248
 249 Returns \true if the Path component of the URI exists.
 250
 251 \membersection{wxURI::HasPort}\label{wxurihasport}
 252
 253 \constfunc{bool}{HasPort}{\void}
 254
 255 Returns \true if the Port component of the URI exists.
 256
 257
 258 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 259
 260 \constfunc{bool}{HasQuery}{\void}
 261
 262 Returns \true if the Query component of the URI exists.
 263
 264
 265 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 266
 267 \constfunc{bool}{HasScheme}{\void}
 268
 269 Returns \true if the Scheme component of the URI exists.
 270
 271
 272 \membersection{wxURI::HasServer}\label{wxurihasserver}
 273
 274 \constfunc{bool}{HasServer}{\void}
 275
 276 Returns \true if the Server component of the URI exists.
 277
 278
 279 \membersection{wxURI::HasUser}\label{wxurihasuser}
 280
 281 \constfunc{bool}{HasUser}{\void}
 282
 283 Returns \true if the User component of the URI exists.
 284
 285
 286 \membersection{wxURI::IsReference}\label{wxuriisreference}
 287
 288 \constfunc{bool}{IsReference}{\void}
 289
 290 Returns \true if a valid [absolute] URI, otherwise this URI
 291 is a URI reference and not a full URI, and IsReference
 292 returns \false.
 293
 294
 295 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 296
 297 \func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
 298
 299 Compares this URI to another URI, and returns \true if
 300 this URI equals \arg{uricomp}, otherwise it returns \false.
 301
 302 \docparam{uricomp}{URI to compare to}
 303
 304
 305 \membersection{wxURI::Resolve}\label{wxuriresolve}
 306
 307 \func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}}
 308
 309 Inherits this URI from a base URI - components that do not
 310 exist in this URI are copied from the base, and if this URI's
 311 path is not an absolute path (prefixed by a '/'), then this URI's
 312 path is merged with the base's path.
 313
 314 For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 315 results in the scheme (http) and server (mysite.com) being copied into
 316 this URI, since they do not exist.  In addition, since the path
 317 of this URI is not absolute (does not begin with '/'), the path
 318 of the base's is merged with this URI's path, resulting in the URI
 319 "http://mysite.com/john/mydir".
 320
 321 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}
 322 \docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non strict
 323 mode some compatability layers are enabled to allow loopholes from RFCs prior
 324 to 2396}
 325
 326 \membersection{wxURI::Unescape}\label{wxuriunescape}
 327
 328 \func{wxString}{Unescape}{\param{const wxString\& }{uri}}
 329
 330 Translates all escape sequences (% hex hex) of \arg{uri} into
 331 normal characters and returns the result.
 332
 333 This is the preferred over deprecated wxURL::ConvertFromURI.
 334
 335 If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead,
 336 as it performs some optimizations over this method.
 337
 338 \docparam{uri}{string with escaped characters to convert}
 339
 340