xref: /haiku/docs/user/netservices/ErrorsExt.dox (revision ec7d71e6129ca5c518a6ffe4c451b7432c7b4d7e)

/*
 * Copyright 2021 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
 *
 * Corresponds to:
 *		headers/os/support/ErrorsExt.h	hrev?????
 */


#if __cplusplus >= 201703L


/*!
	\file ErrorsExt.h
	\ingroup netservices
	\brief Defines advanced error types and error functions for the Network Services API.

	\since Haiku R1
*/


namespace BPrivate {

namespace Network {


/*!
	\class BError
	\ingroup netservices
	\brief Abstract base class for advanced error objects.

	This class defines the minimum interface for advanced error objects in
	modern parts of the Haiku API.

	The minimum definition of an error is that it contains an \em origin and
	a \em message. The origin should contain a string that helps a developer
	identify the origin of the error. Common practise is to pass the
	\c __PRETTY_FUNCTION__ from the place where the error is constructed, but
	subclasses can have their own definitions for the origin.

	The message is a freeform message that describes the exact error condition.
	While it is not meant as a user-facing message, when creating custom error
	objects, take into account that a user may be confronted with a message in
	situations where an application presents it to a user as a final resort.

	\note The advanced error objects are not used in the existing legacy Haiku
	Kits. They are being tested for use in the modern parts of the API and are
	therefore included in the network services kit.

	\since Haiku R1
*/


/*!
	\fn BError::BError(const char* error)
	\brief Constructor that sets the \a origin.

	\since Haiku R1
*/


/*!
	\fn BError::BError(BString origin)
	\brief Constructor that sets the \a origin.

	\since Haiku R1
*/


/*!
	\fn virtual BError::~BError() noexcept
	\brief Standard destructor.

	\since Haiku R1
*/


/*!
	\fn BError::BError(const BError& other)
	\brief Copy constructor.

	\since Haiku R1
*/


/*!
	\fn BError::BError(BError&& other) noexcept
	\brief Move constructor.

	\since Haiku R1
*/


/*!
	\fn BError& BError::operator=(const BError& other)
	\brief Copy assignment operator.

	\since Haiku R1
*/


/*!
	\fn BError& BError::operator=(BError&& other) noexcept
	\brief Move assignment operator.

	\since Haiku R1
*/


/*!
	\fn virtual const char* BError::Message() const noexcept = 0
	\brief Access the string representation of the message.

	Implementations should return a meaningful description of the error that
	occured. The primary target audience of these messages are developers, who
	(hopefully) see them during development, testing or in bug reports.
	However, if it makes sense to have the error messages be instructive to
	users too, then do not hesitate to do so.

	Implementations of this function should never return \c NULL.

	\since Haiku R1
*/


/*!
	\fn virtual const char* BError::Origin() const noexcept
	\brief Access the string representation of the origin of the error.

	The default implementation returns a pointer to the string that was set as
	the origin when this object was constructed.

	Implementations of this function should never return \c NULL.

	\since Haiku R1
*/


/*!
	\fn virtual	BString BError::DebugMessage() const
	\brief Retrieve a debug message that contains all info in this error.

	\code
	[Origin] Message of error
	\endcode

	\exception std::bad_alloc In the future this method may throw this
		exception when the memory for the debug message cannot be allocated.

	\return A \ref BString object that contains the debug message.

	\since Haiku R1
*/


/*!
	\fn void BError::WriteToStream(std::ostream& stream) const
	\brief Write the error description to an output stream.

	The default implementation will write the output of the \ref DebugMessage()
	method, and append a newline.

	\exception std::ios_base::failure Any error that is forwarded when writing
		to the \a stream.

	\since Haiku R1
*/


/*!
	\fn size_t BError::WriteToOutput(BDataIO* output) const
	\brief Write the error description to an output.

	The default implementation will use the output from \ref DebugMessage()
	and write it to the \a output, including a newline and the NUL that
	terminates the string.

	\exception BSystemError For any error that occurs when calling
		\ref BDataIO::Write()

	\returns The number of bytes that was written to \a output.

	\since Haiku R1
*/


/*!
	\class BRuntimeError
	\ingroup netservices
	\brief Advanced error object for runtime errors.

	A \ref BRuntimeError is a concrete advanced error object that is used for
	errors that happen during a program's execution and that by their nature
	are outside of the scope of the control of the program.

	Objects of this class store strings to the \em origin and the error
	\em message. This class can be used as an error class or as a base to
	create more specialized error types.

	\since Haiku R1
*/


/*!
	\fn BRuntimeError::BRuntimeError(const char* origin, const char* message)
	\brief Constructor for a new error object.

	\param origin A string representing where this error occured. It is advised
		to initialize it to \c __PRETTY_FUNCTION__ by default.
	\param message A string explaining the contents for the error. While it is
		generally geared towards the developer, it may be useful to make the
		error understandable by a user, as they may sometimes see it.

	\since Haiku R1
*/


/*!
	\fn BRuntimeError::BRuntimeError(const char* origin, BString message)
	\copydoc BRuntimeError::BRuntimeError(const char* origin, const char* message)
*/


/*!
	\fn BRuntimeError::BRuntimeError(BString origin, BString message)
	\copydoc BRuntimeError::BRuntimeError(const char* origin, const char* message)
*/


/*!
	\fn BRuntimeError::BRuntimeError(const BRuntimeError& other)
	\brief Copy constructor.

	\since Haiku R1
*/


/*!
	\fn BRuntimeError::BRuntimeError(BRuntimeError&& other) noexcept
	\brief Move constructor.

	\since Haiku R1
*/


/*!
	\fn BRuntimeError& BRuntimeError::operator=(const BRuntimeError& other)
	\brief Copy assignment operator.

	\since Haiku R1
*/


/*!
	\fn BRuntimeError& BRuntimeError::operator=(BRuntimeError&& other) noexcept
	\brief Move assignment operator.

	\since Haiku R1
*/


/*!
	\fn virtual	const char* BRuntimeError::Message() const B_CXX_NOEXCEPT B_CXX_OVERRIDE
	\brief Get a pointer to the message describing the runtime error.
*/


/*!
	\class BSystemError
	\ingroup netservices
	\brief Advanced error object that wrap low-level system errors.

	A \ref BSystemError is a concrete advanced error object that is used to
	wrap tradition errors that are usually returned as a \c status_t. This type
	takes the system error, and adds an \em origin specifier.

	\since Haiku R1
*/


/*!
	\fn BSystemError::BSystemError(const char* origin, status_t error)
	\brief Create an object for \a error code with a specified \a origin.

	\param origin A string representing where this error occured. As this
		object usually wraps around a lower level API call, this should
		usually be the call that the error code originated from.
	\param error The error code.

	\since Haiku R1
*/


/*!
	\fn BSystemError::BSystemError(BString origin, status_t error)
	\copydoc BSystemError::BSystemError(const char* origin, status_t error)
*/


/*!
	\fn BSystemError::BSystemError(const BSystemError& other)
	\brief Copy constructor.

	\since Haiku R1
*/


/*!
	\fn BSystemError::BSystemError(BSystemError&& other) noexcept
	\brief Move constructor.

	\since Haiku R1
*/


/*!
	\fn BSystemError& BSystemError::operator=(const BSystemError& other)
	\brief Copy assignment.

	\since Haiku R1
*/


/*!
	\fn BSystemError& BSystemError::operator=(BSystemError&& other) noexcept
	\brief Move assignment operator.

	\since Haiku R1
*/


/*!
	\fn virtual const char* BSystemError::Message() const B_CXX_NOEXCEPT B_CXX_OVERRIDE
	\brief Access the string representation of the message.

	This returns the value of \c strerror() for the error code.

	\since Haiku R1
*/


/*!
	\fn virtual BString BSystemError::DebugMessage() const B_CXX_OVERRIDE
	\brief Retrieve a debug message that contains all info in this error.

	\code
	[Origin] Message of error (error code)
	\endcode

	\exception std::bad_alloc In the future this method may throw this
		exception when the memory for the debug message cannot be allocated.

	\return A \ref BString object that contains the debug message.

	\since Haiku R1
*/


/*!
	\fn status_t BSystemError::Error() B_CXX_NOEXCEPT
	\brief Get the error code for this error.

	\since Haiku R1
*/


} // namespace Network

} // namespace BPrivate

#endif