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