错误处理

类
结构体	AdbcError
	操作的详细错误消息。更多...
结构体	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 使用整数错误代码来表示错误。为了提供有关错误的更多详细信息，函数还可以通过可选的输出参数返回 AdbcError，可以对其进行检查。如果提供，则调用方有责任将 AdbcError 值初始化为零。

---

类文档

AdbcError

struct AdbcError

操作的详细错误消息。

调用方必须将此结构体初始化为零（在 ADBC 1.1.0 中已 clarified）。

该结构体在 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（流）	要查询的流。
[输出]	status（状态）	ADBC 状态代码，如果没有错误，则为 ADBC_STATUS_OK。如果流不包含 ADBC 错误或指针为 NULL，则不会写入。

返回值

如果不支持，则返回 NULL。

自

ADBC API 版本 1.1.0 起

AdbcErrorGetDetail()

struct AdbcErrorDetail AdbcErrorGetDetail	(	const struct AdbcError *	error（错误）,
		int	index（索引）)

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

如果索引无效，则返回使用 NULL/0 字段初始化的 AdbcErrorDetail。

自

ADBC API 版本 1.1.0 起

AdbcErrorGetDetailCount()

int AdbcErrorGetDetailCount

(

const struct AdbcError *

error（错误）

)

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

自

ADBC API 版本 1.1.0 起