interface/uri.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        uri.h
   3 // Purpose:     documentation for wxURI class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxURI
  11     @wxheader{uri.h}
  12
  13     wxURI is used to extract information from
  14     a URI (Uniform Resource Identifier).
  15
  16     For information about URIs, see
  17     RFC 3986.
  18
  19     In short, a URL is a URI.  In other
  20     words, URL is a subset of a URI - all
  21     acceptable URLs are also acceptable URIs.
  22
  23     wxURI automatically escapes invalid characters in a string,
  24     so there is no chance of wxURI "failing" on construction/creation.
  25
  26     wxURI supports copy construction and standard assignment
  27     operators.  wxURI can also be inherited from to provide
  28     furthur functionality.
  29
  30     @library{wxbase}
  31     @category{data}
  32
  33     @seealso
  34     wxURL
  35 */
  36 class wxURI : public wxObject
  37 {
  38 public:
  39     //@{
  40     /**
  41         Copies this URI from another URI.
  42
  43         @param uri
  44         URI (Uniform Resource Identifier) to initialize with
  45     */
  46     wxURI();
  47     wxURI(const wxChar* uri);
  48     wxURI(const wxURI& uri);
  49     //@}
  50
  51     /**
  52         Builds the URI from its individual components and adds proper separators.
  53
  54         If the URI is not a reference or is not resolved,
  55         the URI that is returned from Get is the same one
  56         passed to Create.
  57     */
  58     wxString BuildURI();
  59
  60     /**
  61         Builds the URI from its individual components, adds proper separators, and
  62         returns escape sequences to normal characters.
  63
  64         Note that it is preferred to call this over Unescape(BuildURI()) since
  65         BuildUnescapedURI() performs some optimizations over the plain method.
  66     */
  67     wxString BuildUnescapedURI();
  68
  69     /**
  70         Creates this URI from the string
  71
  72         @param uri.
  73
  74         Returns the position at which parsing stopped (there
  75         is no such thing as an "invalid" wxURI).
  76
  77         uri
  78         string to initialize from
  79     */
  80     const wxChar* Create(const wxString uri);
  81
  82     /**
  83         Note that on URIs with a "file" scheme wxURI does not
  84         parse the userinfo, server, or port portion.  This is to keep
  85         compatability with wxFileSystem, the old wxURL, and older url specifications.
  86     */
  87
  88
  89     /**
  90         Obtains the fragment of this URI.
  91
  92         The fragment of a URI is the last value of the URI,
  93         and is the value after a '' character after the path
  94         of the URI.
  95
  96         @c http://mysite.com/mypath#fragment
  97     */
  98     const wxString GetFragment();
  99
 100     /**
 101         Obtains the host type of this URI, which is of type
 102         HostType():
 103
 104
 105         @b wxURI_REGNAME
 106
 107
 108         Server is a host name, or the Server component itself is undefined.
 109
 110         @b wxURI_IPV4ADDRESS
 111
 112
 113         Server is a IP version 4 address (XXX.XXX.XXX.XXX)
 114
 115         @b wxURI_IPV6ADDRESS
 116
 117
 118         Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX
 119
 120         @b wxURI_IPVFUTURE
 121
 122
 123         Server is an IP address, but not versions 4 or 6
 124     */
 125     const HostType GetHostType();
 126
 127     /**
 128         Returns the password part of the userinfo component of
 129         this URI.  Note that this is explicitly depreciated by
 130         RFC 1396 and should generally be avoided if possible.
 131
 132         @c http://user:password@mysite.com/mypath
 133     */
 134     const wxString GetPassword();
 135
 136     /**
 137         Returns the (normalized) path of the URI.
 138
 139         The path component of a URI comes
 140         directly after the scheme component
 141         if followed by zero or one slashes ('/'),
 142         or after the server/port component.
 143
 144         Absolute paths include the leading '/'
 145         character.
 146
 147         @c http://mysite.compath
 148     */
 149     const wxString GetPath();
 150
 151     /**
 152         Returns a string representation of the URI's port.
 153
 154         The Port of a URI is a value after the server, and
 155         must come after a colon (:).
 156
 157         @c http://mysite.com:port
 158
 159         Note that you can easily get the numeric value of the port
 160         by using wxAtoi or wxString::Format.
 161     */
 162     const wxString GetPort();
 163
 164     /**
 165         Returns the Query component of the URI.
 166
 167         The query component is what is commonly passed to a
 168         cgi application, and must come after the path component,
 169         and after a '?' character.
 170
 171         @c http://mysite.com/mypath?query
 172     */
 173     const wxString GetQuery();
 174
 175     /**
 176         Returns the Scheme component of the URI.
 177
 178         The first part of the uri.
 179
 180         @c scheme://mysite.com
 181     */
 182     const wxString GetScheme();
 183
 184     /**
 185         Returns the Server component of the URI.
 186
 187         The server of the uri can be a server name or
 188         a type of ip address.  See
 189         GetHostType() for the
 190         possible values for the host type of the
 191         server component.
 192
 193         @c http://server/mypath
 194     */
 195     const wxString GetServer();
 196
 197     /**
 198         Returns the username part of the userinfo component of
 199         this URI.  Note that this is explicitly depreciated by
 200         RFC 1396 and should generally be avoided if possible.
 201
 202         @c http://user:password@mysite.com/mypath
 203     */
 204     const wxString GetUser();
 205
 206     /**
 207         Returns the UserInfo component of the URI.
 208
 209         The component of a URI before the server component
 210         that is postfixed by a '@' character.
 211
 212         @c http://userinfo@mysite.com/mypath
 213     */
 214     const wxString GetUserInfo();
 215
 216     /**
 217         Returns @true if the Fragment component of the URI exists.
 218     */
 219     bool HasFragment();
 220
 221     /**
 222         Returns @true if the Path component of the URI exists.
 223     */
 224     bool HasPath();
 225
 226     /**
 227         Returns @true if the Port component of the URI exists.
 228     */
 229     bool HasPort();
 230
 231     /**
 232         Returns @true if the Query component of the URI exists.
 233     */
 234     bool HasQuery();
 235
 236     /**
 237         Returns @true if the Scheme component of the URI exists.
 238     */
 239     bool HasScheme();
 240
 241     /**
 242         Returns @true if the Server component of the URI exists.
 243     */
 244     bool HasServer();
 245
 246     /**
 247         Returns @true if the User component of the URI exists.
 248     */
 249     bool HasUser();
 250
 251     /**
 252         Returns @true if a valid [absolute] URI, otherwise this URI
 253         is a URI reference and not a full URI, and IsReference
 254         returns @false.
 255     */
 256     bool IsReference();
 257
 258     /**
 259         To obtain individual components you can use
 260         one of the following methods
 261
 262         GetScheme()
 263
 264         GetUserInfo()
 265
 266         GetServer()
 267
 268         GetPort()
 269
 270         GetPath()
 271
 272         GetQuery()
 273
 274         GetFragment()
 275
 276         However, you should check HasXXX before
 277         calling a get method, which determines whether or not the component referred
 278         to by the method is defined according to RFC 2396.
 279
 280         Consider an undefined component equivalent to a
 281         @NULL C string.
 282
 283
 284         HasScheme()
 285
 286         HasUserInfo()
 287
 288         HasServer()
 289
 290         @ref hasserver() HasPort
 291
 292         HasPath()
 293
 294         HasQuery()
 295
 296         HasFragment()
 297
 298         Example:
 299     */
 300
 301
 302     /**
 303         Inherits this URI from a base URI - components that do not
 304         exist in this URI are copied from the base, and if this URI's
 305         path is not an absolute path (prefixed by a '/'), then this URI's
 306         path is merged with the base's path.
 307
 308         For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 309         results in the scheme (http) and server (mysite.com) being copied into
 310         this URI, since they do not exist.  In addition, since the path
 311         of this URI is not absolute (does not begin with '/'), the path
 312         of the base's is merged with this URI's path, resulting in the URI
 313         "http://mysite.com/john/mydir".
 314
 315         @param base
 316         Base URI to inherit from.  Must be a full URI and not a reference
 317
 318         @param flags
 319         Currently either wxURI_STRICT or 0, in non-strict
 320         mode some compatibility layers are enabled to allow loopholes from RFCs prior
 321         to 2396
 322     */
 323     void Resolve(const wxURI& base, int flags = wxURI_STRICT);
 324
 325     /**
 326         Translates all escape sequences (normal characters and returns the result.
 327
 328         This is the preferred over deprecated wxURL::ConvertFromURI.
 329
 330         If you want to unescape an entire wxURI, use BuildUnescapedURI() instead,
 331         as it performs some optimizations over this method.
 332
 333         @param uri
 334         string with escaped characters to convert
 335     */
 336     wxString Unescape(const wxString& uri);
 337
 338     /**
 339         Compares this URI to another URI, and returns @true if
 340         this URI equals
 341
 342         @param uricomp, otherwise it returns @false.
 343
 344         uricomp
 345         URI to compare to
 346     */
 347     void operator ==(const wxURI& uricomp);
 348 };