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