NetServices: Implement BHttpStatusCode, BHttpStatusClass and Redirects

The user of the API can set whether redirects should be followed, and if so,
how many. This is part of the BHttpRequest API. The BHttpSession then follows
those instructions, and executes the maximum number of redirects the user
would like to follow.

As part of this commit, the BHttpStatusClass and BHttpStatusCodes helper enums
have been added, to give a friendlier access to HTTP status codes and status
classes.

Change-Id: Ic8c9e3fda158e2cce549c8f1d360951f7ac83311

docs/user/netservices/HttpRequest.dox

@@ -227,6 +227,19 @@ namespace Network {
 */
 
 
+/*!
+	\fn bool BHttpMethod::operator!=(const Verb &other) const noexcept
+	\brief Comparison operator.
+
+	\param other The verb to compare to.
+
+	\retval true This method is different from \a other.
+	\retval false This method is equal to \a other.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn const std::string_view BHttpMethod::Method() const noexcept
 	\brief Get a string representation of the method.
@@ -249,7 +262,7 @@ namespace Network {
 
 
 /*!
-	\fn BHttpMethod& BPrivate::Network::BHttpMethod::operator=(const BHttpMethod &other)
+	\fn BHttpMethod& BHttpMethod::operator=(const BHttpMethod &other)
 	\brief Copy assignment.
 
 	Copy data from an \a other object.
@@ -261,6 +274,40 @@ namespace Network {
 */
 
 
+/*!
+	\struct BHttpRedirectOptions
+	\ingroup netservices
+	\brief Describe redirection options for a \ref BHttpRequest.
+
+	\see These options are used by \ref BHttpRequest::Redirect() and
+		\ref BHttpRequest::SetRedirect()
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var bool BHttpRedirectOptions::followRedirect
+	\brief Describe whether the request should follow redirects.
+
+	\see These options are used by \ref BHttpRequest::Redirect() and
+		\ref BHttpRequest::SetRedirect()
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var uint8 BHttpRedirectOptions::maxRedirections
+	\brief The maximum number of redirects that should be followed.
+
+	\see These options are used by \ref BHttpRequest::Redirect() and
+		\ref BHttpRequest::SetRedirect()
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\class BHttpRequest
 	\ingroup netservices
@@ -288,6 +335,12 @@ namespace Network {
 			<td> The HTTP method for the request </td>
 			<td> Defaults to \ref BHttpMethod::Get </td>
 		</tr>
+		<tr>
+			<td> \ref Redirect() </td>
+			<td> \ref SetRedirect() </td>
+			<td> Whether redirects should be followed, and if so, how many </td>
+			<td> By default redirects are followed, up to 8 redirects for one request </td>
+		</tr>
 	</table>
 
 	\since Haiku R1
@@ -430,6 +483,16 @@ namespace Network {
 */
 
 
+/*!
+	\fn const BHttpRedirectOptions& BHttpRequest::Redirect() const noexcept
+	\brief Get the current redirection options for this request.
+
+	\see \ref BHttpRequest::SetRedirect() for details on the options.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn const BUrl& BHttpRequest::Url() const noexcept
 	\brief Get the current Url for the request.
@@ -468,6 +531,30 @@ namespace Network {
 */
 
 
+/*!
+	\fn void BHttpRequest::SetRedirect(const BHttpRedirectOptions &redirectOptions)
+	\brief Set the redirection options for this request.
+
+	The HTTP protocol allows the server to redirect requests if the resources have moved to a new
+	location. For your convenience, you can instruct the network services kit to follow these
+	redirections.
+
+	The \ref BHttpRedirectOptions allows you to set what the redirection policy should be. You can
+	set whether redirects should be followed at all, and if so, how many redirects should be
+	followed. The maximum value is that of an unsigned 8 bit int, so maximum is 256 redirects. This
+	prevents the request from staying stuck in a redirection loop.
+
+	If redirects are disabled, or the maximum number of redirects have been processed, then the
+	response will be set to the actual (last) received redirection response.
+
+	\param redirectOptions The options for redirections.
+
+	\exception std::bad_alloc This exception may be raised if it is impossible to allocate memory.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn void BHttpRequest::SetUrl(const BUrl &url)
 	\brief Set the \a url for this request.

docs/user/netservices/HttpResult.dox

@@ -28,6 +28,18 @@ namespace BPrivate {
 namespace Network {
 
 
+/*!
+	\enum BHttpStatusClass
+	\brief Category of the HTTP response status code.
+*/
+
+
+/*!
+	\enum BHttpStatusCode
+	\brief Enumeration of standardized HTTP status codes.
+*/
+
+
 /*!
 	\struct BHttpStatus
 	\ingroup netservices
@@ -74,6 +86,28 @@ namespace Network {
 */
 
 
+/*!
+	\fn BHttpStatusClass BHttpStatus::StatusClass() const noexcept
+	\brief Map the \ref code value to a \ref BHttpStatusClass value
+
+	\return One of the valid values of \ref BHttpStatusClass, or \c BHttpStatusClass::Invalid if
+		the return code cannot be maped.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpStatusCode BHttpStatus::StatusCode() const noexcept
+	\brief Map the \ref code value to a \ref BHttpStatusCode value
+
+	\return One of the valid values of \ref BHttpStatusCode, or \c BHttpStatusCode::Unknown if
+		the return code cannot be maped.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\struct BHttpBody
 	\ingroup netservices