Error Codes and Error Handling

Data Structures
struct	C4Error
	An error value. More...

Enumerations
enum	C4ErrorDomain : uint8_t {   LiteCoreDomain = 1 , POSIXDomain , SQLiteDomain , FleeceDomain ,   NetworkDomain , WebSocketDomain , MbedTLSDomain , kC4MaxErrorDomainPlus1 }
enum	C4ErrorCode : int32_t {   kC4ErrorAssertionFailed = 1 , kC4ErrorUnimplemented , kC4ErrorUnsupportedEncryption , kC4ErrorBadRevisionID ,   kC4ErrorCorruptRevisionData , kC4ErrorNotOpen , kC4ErrorNotFound , kC4ErrorConflict ,   kC4ErrorInvalidParameter , kC4ErrorUnexpectedError , kC4ErrorCantOpenFile , kC4ErrorIOError ,   kC4ErrorMemoryError , kC4ErrorNotWriteable , kC4ErrorCorruptData , kC4ErrorBusy ,   kC4ErrorNotInTransaction , kC4ErrorTransactionNotClosed , kC4ErrorUnsupported , kC4ErrorNotADatabaseFile ,   kC4ErrorWrongFormat , kC4ErrorCrypto , kC4ErrorInvalidQuery , kC4ErrorMissingIndex ,   kC4ErrorInvalidQueryParam , kC4ErrorRemoteError , kC4ErrorDatabaseTooOld , kC4ErrorDatabaseTooNew ,   kC4ErrorBadDocID , kC4ErrorCantUpgradeDatabase , kC4ErrorDeltaBaseUnknown , kC4ErrorCorruptDelta ,   kC4NumErrorCodesPlus1 }
enum	C4NetworkErrorCode : int32_t {   kC4NetErrDNSFailure = 1 , kC4NetErrUnknownHost , kC4NetErrTimeout , kC4NetErrInvalidURL ,   kC4NetErrTooManyRedirects , kC4NetErrTLSHandshakeFailed , kC4NetErrTLSCertExpired , kC4NetErrTLSCertUntrusted ,   kC4NetErrTLSCertRequiredByPeer , kC4NetErrTLSCertRejectedByPeer , kC4NetErrTLSCertUnknownRoot , kC4NetErrInvalidRedirect ,   kC4NetErrUnknown , kC4NetErrTLSCertRevoked , kC4NetErrTLSCertNameMismatch , kC4NetErrNetworkReset ,   kC4NetErrConnectionAborted , kC4NetErrConnectionReset , kC4NetErrConnectionRefused , kC4NetErrNetworkDown ,   kC4NetErrNetworkUnreachable , kC4NetErrNotConnected , kC4NetErrHostDown , kC4NetErrHostUnreachable ,   kC4NetErrAddressNotAvailable , kC4NetErrBrokenPipe , kC4NetErrUnknownInterface , kC4NumNetErrorCodesPlus1 }

Functions
CBL_CORE_API FLStringResult	c4error_getMessage (C4Error error)
	Returns an error message describing a C4Error.
CBL_CORE_API FLSliceResult	c4error_getDescription (C4Error error)
	Returns a description of an error, including the domain and code as well as the message.
CBL_CORE_API char *	c4error_getDescriptionC (C4Error error, char *outBuffer, size_t bufferSize)
	Returns a description of an error, including the domain and code as well as the message.
CBL_CORE_API void	c4error_setCaptureBacktraces (bool)
	If set to true, then when a C4Error is created the current thread's stack backtrace will be captured along with it, and can later be examined by calling c4error_getBacktrace.
CBL_CORE_API bool	c4error_getCaptureBacktraces (void)
CBL_CORE_API FLStringResult	c4error_getBacktrace (C4Error error)
	Returns the stack backtrace, if any, associated with a C4Error.
NODISCARD CBL_CORE_API C4Error	c4error_make (C4ErrorDomain domain, int code, FLString message)
	Creates a C4Error struct with the given domain and code, and associates the message with it.
NODISCARD CBL_CORE_API C4Error	c4error_printf (C4ErrorDomain domain, int code, const char *format,...) __printflike(3
	Creates a C4Error struct with the given domain and code, formats the message as with printf, and associates the message with the error.
NODISCARD CBL_CORE_API C4Error NODISCARD CBL_CORE_API C4Error	c4error_vprintf (C4ErrorDomain domain, int code, const char *format, va_list args) __printflike(3
	Same as c4error_printf, but with a premade va_list.
NODISCARD CBL_CORE_API C4Error NODISCARD CBL_CORE_API C4Error CBL_CORE_API void	c4error_return (C4ErrorDomain domain, int code, FLString message, C4Error *outError)
	Creates and stores a C4Error in *outError, if not NULL.
CBL_CORE_API bool	c4error_mayBeTransient (C4Error err)
	Returns true if this is a network error that may be transient, i.e.
CBL_CORE_API bool	c4error_mayBeNetworkDependent (C4Error err)
	Returns true if this error might go away when the network environment changes, i.e.

Detailed Description

Enumeration Type Documentation

C4ErrorCode

enum C4ErrorCode : int32_t

Enumerator
kC4ErrorAssertionFailed
kC4ErrorUnimplemented
kC4ErrorUnsupportedEncryption
kC4ErrorBadRevisionID
kC4ErrorCorruptRevisionData
kC4ErrorNotOpen
kC4ErrorNotFound
kC4ErrorConflict
kC4ErrorInvalidParameter
kC4ErrorUnexpectedError
kC4ErrorCantOpenFile
kC4ErrorIOError
kC4ErrorMemoryError
kC4ErrorNotWriteable
kC4ErrorCorruptData
kC4ErrorBusy
kC4ErrorNotInTransaction
kC4ErrorTransactionNotClosed
kC4ErrorUnsupported
kC4ErrorNotADatabaseFile
kC4ErrorWrongFormat
kC4ErrorCrypto
kC4ErrorInvalidQuery
kC4ErrorMissingIndex
kC4ErrorInvalidQueryParam
kC4ErrorRemoteError
kC4ErrorDatabaseTooOld
kC4ErrorDatabaseTooNew
kC4ErrorBadDocID
kC4ErrorCantUpgradeDatabase
kC4ErrorDeltaBaseUnknown
kC4ErrorCorruptDelta
kC4NumErrorCodesPlus1

C4ErrorDomain

enum C4ErrorDomain : uint8_t

Enumerator
LiteCoreDomain
POSIXDomain
SQLiteDomain
FleeceDomain
NetworkDomain
WebSocketDomain
MbedTLSDomain
kC4MaxErrorDomainPlus1

C4NetworkErrorCode

enum C4NetworkErrorCode : int32_t

Enumerator
kC4NetErrDNSFailure
kC4NetErrUnknownHost
kC4NetErrTimeout
kC4NetErrInvalidURL
kC4NetErrTooManyRedirects
kC4NetErrTLSHandshakeFailed
kC4NetErrTLSCertExpired
kC4NetErrTLSCertUntrusted
kC4NetErrTLSCertRequiredByPeer
kC4NetErrTLSCertRejectedByPeer
kC4NetErrTLSCertUnknownRoot
kC4NetErrInvalidRedirect
kC4NetErrUnknown
kC4NetErrTLSCertRevoked
kC4NetErrTLSCertNameMismatch
kC4NetErrNetworkReset
kC4NetErrConnectionAborted
kC4NetErrConnectionReset
kC4NetErrConnectionRefused
kC4NetErrNetworkDown
kC4NetErrNetworkUnreachable
kC4NetErrNotConnected
kC4NetErrHostDown
kC4NetErrHostUnreachable
kC4NetErrAddressNotAvailable
kC4NetErrBrokenPipe
kC4NetErrUnknownInterface
kC4NumNetErrorCodesPlus1

Function Documentation

c4error_getBacktrace()

CBL_CORE_API FLStringResult c4error_getBacktrace

(

C4Error

error

)

Returns the stack backtrace, if any, associated with a C4Error.

This is formatted in human-readable form similar to a debugger or crash log.

c4error_getCaptureBacktraces()

CBL_CORE_API bool c4error_getCaptureBacktraces

(

void

)

c4error_getDescription()

CBL_CORE_API FLSliceResult c4error_getDescription

(

C4Error

error

)

Returns a description of an error, including the domain and code as well as the message.

Remember to free the result.

c4error_getDescriptionC()

CBL_CORE_API char * c4error_getDescriptionC	(	C4Error	error,
		char *	outBuffer,
		size_t	bufferSize
	)

Returns a description of an error, including the domain and code as well as the message.

The description is copied to the buffer as a C string. It will not write past the end of the buffer; the message will be truncated if necessary.

Parameters

error	The error to describe
outBuffer	Where to write the C string to
bufferSize	The size of the buffer

Returns

A pointer to the string, i.e. to the first byte of the buffer.

c4error_getMessage()

CBL_CORE_API FLStringResult c4error_getMessage

(

C4Error

error

)

Returns an error message describing a C4Error.

Remember to free the result.

c4error_make()

NODISCARD CBL_CORE_API C4Error c4error_make	(	C4ErrorDomain	domain,
		int	code,
		FLString	message
	)

Creates a C4Error struct with the given domain and code, and associates the message with it.

c4error_mayBeNetworkDependent()

CBL_CORE_API bool c4error_mayBeNetworkDependent

(

C4Error

err

)

Returns true if this error might go away when the network environment changes, i.e.

the client should retry after notification of a network status change.

c4error_mayBeTransient()

CBL_CORE_API bool c4error_mayBeTransient

(

C4Error

err

)

Returns true if this is a network error that may be transient, i.e.

the client should retry after a delay.

c4error_printf()

NODISCARD CBL_CORE_API C4Error c4error_printf	(	C4ErrorDomain	domain,
		int	code,
		const char *	format,
			...
	)

Creates a C4Error struct with the given domain and code, formats the message as with printf, and associates the message with the error.

c4error_return()

NODISCARD CBL_CORE_API C4Error NODISCARD CBL_CORE_API C4Error CBL_CORE_API void c4error_return	(	C4ErrorDomain	domain,
		int	code,
		FLString	message,
		C4Error *	outError
	)

Creates and stores a C4Error in *outError, if not NULL.

Useful in functions that use the LiteCore error reporting convention of taking a C4Error *outError parameter.

c4error_setCaptureBacktraces()

CBL_CORE_API void c4error_setCaptureBacktraces

(

bool

)

If set to true, then when a C4Error is created the current thread's stack backtrace will be captured along with it, and can later be examined by calling c4error_getBacktrace.

Even if false, some errors (like assertion failures) will still have backtraces.

c4error_vprintf()

NODISCARD CBL_CORE_API C4Error NODISCARD CBL_CORE_API C4Error c4error_vprintf	(	C4ErrorDomain	domain,
		int	code,
		const char *	format,
		va_list	args
	)

Same as c4error_printf, but with a premade va_list.