interface/uri.h

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