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