carb::ErrorApi

struct ErrorApi

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 Members

Error const *(*viewCurrentError)(Result *code)

Get a view of this thread’s current error, if it is set.

Warning

The caller does not own the returned error. Any information pointed to by the returned value can be altered or cleared by a function calling any of the setError calls on this thread. Errors accessed are meant to be acted upon immediately. If you wish to preserve information, copy the pieces you wish to save or store the whole thing with errorClone or takeCurrentError.

Param code: [out] If not nullptr and there is a current error, then *code will be set to the error code of the current error. Use this to save an extra call to getErrorInfo when you are going to act on the code value. If there is no current error, then this will be set to kResultSuccess.
Return: The current error, if it was set. If there is no error, this returns nullptr.

Error *(*takeCurrentError)(Result *code)

Get this thread’s current error as an owned object, if it is set. After this call, this thread’s current error will be cleared.

It is the caller’s responsibility to clean up the returned value, unless it is nullptr.

This function is equivalent to cloning the current error, then resetting it:

ErrorApi const& api = ErrorApi::instance();
Result code{}; // <- optimization only -- see viewCurrentError
Error* my_err = api.errorClone(api.viewCurrentError(&code));
api.setErrorTo(nullptr);

Param code: [out] If not nullptr and there is a current error, then *code will be set to the error code of the current error. Use this to save an extra call to getErrorInfo when you are going to act on the code value. If there is no current error, then this will be set to kResultSuccess.
Return: An owned version of the current error, if it was set. If there is no error, this returns nullptr.

Result (*setError)(Result code, char const *message, std::size_t message_size)

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.

Param code: The code for the created error, which callers can potentially act on.
Param message: The associated message containing additional details about the error. If this is nullptr, the default message for the code is used.
Param message_size: The number of bytes message is. If message is nullptr, this must be 0.
Retval kResultSuccess: when the error is set without issue.
Retval kResultInvalidArgument: if the message is nullptr and message_size is not 0 or if message is not nullptr and the message_size is 0. The current error will still be set to code, but the message will be the default for that code.
Retval kResultOutOfMemory: if 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.
Retval kResultTooMuchData: If 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.

Result (*setErrorTo)(Error *error)

Set this thread’s current error to the exact error or clear the current error if error is nullptr. Responsibility for this instance is taken by the error system, so you should not call errorRelease on it.

Param error: The error to set. If this is nullptr, this clears the current error.
Retval kResultSuccess: when the error is set without issue.
Retval kResultInvalidOperation: if error == viewCurrentError(). Restoring a previously-saved error should occur through a errorClone call, so doing this represents a bug in the code (note that you must have used const_cast or equivalent to get this to compile). In this case, no action is performed, as the current error is already set to the error.

void (*setErrorOom)(): Set this thread’s current error to a pre-allocated error indicating the system is out of memory. It will always succeed.

Result (*errorRelease)(Error *error)

Release the error which was previously errorCloned or errorCreated.

Retval kResultSuccess: when the error was released.
Retval kResultInvalidOperation: when error == viewCurrentError(). The current error does not need to be released.

Error *(*errorClone)(Error const *source)

Create a copy of the source error.

Param source: The error to clone from. If this is nullptr, nullptr will be returned without error.
Return: The cloned error. In case of error, nullptr is returned and the current error is set with a message containing additional details.

Error *(*errorCreate)(Result code, const char *message, std::size_t message_size)

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 nullptr and set the current error to the failure.

Param code: The code for the created error, which callers can potentially act on.
Param message: The associated message containing additional details about the error. If this is nullptr, the default message for the code is used.
Param message_size: The number of bytes message is.
Return: The created error on success. On failure, nullptr is returned and the current error is set with the reason for the failure. The code values are the same as setError.

Result (*getErrorInfo)(Error const *error, Result *code, char const **message, std::size_t *message_size)

Extract the information associated with the error message. The output parameters are views of the properties, so they are only valid as long as error is valid.

Param error: The source to extract data from. This can not be nullptr.
Param code: [out] If not nullptr, *code will be set to the code of this error.
Param message: [out] If not nullptr, *message will point to the error’s detail message.
Param message_size: [out] If not nullptr, *message_size will be set to the size of the error’s detail message. Note that *message is always null-terminated, but this is useful for optimization when copying.
Retval kResultSuccess: when the operation was successfully performed.
Retval kResultInvalidArgument: if error is nullptr. The current error is not set in this case (since the error can be current_error, we do not want to clear it for you.

Result (*getCodeDescription)(Result code, char const **name, std::size_t *name_size, char const **message, std::size_t *message_size)

Get the name and default message for the given code. The name 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".

Note that all of the output parameters are allowed to be nullptr. In this case, kResultSuccess is still returned. This can be useful for checking if a given code exists at all.

Param code: The error code to look up.
Param name: [out] A pointer to a place to put the name of the code. If this is nullptr, it will not be set.
Param name_size: [out] A pointer to place to put the size of name (in UTF-8 code units). Since name is null-terminated, this is not strictly needed, but can save you a strlen call. If this is nullptr, it will not be set.
Param message: [out] A pointer to the place to put the default message for this code. If this is nullptr, it will not be set.
Param message_size: [out] A pointer to the place to put the size of message (in UTF-8 code units). Since message is null-terminated, this is not strictly needed, but can save you a strlen call. If this is nullptr, it will not be set.
Retval kResultSuccess: when the operation was successfully performed.
Retval kResultNotFound: when code is not in the known list of error codes. The current error is not set.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc()

Returns information about this interface. Auto-generated by CARB_PLUGIN_INTERFACE(). *

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

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.