IError#

Fully qualified name: carb::IError

class IError#

The low-level API for interacting with the Carbonite error handling system. At the core, this system maintains a thread-specific error code and optional error message.

The state of the error objects are maintained through libcarb.so/carb.dll, the API is accessed through carbGetErrorApi or ErrorApi::instance. Different versions of the API interact with the same global state. A call to ErrorApi::viewCurrentError with version 1.0 will still be able to read a ErrorApi::setError from a version 4.0 API (version 4.0 does not exist at this time).

Subclassed by carb::ErrorApi

Public Functions

virtual ErrorPtr viewCurrentError() const noexcept = 0#

Access the current thread’s Error, if any.

Note: the error remains set for the current thread. In order to clear the error after viewing it, call ErrorApi::clearError or setError with nullptr.

Returns:: The valid Error object if one is set for the current thread, otherwise an empty ErrorPtr.

virtual void setError(ErrorPtr error) const noexcept = 0#

Set this thread’s current error to the exact given error or clear the current error if error is empty.

Parameters:: error – The error to set. If this is empty, this clears the current error.

virtual void setErrorOom() const noexcept = 0#: Set this thread’s current error to a pre-allocated error indicating the system is out of memory. It will always succeed.

virtual omni::expected<void, ErrorCode> setError( ErrorCode code, cpp::string_view message = {}, ) const noexcept = 0#

Set this thread’s current error to a pre-formatted string.

In the case of any error of a call to this function, the current error will always be set with code. However, the associated message of the error will be the default for that code.

Possible returned ErrorCodes

kInvalidArgument - A default-constructed code was given (or ErrorCode::kOutOfMemory), but with a non-empty message. The code is still set as the current error but message is ignored.
kResultOutOfMemory - the message is too large to fit in the string buffer, but the call to allocate memory failed. The current error is still set to code, but the error message is saved as the default for that code.
kResultTooMuchData - the provided message is too large to fit in any error message buffer (the current maximum is 64 KiB). The current error will be set with a truncated version of the provided message.

Parameters:

code – The code for the created error, which callers can potentially act on.
message – The associated message containing additional details about the error. If empty, the default default message for code is used. A non-empty message is not allowed for kOutOfMemory or a default-constructed code.

Returns:

void on success; if an error occurs while setting the current error, an omni::unexpected is returned with the ErrorCode.

virtual omni::expected<ErrorPtr, ErrorCode> errorCreate( ErrorCode code, cpp::string_view message = {}, ) const noexcept = 0#

Create an error message with the code and pre-formatted message string without setting the current error.

The parameters operate similarly to setError, but are more strict. Where setError would return a non-OK code but still set the current error, this function would return omni::unexpected with the error.

Possible return ErrorCode values

ErrorCode::kInvalidArgument - a default-constructed code was provided, or ErrorCode::kOutOfMemory was given with a non-empty message.

Parameters:

code – The code for the created error, which callers can potentially act on. This does not have to be a pre-defined ErrorCode value.
message – The associated message containing additional details about the error.

Returns:

The created error on success. On failure, omni::unexpected with an ErrorCode is returned giving the reason for the failure.

virtual cpp::optional<std::pair<cpp::zstring_view, cpp::zstring_view>> getCodeDescription( ErrorCode code, ) const noexcept = 0#

Retrieve the name and default message for the given code.

The name is a symbol-like name in snake case like "invalid_argument". The message is the default message for the code as a sentence fragment like "invalid argument".

Possible ErrorCode return values

kResultNotFound if code is not in the known list of error codes.

Note

The current error is not changed.

Parameters:: code – The ErrorCode to look up.
Returns:: A optional containing a std::pair<name, message> on success, where name and message are of type carb::cpp::zstring_view. If the code is not a known default ErrorCode, carb::cpp::nullopt is returned instead.

virtual ErrorCode currentError( cpp::zstring_view *outMessage = nullptr, ) const noexcept = 0#

A simple helper function to retrieve the ErrorCode stored by the current thread.

Parameters:: outMessage – If not nullptr, will receive the error message stored by the current thread. If no error message is stored by the current thread, this will receive an empty zstring_view. This view is valid until the error stored by the current thread changes.
Returns:: The ErrorCode stored by the current thread. If no ErrorCode is stored by the current thread, This will be a default-constructed ErrorCode.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc( ) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc( ) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about the latest version of this interface.