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