Status Codes

<amongoc/status.h> (header file)

Types and functions for handling generic status codes

Types

struct amongoc_status

An augmented status code object.

Note

This API is inspired by the C++ std::error_code API

Zero-initialized:

A zero-initialized amongoc_status has no defined semantics. If you want a default “okay” status, use amongoc_okay. To create a constant-initialized okay status, use {&amongoc_generic_category, 0} as an initializer.

const amongoc_status_category_vtable *category

Pointer to a virtual method table for status categories. This pointer can be compared against the address of known categories to check the category of the status.

See also

Built-In amongoc Categories

int code

The actual status code. The semantics of this value depend on the category of the error.

Important

DO NOT assume that a non-zero value represents an error, as the status category may define more than one type of success value. Use amongoc_is_error() to check whether a status represents an error.

static amongoc_status from(std::error_code) noexcept

static amongoc_status from(std::errc) noexcept

std::error_code as_error_code() const noexcept

(C++ API) Construct a new amongoc_status from a std::error_code, or convert an existing amongoc_status to a C++ std::error_code

Warning

This conversion is potentially lossy, as the category of the status/error code might not have an equivalent category in the target representation. This method should only be used on status values that are know to have a category belonging to amongoc (See: Built-In amongoc Categories).

It is recommended to keep to using amongoc_status whenever possible.

std::string message() const noexcept

C API:

amongoc_status_strdup_message()

bool is_error() const noexcept

C API:

amongoc_is_error()

Functions & Macros

bool amongoc_is_error(amongoc_status st)

Test whether the given status st represents an error condition.

Parameters:

st – The statust to be checked

Returns:

true if st represents an error.

Returns:

false otherwise.

Note

The defintion of what constitutes an error depends on the amongoc_status::category.

bool amongoc_is_cancellation(amongoc_status st)

Test whether the given status st represents a cancellation.

Parameters:

st – The status to be checked.

Returns:

true if st represents a cancellation.

Returns:

false otherwise.

Note

The defintion of what constitutes a cancellation depends on the amongoc_status::category.

bool amongoc_is_timeout(amongoc_status st)

Test whether the given status st represents an operation timeout.

Parameters:

st – The status to be checked.

Returns:

true if st represents a timeout.

Returns:

false otherwise.

Note

The defintion of what constitutes a timeout depends on the amongoc_status::category.

char *amongoc_status_strdup_message(amongoc_status)

Obtain a dynamically allocated C string that describes the status in human-readable form.

Important

The returned string must be freed with free()

C++ API:

amongoc_status::message()

const amongoc_status amongoc_okay

A generic status with a code zero. This represents a generic non-error status.

Note

This is implemented as a C preprocessor macro.

Status Categories

struct amongoc_status_category_vtable

A virtual-method table for amongoc_status that defines the semantics of status codes. The following “methods” are actually function pointers that may be customized by the user to provide new status code behaviors.

Customization Points

const char *name()

Returns:

Must return a statically-allocated null-terminated string that uniquely identifies the category.

char *strdup_message(int code)

Parameters:

code – The integer status code from amongoc_status::code

Returns:

Must return a dynamically allocated null-terminated string that describes the status in a human-readable format. The returned string will be freed with free().

bool is_error(int code) [[optional]]

Parameters:

code – The integer status code from amongoc_status::code

Returns:

Should return true if-and-only-if the integer value of code represents a non-success state (this includes cancellation and timeout).

Note

If this function is not defined, amongoc_is_error() returns true if code is non-zero

bool is_cancellation(int code) [[optional]]

Parameters:

code – The integer status code from amongoc_status::code

Returns:

Should return true if the value of code represents a cancellation (e.g. POSIX ECANCELLED).

Note

If this function is not defined, amongoc_is_cancellation() will always return false.

bool is_timeout(int code) [[optional]]

Parameters:

code – The integer status code from amongoc_status::code

Returns:

Should return true if the value of code represents a timeout (e.g. POSIX ETIMEDOUT).

Note

If this function is not defined, amongoc_is_timeout() will always return false.

Built-In amongoc Categories

const amongoc_status_category_vtable amongoc_generic_category

const amongoc_status_category_vtable amongoc_system_category

const amongoc_status_category_vtable amongoc_netdb_category

const amongoc_status_category_vtable amongoc_addrinfo_category

const amongoc_status_category_vtable amongoc_io_category

const amongoc_status_category_vtable amongoc_server_category

const amongoc_status_category_vtable amongoc_client_category

const amongoc_status_category_vtable amongoc_tls_category

const amongoc_status_category_vtable amongoc_unknown_category

The above amongoc_status_category_vtable objects are the built-in status categories provided by amongoc. Each has the following meaning:

generic (amongoc.generic)

Corresponds to POSIX errno values. With this category, amongoc_status::code corresponds to a possible error code macro from <errno.h>

system (amongoc.system)

Corresponds to error code values dependent on the host platform. On Unix-like systems, these error code values will be equivalent to those of amongoc_generic_category.

On Windows, for example, the amongoc_status::code will be a value obtained from GetLastError()

addrinfo (amongoc.addrinfo) & netdb (amongoc.netdb)

Error codes related to name resolution and network addressing. The error code values depend on the error codes exposed by the host’s networking system.

These statuses get their own category separate from system and generic because most platforms’ networking implementations reuse POSIX integer values for error codes that arise from name resolution, thus it is required that such errors are distinguished by their category to avoid ambiguity.

io

Error codes related to I/O that are not covered in the system or generic category.

server (amongoc.server)

These error conditions correspond to error codes returned from a MongoDB server. These values are named in amongoc_server_errc.

client (amongoc.client)

These error conditions correspond to erroneous use of client-side APIs. These arise to prevent communication with a server in a way that would likely cause undesired behavior, often from client/server incompatibilities. These error values are named in amongoc_client_errc.

tls (amongoc.tls)

Error conditions related to TLS. Often the corresponding integer value comes from OpenSSL. Error reason values are stored in amongoc_tls_errc

unknown (amongoc.unknown)

This status category appears if the status was constructed from an unknown source. In this case, no status messages or status semantics are defined, except that amongoc_is_error() returns false only if the amongoc_status::code is 0.

The message returned from amongoc_status_strdup_message() will always be “amongoc.unknown:<n>” where <n> is the numeric value of the error code.

Status Code Enumerations

enum amongoc_server_errc

This enum contains error code values corresponding to their numeric value as returned from a MongoDB server.

See also

The MongoDB Error Codes Reference

Note

This enum is not exhaustive, and it is possible for a server to return an error code that does not have a corresponding enumerator.

enum amongoc_client_errc

This enum corresponds to error codes that may arise for the amongoc_client_category status category.

enumerator amongoc_client_errc_okay = 0

Represents no error

enumerator amongoc_client_errc_invalid_update_document

Issued during update CRUD operations where the update specification document is invalid.

enum amongoc_tls_errc

This enum corresponds to reason error codes related to TLS.

Important

Note that the amongoc_status::code value will not necessarily directly compare equal to any enumerator value in this enum. Instead, the reason should be extracted using amongoc_status_tls_reason(), which extracts the reason portion of the status code from the status.

Enumerators with an _ossl_ in their identifier correspond to the OpenSSL error reasons from <openssl/sslerr.h>.

enumerator amongoc_tls_errc_okay = 0

This represents a non-error condition.

There are many additional enumerators for this category, but they are not listed here. Most enumerators correspond to OpenSSL reason codes.

amongoc_tls_errc amongoc_status_tls_reason(amongoc_status st)

Extract the TLS reason integer value from a status code.

If st does not have the amongoc_tls_category category, this will return amongoc_tls_errc::amongoc_tls_errc_okay (non-error). Otherwise, it will return a non-zero amongoc_tls_errc that specifies the error reason.

C++ Exception Type

class amongoc::exception : public std::runtime_error

A C++ exception type that carries an amongoc_status value.

Note

This type is not currently thrown by any public APIs and is only used internally

exception(amongoc_status)

Construct an exception object with the associated status.

amongoc_status status() const noexcept

Return the amongoc_status associated with this exception.