ErrorApi

Fully qualified name: carb::ErrorApi

Defined in carb/Error.h

struct ErrorApi : public carb::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).

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 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 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<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 ErrorApi const &instance() noexcept

Get the singleton instance of this API.

The implementation of this is backed by libcarb.so/carb.dll, so it is a singleton instance for all loaded modules. This function is backed by carbGetErrorApi with the version argument provided with the value of the API version the calling module was built against.

static inline void clearError() noexcept

Clears any error stored for the current thread.

Post:

IError::viewCurrentError() returns an empty ErrorPtr.

static inline ErrorCode getError(

cpp::zstring_view *outMessage = nullptr,

) noexcept

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.

static inline ErrorCode convertFromErrno(

extras::ErrnoType err = errno,

std::string *message = nullptr,

)

Converts the current thread’s errno value to an ErrorCode.

The following table is a mapping of errno values to ErrorCode codes:

Mapping of errno value to Result codes

errno values	carb::ErrorCode
0	carb::ErrorCode{}
ENOSYS	carb::ErrorCode::kNotImplemented
EACCES	carb::ErrorCode::kAccessDenied
ENOMEM	carb::ErrorCode::kOutOfMemory
EINVAL	carb::ErrorCode::kInvalidArgument
EAGAIN	carb::ErrorCode::kTryAgain
EWOULDBLOCK	carb::ErrorCode::kTryAgain
EINTR	carb::ErrorCode::kInterrupted
EEXIST	carb::ErrorCode::kAlreadyExists
EPERM	carb::ErrorCode::kInvalidOperation
ENOENT	carb::ErrorCode::kNotFound
Everything else	carb::ErrorCode::kFail

Note

The value of errno remains consistent across the call to this function.

Parameters:

• err – An errno value. If not specified, the current value from errno itself will be used.

• message – [out] An optional std::string* that will receive the error description for the current errno value as via strerror. If the errno value is 0 the string will be cleared.

static inline void setFromErrno()

Sets the current thread’s error code value based on the value of errno.

Note

The value of errno remains consistent across the call to this function.

static ErrorCode convertFromWinApiErrorCode(

DWORD err = ::GetLastError(),

std::string *message = nullptr,

)

(Windows only) Converts the error code from GetLastError() to a omni::core::Result.

The following table is a mapping of Windows error values to omni::core::Result codes:

Mapping of Windows error value to Result code

errno values	omni::core::Result
ERROR_SUCCESS	carb::ErrorCode{}
ERROR_PATH_NOT_FOUND	carb::ErrorCode::kNotFound
ERROR_FILE_NOT_FOUND	carb::ErrorCode::kNotFound
ERROR_ACCESS_DENIED	carb::ErrorCode::kAccessDenied
ERROR_ALREADY_EXISTS	carb::ErrorCode::kAlreadyExists
ERROR_FILE_EXISTS	carb::ErrorCode::kAlreadyExists
ERROR_OUTOFMEMORY	carb::ErrorCode::kOutOfMemory
ERROR_NO_MORE_FILES	carb::ErrorCode::kNoMoreItems
ERROR_NO_MORE_ITEMS	carb::ErrorCode::kNoMoreItems
ERROR_NOT_IMPLEMENTED	carb::ErrorCode::kNotImplemented
ERROR_WAIT_TIMEOUT	carb::ErrorCode::kTryAgain
ERROR_ERROR_TIMEOUT	carb::ErrorCode::kTryAgain
Everything else	carb::ErrorCode::kFail

Note

The value of GetLastError remains consistent across the call to this function.

Parameters:

• err – The value from GetLastError() to convert. If not specified, the current value from GetLastError() will be used.

• message – [out] An optional std::string* that will receive the Windows formatted error description for the current error code. If GetLastError reports ERROR_SUCCESS this will be cleared.

Returns:

The omni::core::Result mapped from the windows error code.

static void setFromWinApiErrorCode()

(Windows only) Sets the current thread’s error code value based on the value of GetLastError().

See convertFromWinApiErrorCode for the error mapping.

Note

The value of GetLastError remains consistent across the call to this function.

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.