错误处理

类
struct	AdbcError
	操作的详细错误消息。 更多...
struct	AdbcErrorDetail
	错误的额外键值元数据。 更多...

宏
#define	ADBC_STATUS_OK   0
	没有错误。
#define	ADBC_STATUS_UNKNOWN   1
	发生未知错误。
#define	ADBC_STATUS_NOT_IMPLEMENTED   2
	该操作未实现或不支持。
#define	ADBC_STATUS_NOT_FOUND   3
	找不到请求的资源。
#define	ADBC_STATUS_ALREADY_EXISTS   4
	请求的资源已存在。
#define	ADBC_STATUS_INVALID_ARGUMENT   5
	参数无效，可能是编程错误。
#define	ADBC_STATUS_INVALID_STATE   6
	不满足操作的前提条件，可能是编程错误。
#define	ADBC_STATUS_INVALID_DATA   7
	处理了无效数据（不是编程错误）。
#define	ADBC_STATUS_INTEGRITY   8
	数据库的完整性受到影响。
#define	ADBC_STATUS_INTERNAL   9
	驱动程序或数据库内部发生错误。
#define	ADBC_STATUS_IO   10
	发生 I/O 错误。
#define	ADBC_STATUS_CANCELLED   11
	该操作已取消，不是因为超时。
#define	ADBC_STATUS_TIMEOUT   12
	该操作因超时而取消。
#define	ADBC_STATUS_UNAUTHENTICATED   13
	身份验证失败。
#define	ADBC_STATUS_UNAUTHORIZED   14
	客户端未被授权执行给定的操作。
#define	ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA   INT32_MIN
	通知驱动程序/驱动程序管理器，我们正在使用来自 ADBC 1.1.0 的扩展 AdbcError 结构。
#define	ADBC_ERROR_INIT
	一个辅助函数，用于初始化完整的 AdbcError 结构。
#define	ADBC_ERROR_1_0_0_SIZE   (offsetof(struct AdbcError, private_data))
	ADBC 1.0.0 中 AdbcError 结构的大小。
#define	ADBC_ERROR_1_1_0_SIZE   (sizeof(struct AdbcError))
	ADBC 1.1.0 中 AdbcError 结构的大小。

类型定义
typedef uint8_t	AdbcStatusCode
	可能失败的操作的错误代码。

函数
int	AdbcErrorGetDetailCount (const struct AdbcError *error)
	获取错误中可用的元数据值的数量。
struct AdbcErrorDetail	AdbcErrorGetDetail (const struct AdbcError *error, int index)
	通过索引获取错误中的元数据值。
const struct AdbcError *	AdbcErrorFromArrayStream (struct ArrowArrayStream *stream, AdbcStatusCode *status)
	从驱动程序创建的 ArrowArrayStream 获取 ADBC 错误。

详细描述

ADBC 使用整数错误代码来表示错误。 为了提供有关错误的更多详细信息，函数还可以通过可选的 out 参数返回 AdbcError，可以对其进行检查。 如果提供，则调用者有责任将 AdbcError 值零初始化。

---

类文档

AdbcError

struct AdbcError

操作的详细错误消息。

调用者必须将此结构零初始化（在 ADBC 1.1.0 中已阐明）。

该结构在 ADBC 1.1.0 中进行了扩展。 使用 ADBC 1.0.0 的驱动程序和客户端将没有 private_data 或 private_driver 字段。 驱动程序应该仅当 vendor_code 等于 ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA 时才读取/写入这些字段。 客户端需要初始化此结构，以避免未初始化的值使驱动程序感到困惑的可能性。

公共属性
char *	message
	错误消息。
int32_t	vendor_code
	供应商特定的错误代码（如果适用）。
char	sqlstate [5]
	SQLSTATE 错误代码（如果提供），由 SQL:2003 标准定义。 如果未设置，则应将其设置为 "\0\0\0\0\0"。
void(*	release )(struct AdbcError *error)
	释放包含的错误。
void *	private_data
	不透明的实现定义状态。
struct AdbcDriver *	private_driver
	关联的驱动程序（由驱动程序管理器用于帮助跟踪状态）。

成员数据文档

message

char* AdbcError::message

错误消息。

private_data

void* AdbcError::private_data

不透明的实现定义状态。

仅当 vendor_code 为 ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA 时，才能使用此字段。 如果存在，则当错误未初始化/释放时，此字段为 NULLPTR。

自从

ADBC API 修订版 1.1.0

private_driver

struct AdbcDriver* AdbcError::private_driver

关联的驱动程序（由驱动程序管理器用于帮助跟踪状态）。

仅当 vendor_code 为 ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA 时，才能使用此字段。

自从

ADBC API 修订版 1.1.0

release

void(* AdbcError::release) (struct AdbcError *error)

释放包含的错误。

与其他结构不同，这是一个嵌入式回调，使驱动程序管理器和驱动程序更容易协作。

sqlstate

char AdbcError::sqlstate[5]

SQLSTATE 错误代码（如果提供），由 SQL:2003 标准定义。 如果未设置，则应将其设置为 "\0\0\0\0\0"。

vendor_code

int32_t AdbcError::vendor_code

供应商特定的错误代码（如果适用）。

AdbcErrorDetail

struct AdbcErrorDetail

错误的额外键值元数据。

此处的字段由驱动程序拥有，不应释放。 调用 AdbcError 中的 release 回调时，此处的字段将失效。

自从

ADBC API 修订版 1.1.0

公共属性
const char *	key
	元数据键。
const uint8_t *	value
	二进制元数据值。
size_t	value_length
	元数据值的长度。

成员数据文档

key

const char* AdbcErrorDetail::key

元数据键。

value

const uint8_t* AdbcErrorDetail::value

二进制元数据值。

value_length

size_t AdbcErrorDetail::value_length

元数据值的长度。

宏定义文档

ADBC_ERROR_1_0_0_SIZE

#define ADBC_ERROR_1_0_0_SIZE   (offsetof(struct AdbcError, private_data))

ADBC 1.0.0 中 AdbcError 结构的大小。

为 ADBC 1.1.0 及更高版本编写的驱动程序，当 vendor_code 不是 ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA 时，绝不应接触 AdbcDriver 结构的这一部分以上。

自从

ADBC API 修订版 1.1.0

ADBC_ERROR_1_1_0_SIZE

#define ADBC_ERROR_1_1_0_SIZE   (sizeof(struct AdbcError))

ADBC 1.1.0 中 AdbcError 结构的大小。

为 ADBC 1.1.0 及更高版本编写的驱动程序，当 vendor_code 为 ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA 时，绝不应接触 AdbcDriver 结构的这一部分以上。

自从

ADBC API 修订版 1.1.0

ADBC_ERROR_INIT

#define ADBC_ERROR_INIT

值

((struct AdbcError){ \
NULL, ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA, {0, 0, 0, 0, 0}, NULL, NULL, NULL})

一个辅助函数，用于初始化完整的 AdbcError 结构。

自从

ADBC API 修订版 1.1.0

ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA

#define ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA   INT32_MIN

通知驱动程序/驱动程序管理器，我们正在使用来自 ADBC 1.1.0 的扩展 AdbcError 结构。

有关用法，请参阅 AdbcError 文档。

自从

ADBC API 修订版 1.1.0

ADBC_STATUS_ALREADY_EXISTS

#define ADBC_STATUS_ALREADY_EXISTS   4

请求的资源已存在。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_CANCELLED

#define ADBC_STATUS_CANCELLED   11

该操作已取消，不是因为超时。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_INTEGRITY

#define ADBC_STATUS_INTEGRITY   8

数据库的完整性受到影响。

例如，外键检查可能失败，或者唯一性约束可能被违反。

可能仅表示数据库端错误。

ADBC_STATUS_INTERNAL

#define ADBC_STATUS_INTERNAL   9

驱动程序或数据库内部发生错误。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_INVALID_ARGUMENT

#define ADBC_STATUS_INVALID_ARGUMENT   5

参数无效，可能是编程错误。

例如，它们可能格式错误或超出范围。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_INVALID_DATA

#define ADBC_STATUS_INVALID_DATA   7

处理了无效数据（不是编程错误）。

例如，查询执行期间可能发生了除以零的情况。

可能仅表示数据库端错误。

ADBC_STATUS_INVALID_STATE

#define ADBC_STATUS_INVALID_STATE   6

不满足操作的前提条件，可能是编程错误。

例如，该对象可能未初始化，或者可能未完全配置。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_IO

#define ADBC_STATUS_IO   10

发生 I/O 错误。

例如，远程服务可能不可用。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_NOT_FOUND

#define ADBC_STATUS_NOT_FOUND   3

找不到请求的资源。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_NOT_IMPLEMENTED

#define ADBC_STATUS_NOT_IMPLEMENTED   2

该操作未实现或不支持。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_OK

#define ADBC_STATUS_OK   0

没有错误。

ADBC_STATUS_TIMEOUT

#define ADBC_STATUS_TIMEOUT   12

该操作因超时而取消。

可能表示驱动程序端或数据库端错误。

ADBC_STATUS_UNAUTHENTICATED

#define ADBC_STATUS_UNAUTHENTICATED   13

身份验证失败。

可能仅表示数据库端错误。

ADBC_STATUS_UNAUTHORIZED

#define ADBC_STATUS_UNAUTHORIZED   14

客户端未被授权执行给定的操作。

可能仅表示数据库端错误。

ADBC_STATUS_UNKNOWN

#define ADBC_STATUS_UNKNOWN   1

发生未知错误。

可能表示驱动程序端或数据库端错误。

类型定义文档

AdbcStatusCode

typedef uint8_t AdbcStatusCode

可能失败的操作的错误代码。

函数文档

AdbcErrorFromArrayStream()

const struct AdbcError * AdbcErrorFromArrayStream	(	struct ArrowArrayStream *	stream,
		AdbcStatusCode *	status )

从驱动程序创建的 ArrowArrayStream 获取 ADBC 错误。

这允许检索通常会被 Arrow C Stream 接口抑制的错误详情和其他元数据。

调用者不得释放错误；它由流本身的释放回调函数管理。

参数

[输入]	stream	要查询的流。
[输出]	status	ADBC 状态码，如果没有错误，则为 ADBC_STATUS_OK。 如果流不包含 ADBC 错误或指针为 NULL，则不会写入。

返回值

如果不支持，则返回 NULL。

自从

ADBC API 修订版 1.1.0

AdbcErrorGetDetail()

struct AdbcErrorDetail AdbcErrorGetDetail	(	const struct AdbcError *	error,
		int	index )

通过索引获取错误中的元数据值。

如果 index 无效，则返回一个用 NULL/0 字段初始化的 AdbcErrorDetail 。

自从

ADBC API 修订版 1.1.0

AdbcErrorGetDetailCount()

int AdbcErrorGetDetailCount

(

const struct AdbcError *

error

)

获取错误中可用的元数据值的数量。

自从

ADBC API 修订版 1.1.0