/////////////////////////////////////////////////////////////////////////////
// Name: uri.h
-// Purpose: documentation for wxURI class
+// Purpose: interface of wxURI
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ Host type of URI returned from wxURI::GetHostType().
+*/
+enum wxURIHostType
+{
+ wxURI_REGNAME, ///< Host is a normal register name (@c "www.mysite.com").
+ wxURI_IPV4ADDRESS, ///< Host is a version 4 ip address (@c "192.168.1.100").
+ wxURI_IPV6ADDRESS, ///< Host is a version 6 ip address (@c "[aa:aa:aa:aa::aa:aa]:5050").
+ wxURI_IPVFUTURE ///< Host is a future ip address, wxURI is unsure what kind.
+};
+
/**
@class wxURI
@wxheader{uri.h}
-
- wxURI is used to extract information from
- a URI (Uniform Resource Identifier).
-
- For information about URIs, see
- RFC 3986.
-
- In short, a URL is a URI. In other
- words, URL is a subset of a URI - all
+
+ wxURI is used to extract information from a URI (Uniform Resource
+ Identifier).
+
+ For information about URIs, see RFC 3986
+ <http://www.ietf.org/rfc/rfc3986.txt>.
+
+ In short, a URL is a URI. In other words, URL is a subset of a URI - all
acceptable URLs are also acceptable URIs.
-
- wxURI automatically escapes invalid characters in a string,
- so there is no chance of wxURI "failing" on construction/creation.
-
- wxURI supports copy construction and standard assignment
- operators. wxURI can also be inherited from to provide
- furthur functionality.
-
+
+ wxURI automatically escapes invalid characters in a string, so there is no
+ chance of wxURI "failing" on construction/creation.
+
+ wxURI supports copy construction and standard assignment operators. wxURI
+ can also be inherited from to provide furthur functionality.
+
+ To obtain individual components you can use one of the GetXXX() methods.
+ However, you should check HasXXX() before calling a get method, which
+ determines whether or not the component referred to by the method is
+ defined according to RFC 2396. Consider an undefined component equivalent
+ to a @NULL C string.
+
+ Example:
+
+ @code
+ //protocol will hold the http protocol (i.e. "http")
+ wxString protocol;
+ wxURI myuri("http://mysite.com");
+ if( myuri.HasScheme() )
+ protocol = myuri.GetScheme();
+ @endcode
+
+ @note On URIs with a "file" scheme wxURI does not parse the userinfo,
+ server, or port portion. This is to keep compatability with
+ wxFileSystem, the old wxURL, and older url specifications.
+
@library{wxbase}
@category{data}
-
- @seealso
- wxURL
+
+ @see wxURL
*/
class wxURI : public wxObject
{
public:
- //@{
/**
- Copies this URI from another URI.
-
- @param uri
- URI (Uniform Resource Identifier) to initialize with
+ Creates an empty URI.
*/
wxURI();
- wxURI(const wxChar* uri);
- wxURI(const wxURI& uri);
- //@}
+ /**
+ Constructor for quick creation.
+ @param uri
+ URI (Uniform Resource Identifier) to initialize with.
+ */
+ wxURI(const wxChar* uri);
/**
- Builds the URI from its individual components and adds proper separators.
-
- If the URI is not a reference or is not resolved,
- the URI that is returned from Get is the same one
- passed to Create.
+ Copies this URI from another URI.
+
+ @param uri
+ URI (Uniform Resource Identifier) to initialize with.
*/
- wxString BuildURI();
+ wxURI(const wxURI& uri);
/**
- Builds the URI from its individual components, adds proper separators, and
- returns escape sequences to normal characters.
-
- Note that it is preferred to call this over Unescape(BuildURI()) since
- BuildUnescapedURI() performs some optimizations over the plain method.
+ Builds the URI from its individual components and adds proper
+ separators.
+
+ If the URI is not a reference or is not resolved, the URI that is
+ returned is the same one passed to the constructor or Create().
*/
- wxString BuildUnescapedURI();
+ wxString BuildURI() const;
/**
- Creates this URI from the string
-
- @param uri.
-
- Returns the position at which parsing stopped (there
- is no such thing as an "invalid" wxURI).
-
- uri
- string to initialize from
+ Builds the URI from its individual components, adds proper separators,
+ and returns escape sequences to normal characters.
+
+ @note It is preferred to call this over Unescape(BuildURI()) since
+ BuildUnescapedURI() performs some optimizations over the plain
+ method.
*/
- const wxChar* Create(const wxString uri);
+ wxString BuildUnescapedURI() const;
/**
- Note that on URIs with a "file" scheme wxURI does not
- parse the userinfo, server, or port portion. This is to keep
- compatability with wxFileSystem, the old wxURL, and older url specifications.
- */
+ Creates this URI from the @a uri string.
+
+ Returns the position at which parsing stopped (there is no such thing
+ as an "invalid" wxURI).
+ @param uri
+ String to initialize from.
+ */
+ const wxChar* Create(const wxString uri);
/**
Obtains the fragment of this URI.
-
- The fragment of a URI is the last value of the URI,
- and is the value after a '' character after the path
- of the URI.
-
- @c http://mysite.com/mypath#fragment
+
+ The fragment of a URI is the last value of the URI, and is the value
+ after a "#" character after the path of the URI.
+
+ @c "http://mysite.com/mypath#<fragment>"
*/
- const wxString GetFragment();
+ const wxString& GetFragment() const;
/**
- Obtains the host type of this URI, which is of type
- HostType():
-
-
- @b wxURI_REGNAME
-
-
- Server is a host name, or the Server component itself is undefined.
-
- @b wxURI_IPV4ADDRESS
-
-
- Server is a IP version 4 address (XXX.XXX.XXX.XXX)
-
- @b wxURI_IPV6ADDRESS
-
-
- Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX
-
- @b wxURI_IPVFUTURE
-
-
- Server is an IP address, but not versions 4 or 6
+ Obtains the host type of this URI, which is one of wxURIHostType.
*/
- const HostType GetHostType();
+ const wxURIHostType& GetHostType() const;
/**
- Returns the password part of the userinfo component of
- this URI. Note that this is explicitly depreciated by
- RFC 1396 and should generally be avoided if possible.
-
- @c http://user:password@mysite.com/mypath
+ Returns the password part of the userinfo component of this URI. Note
+ that this is explicitly depreciated by RFC 1396 and should generally be
+ avoided if possible.
+
+ @c "http://<user>:<password>@mysite.com/mypath"
*/
- const wxString GetPassword();
+ const wxString& GetPassword() const;
/**
Returns the (normalized) path of the URI.
-
- The path component of a URI comes
- directly after the scheme component
- if followed by zero or one slashes ('/'),
- or after the server/port component.
-
- Absolute paths include the leading '/'
- character.
-
- @c http://mysite.compath
+
+ The path component of a URI comes directly after the scheme component
+ if followed by zero or one slashes ('/'), or after the server/port
+ component.
+
+ Absolute paths include the leading '/' character.
+
+ @c "http://mysite.com<path>"
*/
- const wxString GetPath();
+ const wxString& GetPath() const;
/**
Returns a string representation of the URI's port.
-
- The Port of a URI is a value after the server, and
- must come after a colon (:).
-
- @c http://mysite.com:port
-
- Note that you can easily get the numeric value of the port
- by using wxAtoi or wxString::Format.
+
+ The Port of a URI is a value after the server, and must come after a
+ colon (:).
+
+ @c "http://mysite.com:<port>"
+
+ @note You can easily get the numeric value of the port by using
+ wxAtoi() or wxString::Format().
*/
- const wxString GetPort();
+ const wxString& GetPort() const;
/**
Returns the Query component of the URI.
-
- The query component is what is commonly passed to a
- cgi application, and must come after the path component,
- and after a '?' character.
-
- @c http://mysite.com/mypath?query
+
+ The query component is what is commonly passed to a cgi application,
+ and must come after the path component, and after a '?' character.
+
+ @c "http://mysite.com/mypath?<query>"
*/
- const wxString GetQuery();
+ const wxString& GetQuery() const;
/**
Returns the Scheme component of the URI.
-
- The first part of the uri.
-
- @c scheme://mysite.com
+
+ The first part of the URI.
+
+ @c "<scheme>://mysite.com"
*/
- const wxString GetScheme();
+ const wxString& GetScheme() const;
/**
Returns the Server component of the URI.
-
- The server of the uri can be a server name or
- a type of ip address. See
- GetHostType() for the
- possible values for the host type of the
- server component.
-
- @c http://server/mypath
+
+ The server of the URI can be a server name or a type of IP address. See
+ GetHostType() for the possible values for the host type of the server
+ component.
+
+ @c "http://<server>/mypath"
*/
- const wxString GetServer();
+ const wxString& GetServer() const;
/**
- Returns the username part of the userinfo component of
- this URI. Note that this is explicitly depreciated by
- RFC 1396 and should generally be avoided if possible.
-
- @c http://user:password@mysite.com/mypath
+ Returns the username part of the userinfo component of this URI. Note
+ that this is explicitly depreciated by RFC 1396 and should generally be
+ avoided if possible.
+
+ @c "http://<user>:<password>@mysite.com/mypath"
*/
- const wxString GetUser();
+ const wxString& GetUser() const;
/**
Returns the UserInfo component of the URI.
-
- The component of a URI before the server component
- that is postfixed by a '@' character.
-
- @c http://userinfo@mysite.com/mypath
+
+ The component of a URI before the server component that is postfixed by
+ a '@' character.
+
+ @c "http://<userinfo>@mysite.com/mypath"
*/
- const wxString GetUserInfo();
+ const wxString& GetUserInfo() const;
/**
Returns @true if the Fragment component of the URI exists.
*/
- bool HasFragment();
+ bool HasFragment() const;
/**
Returns @true if the Path component of the URI exists.
*/
- bool HasPath();
+ bool HasPath() const;
/**
Returns @true if the Port component of the URI exists.
*/
- bool HasPort();
+ bool HasPort() const;
/**
Returns @true if the Query component of the URI exists.
*/
- bool HasQuery();
+ bool HasQuery() const;
/**
Returns @true if the Scheme component of the URI exists.
*/
- bool HasScheme();
+ bool HasScheme() const;
/**
Returns @true if the Server component of the URI exists.
*/
- bool HasServer();
+ bool HasServer() const;
/**
Returns @true if the User component of the URI exists.
*/
- bool HasUser();
+ bool HasUser() const;
/**
- Returns @true if a valid [absolute] URI, otherwise this URI
- is a URI reference and not a full URI, and IsReference
- returns @false.
+ Returns @true if a valid [absolute] URI, otherwise this URI is a URI
+ reference and not a full URI, and this function returns @false.
*/
- bool IsReference();
+ bool IsReference() const;
/**
- To obtain individual components you can use
- one of the following methods
-
- GetScheme()
-
- GetUserInfo()
-
- GetServer()
-
- GetPort()
-
- GetPath()
-
- GetQuery()
-
- GetFragment()
-
- However, you should check HasXXX before
- calling a get method, which determines whether or not the component referred
- to by the method is defined according to RFC 2396.
-
- Consider an undefined component equivalent to a
- @NULL C string.
-
-
- HasScheme()
-
- HasUserInfo()
-
- HasServer()
-
- @ref hasserver() HasPort
-
- HasPath()
-
- HasQuery()
-
- HasFragment()
-
- Example:
- */
-
+ Inherits this URI from a base URI - components that do not exist in
+ this URI are copied from the base, and if this URI's path is not an
+ absolute path (prefixed by a '/'), then this URI's path is merged with
+ the base's path.
- /**
- Inherits this URI from a base URI - components that do not
- exist in this URI are copied from the base, and if this URI's
- path is not an absolute path (prefixed by a '/'), then this URI's
- path is merged with the base's path.
-
- For instance, resolving "../mydir" from "http://mysite.com/john/doe"
- results in the scheme (http) and server (mysite.com) being copied into
- this URI, since they do not exist. In addition, since the path
- of this URI is not absolute (does not begin with '/'), the path
- of the base's is merged with this URI's path, resulting in the URI
+ For instance, resolving "../mydir" from "http://mysite.com/john/doe"
+ results in the scheme (http) and server ("mysite.com") being copied
+ into this URI, since they do not exist. In addition, since the path of
+ this URI is not absolute (does not begin with '/'), the path of the
+ base's is merged with this URI's path, resulting in the URI
"http://mysite.com/john/mydir".
-
- @param base
- Base URI to inherit from. Must be a full URI and not a reference
-
- @param flags
- Currently either wxURI_STRICT or 0, in non-strict
- mode some compatibility layers are enabled to allow loopholes from RFCs prior
- to 2396
+
+ @param base
+ Base URI to inherit from. Must be a full URI and not a reference.
+ @param flags
+ Currently either wxURI_STRICT or 0, in non-strict mode some
+ compatibility layers are enabled to allow loopholes from RFCs prior
+ to 2396.
*/
void Resolve(const wxURI& base, int flags = wxURI_STRICT);
/**
- Translates all escape sequences (normal characters and returns the result.
-
- This is the preferred over deprecated wxURL::ConvertFromURI.
-
- If you want to unescape an entire wxURI, use BuildUnescapedURI() instead,
- as it performs some optimizations over this method.
-
- @param uri
- string with escaped characters to convert
+ Translates all escape sequences (normal characters and returns the
+ result.
+
+ If you want to unescape an entire wxURI, use BuildUnescapedURI()
+ instead, as it performs some optimizations over this method.
+
+ @param uri
+ String with escaped characters to convert.
*/
wxString Unescape(const wxString& uri);
/**
- Compares this URI to another URI, and returns @true if
- this URI equals
-
- @param uricomp, otherwise it returns @false.
-
- uricomp
- URI to compare to
+ Compares this URI to another URI, and returns @true if this URI equals
+ @a uricomp, otherwise it returns @false.
+
+ @param uricomp
+ URI to compare to.
*/
void operator ==(const wxURI& uricomp);
};
+
projects / wxWidgets.git / blobdiff