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