NetServices: Add the BNetworkRequestError type

This is a generic error type that can be used by multiple protocols to describe errors that can
occur while processing a request. The error type supports adding an additional error code in cases
where there is an underlying system error.

The type will be used to describe errors that occur while processing requests by BHttpSession, and
it is generally going to be thrown by the receiving BHttpResult.

Change-Id: I76c0bbaedd38df8cfb79159c4beae2fbf1350aab

docs/user/netservices/HttpResult.dox

@@ -101,7 +101,7 @@ namespace Network {
 	When there are errors during the request that lead to the situation where there is no valid
 	response according to the HTTP specification, then this object goes into an error state. This
 	means that the access methods of this object will throw an exception of the
-	\ref BNetServiceError type.
+	\ref BNetworkRequestError type.
 
 	A special property of this object is that it is unique. This means it cannot be copied, only
 	moved. Objects that have moved from, are in an invalid state, and will always raise a
@@ -275,7 +275,7 @@ namespace Network {
 
 	\exception BRuntimeException This exception is raised when the object has been moved from and
 		is thus no longer valid.
-	\exception BNetServicesError This exception is raised when there was an error that prevented
+	\exception BNetworkRequestError This exception is raised when there was an error that prevented
 		completely retrieving and parsing the HTTP response.
 
 	\since Haiku R1

docs/user/netservices/NetServicesDefs.dox

@@ -17,6 +17,16 @@ namespace BPrivate {
 namespace Network {
 
 
+/*!
+	\file NetServicesDefs.h
+	\ingroup netservices
+	\brief Various standardized error and notification types used by multiple protocols of the
+		Network Services Kit.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\class BUnsupportedProtocol
 	\ingroup netservices
@@ -29,7 +39,7 @@ namespace Network {
 /*!
 	\fn BUnsupportedProtocol::BUnsupportedProtocol(const char* origin,
 		BUrl url, BStringList supportedProtocols)
-	\brief Create a new error unsupported protocol error.
+	\brief Create a new unsupported protocol error.
 
 	\param origin A string representing where this error occured. It is advised
 		to initialize it to \c __PRETTY_FUNCTION__ by default.
@@ -121,6 +131,123 @@ namespace Network {
 */
 
 
+/*!
+	\class BNetworkRequestError
+	\ingroup netservices
+	\brief Error that indicates there was an issue executing the network request.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\enum BNetworkRequestError::ErrorType
+	\ingroup netservices
+	\brief A list of errors that can occur while executing a network request.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BNetworkRequestError::ErrorType BNetworkRequestError::HostnameError
+	\brief Error resolving the hostname.
+
+	\ref ErrorCode() will be set to contain the underlying error code.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BNetworkRequestError::ErrorType BNetworkRequestError::NetworkError
+	\brief The request was interrupted due to a network error.
+
+	This may occur when reading or writing fails due to an underlying network error, like an
+	unexpected closed connection.
+
+	\ref ErrorCode() will be set to contain the underlying error code.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BNetworkRequestError::ErrorType BNetworkRequestError::ProtocolError
+	\brief The request did not complete because the response did not conform to the protocol.
+
+	The server gave an unexpected or incorrect response. The network request could not complete
+	because of this.
+
+	There will not be any \ref ErrorCode() set.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BNetworkRequestError::ErrorType BNetworkRequestError::SystemError
+	\brief Other internal error while handling the request.
+
+	There could have been issues initializing buffers or decompression engines.
+
+	\ref ErrorCode() will be set to contain the underlying error code.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BNetworkRequestError::ErrorType BNetworkRequestError::Canceled
+	\brief The request was canceled before it was completed.
+
+	This could either have been done through the API, or because the session that schedules and
+	executes the requests was destroyed.
+
+	There will not be any \ref ErrorCode() set.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BNetworkRequestError::BNetworkRequestError(const char *origin, ErrorType type,
+		status_t errorCode=B_OK)
+	\brief Create a new network request error.
+
+	\param origin A string representing where this error occured. It is advised
+		to initialize it to \c __PRETTY_FUNCTION__ by default.
+	\param type The error type that describes what the issue was that prevented the completion of
+		the request.
+	\param error Optional underlying system error. See the \ref BNetworkRequestError::ErrorType
+		documentation on which error types expect a system error.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn status_t BNetworkRequestError::ErrorCode() const noexcept
+	\brief Get the underlying system error code.
+
+	\return A \c status_t error code when the associated \ref BNetworkRequestError::ErrorType sets
+		the system error, or \c B_OK if there is no additional error code available.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn ErrorType BNetworkRequestError::Type() const noexcept
+	\brief Get the error type.
+
+	\return Get the \ref BNetworkRequestError::ErrorType that describes the cause for the request
+		to fail.
+
+	\since Haiku R1
+*/
+
+
 } // namespace Network
 
 } // namespace BPrivate

headers/private/netservices2/NetServicesDefs.h

@@ -50,6 +50,31 @@ private:
 };
 
 
+class BNetworkRequestError : public BError {
+public:
+	enum ErrorType {
+		HostnameError,
+		NetworkError,
+		ProtocolError,
+		SystemError,
+		Canceled
+	};
+
+							BNetworkRequestError(const char* origin, ErrorType type,
+								status_t errorCode = B_OK);
+
+	virtual	const char*		Message() const noexcept override;
+	virtual	BString			DebugMessage() const override;
+
+			ErrorType		Type() const noexcept;
+			status_t		ErrorCode() const noexcept;
+
+private:
+			ErrorType		fErrorType;
+			status_t		fErrorCode = B_OK;
+};
+
+
 }
 
 }

src/kits/network/libnetservices2/NetServicesMisc.cpp

@@ -11,6 +11,9 @@
 using namespace BPrivate::Network;
 
 
+// #pragma mark -- BUnsupportedProtocol
+
+
 BUnsupportedProtocol::BUnsupportedProtocol(const char* origin,
 		BUrl url, BStringList supportedProtocols)
 	:
@@ -54,6 +57,9 @@ BUnsupportedProtocol::SupportedProtocols() const
 }
 
 
+// #pragma mark -- BInvalidUrl
+
+
 BInvalidUrl::BInvalidUrl(const char* origin, BUrl url)
 	:
 	BError(origin),
@@ -84,3 +90,60 @@ BInvalidUrl::Url() const
 {
 	return fUrl;
 }
+
+
+// #pragma mark -- BNetworkRequestError
+
+
+BNetworkRequestError::BNetworkRequestError(const char* origin, ErrorType type, status_t errorCode)
+	: BError(origin), fErrorType(type), fErrorCode(errorCode)
+{
+
+}
+
+
+const char*
+BNetworkRequestError::Message() const noexcept
+{
+	switch (fErrorType) {
+	case HostnameError:
+		return "Cannot resolving hostname";
+	case NetworkError:
+		return "Network error during operation";
+	case ProtocolError:
+		return "Protocol error";
+	case SystemError:
+		return "System error";
+	case Canceled:
+		return "Network request was canceled";
+	}
+	// Unreachable
+	return "Network request error";
+}
+
+
+BString
+BNetworkRequestError::DebugMessage() const
+{
+	BString debugMessage;
+	debugMessage << "[" << Origin() << "] " << Message();
+	if (fErrorCode != B_OK) {
+		debugMessage << "\n\tUnderlying System Error: " << fErrorCode << " ("
+			<< strerror(fErrorCode) << ")";
+	}
+	return debugMessage;
+}
+
+
+BNetworkRequestError::ErrorType
+BNetworkRequestError::Type() const noexcept
+{
+	return fErrorType;
+}
+
+
+status_t
+BNetworkRequestError::ErrorCode() const noexcept
+{
+	return fErrorCode;
+}