interface/wx/uri.h

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