Add some documentation for BUrl.

Change-Id: I9db68f77d80c246fce5011247471972c3f1bf68a
Reviewed-on: https://review.haiku-os.org/c/haiku/+/1419
Reviewed-by: Niels Sascha Reedijk <[email protected]>
This commit is contained in:
Naba7
2019-12-09 19:00:20 +00:00
committed by Niels Sascha Reedijk
parent b84574958d
commit a8edaa2b21
+211 -295
View File
@@ -3,489 +3,405 @@
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Name, email@email.com * Nabanita Dash, dashnabanita@gmail.com
*
* Proofreaders:
* Adrien Destugues, [email protected]
* *
* Corresponds to: * Corresponds to:
* headers/os/support/Url.h hrev52332 * headers/os/support/Url.h hrev52332
* src/kits/support/Url.cpp hrev52332 * src/kits/support/Url.cpp hrev52332
*/ */
/*! /*!
\file Url.h \file Url.h
\ingroup support \ingroup support
\brief Undocumented file. \ingroup libbe
\brief Provides the BUrl class
\since Haiku R1 \since Haiku R1
*/ */
/*! /*!
\class BUrl \class BUrl
\ingroup support \ingroup support
\ingroup libbe \ingroup libbe
\brief Undocumented class. \brief Represents and manipulates an URL (Uniform Resource Locator).
\since Haiku R1 \since Haiku R1
An "Uniform Resource Locator" identifies a place where a resource can
be found. It specifies both a location and a mechanism to retrieve the
data. For example, http://www.example.com/index.html indicates a protocol
(http), a hostname (www.example.com), and a file name (index.html).
Every URL consists of a sequence of up to five components:
protocol, authority (consisting of login and password, hostname and port)
path, request and fragment.
The format is provided in RFC3986 (URI generic syntax), Appendix B as a regular expression:
^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\\?([^#]*))?(#(.*))?
This regular expression makes it possible to parse any string as an URL (if there are no
special characters to spearate the fields, everything will end up in the path compopent).
However, some characters are not allowed: space, newlines, tabs, <, > and ". If any of these
is present in the URL string, the parsing results in an empty URL.
The protocols (http, https, ftp, irc, etc) identifies which way the resource
can be accessed.
Authority consists of userinfo such as username and password, a host
subcomponent consisting of IP address or hostname and a port subcomponent.
The path component locates the resource inside the authority's hierarchy,
and can have different formats (for example, directory names separated by
slashes) depending on the protocol in use.
The request component (preceeded by a question mark) contains a query
string of non-hierarchial data.
The fragment contains a fragment identifier providing direction to a
secondary resource, usually an identifier for a specific element into the
resource such as a paragraph in a text.
*/ */
//! @{
/*! /*!
\fn BUrl::BUrl(const char *url) \fn BUrl::BUrl(const char* url);
\brief Undocumented public method \brief Constructs a BUrl and fills it.
\param url Undocumented \param url A string to parse and populate the URL fields from.
\return Undocumented Call InitCheck() to verify that the string was succesfully parsed and
\retval <value> Undocumented resulted in a valid URL.
\since Haiku R1
*/ */
/*! /*!
\fn BUrl::BUrl(BMessage *archive) \fn BUrl::BUrl(BMessage* archive);
\brief Undocumented public method \brief Restore an URL from archived data.
\param archive Undocumented \param archive An archived BUrl (using BArchive()).
\return Undocumented Usually, archived messages are restored using BArchivable::Unarchive()
\retval <value> Undocumented which will automatically instanciate the correct class.
\since Haiku R1
*/ */
/*! /*!
\fn BUrl::BUrl(const BUrl &other) \fn BUrl::BUrl(const BUrl& other);
\brief Undocumented public method \brief Copy constructor
\param other Undocumented \param other A BUrl object to copy.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl::BUrl(const BUrl &base, const BString &relative) \fn BUrl::BUrl(const BUrl& base, const BString& relative);
\brief Undocumented public method \brief Construct a BUrl using a known base and a string representing a relative URL.
\param base Undocumented \param base A BUrl object that holds base URL.
\param relative Undocumented \param relative A path relative to the base URL.
\return Undocumented URLs can sometimes be represented in relative form. For example, links in
\retval <value> Undocumented a webpage may refer to only a path, assuming the same protocol and authority
are the same as the current page. This constructor applies the required
resolution process to construct a complete, standalone URL from such a
string.
\since Haiku R1 For example, the following:
BUrl base("http://example.org/path/page.html");
BUrl relative(base, "sudirectory/otherpage.html");
results in:
"http://example.org/path/subdirectory/otherpage.hhtml"
The relative URL can override any of the fields from the original one. The algorithm
for resolution is documented in RFC3986 section 5.
*/ */
/*! /*!
\fn BUrl::BUrl(const BPath &path) \fn BUrl::BUrl(const BPath& path);
\brief Undocumented public method \brief Constructs a BUrl identifying a local file.
\param path Undocumented \param path The path to convert into an URL
\return Undocumented The generated URL uses the file protocol, and its path component is the
\retval <value> Undocumented path given as a parameter.
\since Haiku R1
*/ */
/*! /*!
\fn BUrl::BUrl() \fn BUrl::BUrl();
\brief Undocumented public method \brief Constructs an empty BUrl.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn virtual virtual BUrl::~BUrl() \fn BUrl::~BUrl();
\brief Undocumented public method \brief Destructor for BUrl.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
//! @}
//! @{
/*! /*!
\fn BUrl& BUrl::SetUrlString(const BString &url) \fn BUrl& BUrl::SetUrlString(const BString& url);
\brief Undocumented public method \brief Parse a string and set the URL accordingly
\param url Undocumented \param url A string to parse as an absolute URL.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetProtocol(const BString &scheme) \fn BUrl& BUrl::SetProtocol(const BString& scheme);
\brief Undocumented public method \brief Set the protocol
\param scheme Undocumented \param scheme The protocol to use.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetUserName(const BString &user) \fn BUrl& BUrl::SetUserName(const BString& user);
\brief Undocumented public method \brief Set the username in the authority component
\param user Undocumented \param user The username.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetPassword(const BString &password) \fn BUrl& BUrl::SetPassword(const BString& password);
\brief Undocumented public method \brief Set the password in the authority component
\param password Undocumented \param password The password.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn void BUrl::SetAuthority(const BString &authority) \fn void BUrl::SetAuthority(const BString& authority);
\brief Undocumented public method \brief Replace the complete authority component
\param authority Undocumented \param authority The authority component.
\since Haiku R1 The username, password, host and port fields are replaced. The authority
can be of the form username:password@host:port
*/ */
/*! /*!
\fn BUrl& BUrl::SetHost(const BString &host) \fn BUrl& BUrl::SetHost(const BString& host);
\brief Undocumented public method \brief Sets the host part of the authority component.
\param host Undocumented \param host The hostname or address to use.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetPort(int port) \fn BUrl& BUrl::SetPort(int port);
\brief Undocumented public method \brief Set the port of the authority component
\param port Undocumented \param port The port number to use (usually a TCP or UDP port).
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetPath(const BString &path) \fn BUrl& BUrl::SetPath(const BString& path);
\brief Undocumented public method \brief Set the path of the URL.
\param path Undocumented \param path Set the path to use.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetRequest(const BString &request) \fn BUrl& BUrl::SetRequest(const BString& request);
\brief Undocumented public method \brief Set the request part of the URL.
\param request Undocumented \param request The request string.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn BUrl& BUrl::SetFragment(const BString &fragment) \fn BUrl& BUrl::SetFragment(const BString& fragment);
\brief Undocumented public method \brief Set the fragment part of the URL.
\param fragment Undocumented \param fragment The fragment to use.
\return Undocumented
\retval <value> Undocumented
\since Haiku R1
*/ */
//! @}
//! @{
/*! /*!
\fn const BString& BUrl::UrlString() const \fn const BString& BUrl::UrlString() const;
\brief Undocumented public method \brief Returns the string representation of the URL.
\return Undocumented \returns the string representation of the URL.
\retval <value> Undocumented
\since Haiku R1 A complete URL string is of the form protocol://username:passord@host:port/path?request#fragment . All the fields are optional, for example a file URL will
have only a protocol and a path.
*/ */
/*! /*!
\fn const BString& BUrl::Protocol() const \fn const BString& BUrl::Protocol() const;
\brief Undocumented public method \brief Returns the protocol used in the url.
\return Undocumented \returns The URL protocol.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn const BString& BUrl::UserName() const \fn const BString& BUrl::UserName() const;
\brief Undocumented public method \brief Returns the username.
\return Undocumented \returns The username.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn const BString& BUrl::Password() const \fn const BString& BUrl::Password() const;
\brief Undocumented public method \brief Returns the password.
\return Undocumented \returns The password.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn const BString& BUrl::UserInfo() const \fn const BString& BUrl::UserInfo() const;
\brief Undocumented public method \brief Returns the user information (username:password)
\return Undocumented \returns The username and password.
\retval <value> Undocumented
\since Haiku R1 If there is no password, the username alone is returned. If there is no
username, a string of the form ":password" is returned.
*/ */
/*! /*!
\fn const BString& BUrl::Host() const \fn const BString& BUrl::Host() const;
\brief Undocumented public method \brief Returns the URL host component.
\return Undocumented \returns The URL host.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn int BUrl::Port() const \fn int BUrl::Port() const;
\brief Undocumented public method \brief Returns the URL port number.
\return Undocumented \returns The URL port number.
\retval <value> Undocumented
\since Haiku R1 -1 is returned if no port is set.
*/ */
/*! /*!
\fn const BString& BUrl::Authority() const \fn const BString& BUrl::Authority() const;
\brief Undocumented public method \brief Returns the authority url as a string.
\return Undocumented \returns The authority url as a string.
\retval <value> Undocumented
\since Haiku R1 The authority is of the form username:password@host:port.
*/ */
/*! /*!
\fn const BString& BUrl::Path() const \fn const BString& BUrl::Path() const;
\brief Undocumented public method \brief Returns the url path.
\return Undocumented \returns The url-path.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn const BString& BUrl::Request() const \fn const BString& BUrl::Request() const;
\brief Undocumented public method \brief Returns the url-request.
\return Undocumented \returns The url-request as a string.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn const BString& BUrl::Fragment() const \fn const BString& BUrl::Fragment() const;
\brief Undocumented public method \brief Returns the fragment of the url.
\return Undocumented \returns The fragment of the url as a string.
\retval <value> Undocumented
\since Haiku R1
*/ */
//! @}
//! @{
/*! /*!
\fn bool BUrl::IsValid() const \fn bool BUrl::IsValid() const;
\brief Undocumented public method \brief Check if the URL is valid.
\return Undocumented \returns true if the URL is valid.
\retval <value> Undocumented
\since Haiku R1 This function verifies that the mandatory fields are present and perform
some other sanity checks on the URL.
An URL is valid if:
- It has a protocol, starting with an alphabetic character and folowed by alphanumeric or +, -,
or . characters exclusively,
- If the protocol requires one, there is a valid host,
- If the protocol requires one, there is a path.
- If there is a host, it is either an IPv4 address or valid DNS name, or an IPv6 address
enclosed in brackets
An invalid URL can still be modified using the various setters to turn it into a valid one.
*/ */
/*! /*!
\fn bool BUrl::HasProtocol() const \fn bool BUrl::HasProtocol() const;
\brief Undocumented public method \brief Check wether the URL has a protocol.
\return Undocumented \returns True if the URL has a protocol.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasUserName() const \fn bool BUrl::HasUserName() const;
\brief Undocumented public method \brief Check wether the URL has an username.
\return Undocumented \returns True if the URL has an username.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasPassword() const \fn bool BUrl::HasPassword() const;
\brief Undocumented public method \brief Check wether the URL has a password.
\return Undocumented \returns True if the URL has a password.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasUserInfo() const \fn bool BUrl::HasUserInfo() const;
\brief Undocumented public method \brief Check wether the URL has user information.
\return Undocumented \returns True if the URL has an username or password.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasHost() const \fn bool BUrl::HasHost() const;
\brief Undocumented public method \brief Check wether the URL has an host.
\return Undocumented \returns True if the URL has an host.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasPort() const \fn bool BUrl::HasPort() const;
\brief Undocumented public method \brief Check wether the URL has a port.
\return Undocumented \returns True if the URL has a port.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasAuthority() const \fn bool BUrl::HasAuthority() const;
\brief Undocumented public method \brief Check if the URL has an host or port.
\return Undocumented \returns True if the URL has an host or port.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasPath() const \fn bool BUrl::HasPath() const;
\brief Undocumented public method \brief Check wether the URL has a path.
\return Undocumented \returns True if the URL has a path.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasRequest() const \fn bool BUrl::HasRequest() const;
\brief Undocumented public method \brief Check wether the URL has a request.
\return Undocumented \returns True if the URL has a request.
\retval <value> Undocumented
\since Haiku R1
*/ */
/*! /*!
\fn bool BUrl::HasFragment() const \fn bool BUrl::HasFragment() const;
\brief Undocumented public method \brief Check wether the URL has a fragment.
\return Undocumented \returns True if the URL has a fragment.
\retval <value> Undocumented
\since Haiku R1
*/ */
//! @}
/*! /*!
\fn void BUrl::UrlEncode(bool strict=false) \fn void BUrl::UrlEncode(bool strict=false)