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         If the URI is not a reference or is not resolved,
  54         the URI that is returned from Get is the same one
  55         passed to Create.
  56     */
  57     wxString BuildURI();
  58
  59     /**
  60         Builds the URI from its individual components, adds proper separators, and
  61         returns escape sequences to normal characters.
  62         Note that it is preferred to call this over Unescape(BuildURI()) since
  63         BuildUnescapedURI() performs some optimizations over the plain method.
  64     */
  65     wxString BuildUnescapedURI();
  66
  67     /**
  68         Creates this URI from the string
  69
  70         @param uri.
  71
  72         Returns the position at which parsing stopped (there
  73         is no such thing as an "invalid" wxURI).
  74
  75         uri
  76             string to initialize from
  77     */
  78     const wxChar* Create(const wxString uri);
  79
  80     /**
  81         Note that on URIs with a "file" scheme wxURI does not
  82         parse the userinfo, server, or port portion.  This is to keep
  83         compatability with wxFileSystem, the old wxURL, and older url specifications.
  84     */
  85
  86
  87     /**
  88         Obtains the fragment of this URI.
  89         The fragment of a URI is the last value of the URI,
  90         and is the value after a '' character after the path
  91         of the URI.
  92         @c http://mysite.com/mypath#fragment
  93     */
  94     const wxString GetFragment();
  95
  96     /**
  97         Obtains the host type of this URI, which is of type
  98         HostType():
  99
 100         @b wxURI_REGNAME
 101
 102         Server is a host name, or the Server component itself is undefined.
 103
 104         @b wxURI_IPV4ADDRESS
 105
 106         Server is a IP version 4 address (XXX.XXX.XXX.XXX)
 107
 108         @b wxURI_IPV6ADDRESS
 109
 110         Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX
 111
 112         @b wxURI_IPVFUTURE
 113
 114         Server is an IP address, but not versions 4 or 6
 115     */
 116     const HostType GetHostType();
 117
 118     /**
 119         Returns the password part of the userinfo component of
 120         this URI.  Note that this is explicitly depreciated by
 121         RFC 1396 and should generally be avoided if possible.
 122         @c http://user:password@mysite.com/mypath
 123     */
 124     const wxString GetPassword();
 125
 126     /**
 127         Returns the (normalized) path of the URI.
 128         The path component of a URI comes
 129         directly after the scheme component
 130         if followed by zero or one slashes ('/'),
 131         or after the server/port component.
 132         Absolute paths include the leading '/'
 133         character.
 134         @c http://mysite.compath
 135     */
 136     const wxString GetPath();
 137
 138     /**
 139         Returns a string representation of the URI's port.
 140         The Port of a URI is a value after the server, and
 141         must come after a colon (:).
 142         @c http://mysite.com:port
 143         Note that you can easily get the numeric value of the port
 144         by using wxAtoi or wxString::Format.
 145     */
 146     const wxString GetPort();
 147
 148     /**
 149         Returns the Query component of the URI.
 150         The query component is what is commonly passed to a
 151         cgi application, and must come after the path component,
 152         and after a '?' character.
 153         @c http://mysite.com/mypath?query
 154     */
 155     const wxString GetQuery();
 156
 157     /**
 158         Returns the Scheme component of the URI.
 159         The first part of the uri.
 160         @c scheme://mysite.com
 161     */
 162     const wxString GetScheme();
 163
 164     /**
 165         Returns the Server component of the URI.
 166         The server of the uri can be a server name or
 167         a type of ip address.  See
 168         GetHostType() for the
 169         possible values for the host type of the
 170         server component.
 171         @c http://server/mypath
 172     */
 173     const wxString GetServer();
 174
 175     /**
 176         Returns the username part of the userinfo component of
 177         this URI.  Note that this is explicitly depreciated by
 178         RFC 1396 and should generally be avoided if possible.
 179         @c http://user:password@mysite.com/mypath
 180     */
 181     const wxString GetUser();
 182
 183     /**
 184         Returns the UserInfo component of the URI.
 185         The component of a URI before the server component
 186         that is postfixed by a '@' character.
 187         @c http://userinfo@mysite.com/mypath
 188     */
 189     const wxString GetUserInfo();
 190
 191     /**
 192         Returns @true if the Fragment component of the URI exists.
 193     */
 194     bool HasFragment();
 195
 196     /**
 197         Returns @true if the Path component of the URI exists.
 198     */
 199     bool HasPath();
 200
 201     /**
 202         Returns @true if the Port component of the URI exists.
 203     */
 204     bool HasPort();
 205
 206     /**
 207         Returns @true if the Query component of the URI exists.
 208     */
 209     bool HasQuery();
 210
 211     /**
 212         Returns @true if the Scheme component of the URI exists.
 213     */
 214     bool HasScheme();
 215
 216     /**
 217         Returns @true if the Server component of the URI exists.
 218     */
 219     bool HasServer();
 220
 221     /**
 222         Returns @true if the User component of the URI exists.
 223     */
 224     bool HasUser();
 225
 226     /**
 227         Returns @true if a valid [absolute] URI, otherwise this URI
 228         is a URI reference and not a full URI, and IsReference
 229         returns @false.
 230     */
 231     bool IsReference();
 232
 233     /**
 234         To obtain individual components you can use
 235         one of the following methods
 236         GetScheme()
 237
 238         GetUserInfo()
 239
 240         GetServer()
 241
 242         GetPort()
 243
 244         GetPath()
 245
 246         GetQuery()
 247
 248         GetFragment()
 249         However, you should check HasXXX before
 250         calling a get method, which determines whether or not the component referred
 251         to by the method is defined according to RFC 2396.
 252         Consider an undefined component equivalent to a
 253         @NULL C string.
 254
 255         HasScheme()
 256
 257         HasUserInfo()
 258
 259         HasServer()
 260
 261         @ref hasserver() HasPort
 262
 263         HasPath()
 264
 265         HasQuery()
 266
 267         HasFragment()
 268         Example:
 269     */
 270
 271
 272     /**
 273         Inherits this URI from a base URI - components that do not
 274         exist in this URI are copied from the base, and if this URI's
 275         path is not an absolute path (prefixed by a '/'), then this URI's
 276         path is merged with the base's path.
 277         For instance, resolving "../mydir" from "http://mysite.com/john/doe"
 278         results in the scheme (http) and server (mysite.com) being copied into
 279         this URI, since they do not exist.  In addition, since the path
 280         of this URI is not absolute (does not begin with '/'), the path
 281         of the base's is merged with this URI's path, resulting in the URI
 282         "http://mysite.com/john/mydir".
 283
 284         @param base
 285             Base URI to inherit from.  Must be a full URI and not a reference
 286         @param flags
 287             Currently either wxURI_STRICT or 0, in non-strict
 288             mode some compatibility layers are enabled to allow loopholes from RFCs
 289         prior
 290             to 2396
 291     */
 292     void Resolve(const wxURI& base, int flags = wxURI_STRICT);
 293
 294     /**
 295         Translates all escape sequences (normal characters and returns the result.
 296         This is the preferred over deprecated wxURL::ConvertFromURI.
 297         If you want to unescape an entire wxURI, use BuildUnescapedURI() instead,
 298         as it performs some optimizations over this method.
 299
 300         @param uri
 301             string with escaped characters to convert
 302     */
 303     wxString Unescape(const wxString& uri);
 304
 305     /**
 306         Compares this URI to another URI, and returns @true if
 307         this URI equals
 308
 309         @param uricomp, otherwise it returns @false.
 310
 311         uricomp
 312             URI to compare to
 313     */
 314     void operator ==(const wxURI& uricomp);
 315 };