概述

libpq接口参考提供给用户一套数据库C语言客户端开发所需的核心API函数。这些函数按功能分类组织，涵盖了从连接建立、SQL执行、异步处理到结果集处理的完整开发流程。

开发者可根据实际需求查阅对应分类，快速定位所需函数。当前不支持通过libpq调用PQfn接口；本节将对部分常用接口做具体描述，若涉及其他接口可参考链接。libpq接口参考共分为以下6个主要部分：

数据库连接控制函数：
数据库连接控制函数控制与数据库服务器的连接。一个应用程序一次可以与多个服务器建立连接，例如一个客户端连接多个数据库的场景。支持每个连接都是用一个从函数PQconnectdb、PQconnectdbParams或PQsetdbLogin获得的PGconn对象表示。也可以支持PQconnectStart接口结合异步PQconnectPoll轮询方式获得连接对象。注意，这些函数总是返回一个非空的对象指针，除非内存分配失败，会返回一个空的指针。连接建立的接口保存在PGconn对象中，可以调用PQstatus函数来检查返回值查看连接是否成功。由于PGconn对象将SSL上下文存储在线程本地，所以PGconn的释放线程应与申请线程一致。
数据库执行语句函数：
与数据库服务器的连接成功建立，便可以使用该章节描述的函数执行SQL查询和命令。是libpq最常用的功能接口。
异步命令处理函数：
异步命令处理函数用于实现非阻塞的SQL执行，适用于高并发、低延迟或需要同时处理多个命令的场景。该类函数允许应用程序在不阻塞当前线程的情况下发送SQL命令、轮询命令执行状态等。
取消查询处理中函数：
取消查询处理中函数用于在查询执行过程中主动中断正在运行的SQL语句。该类函数主要用于长时间查询的超时控制、用户主动取消操作、异常情况下的快速中断等。
数据库结果处理函数：
数据库结果处理函数用于解析和提取PQexec或异步执行返回的PGresult结果集。该类函数提供行数、列数获取、字段值提取与空值判断等功能。

XA协议函数：

XA协议是X/Open组织提出的分布式事务处理标准，为应用程序和数据库管理系统（DBMS）提供一致的接口，以支持分布式事务处理。

xa_switch_t结构体包含了XA协议一系列的函数指针。libpq提供的xa_switch_t的变量名为xagsw。

相关信息说明如下：

表1 xa_switch_t结构体
变量名称	说明
char name[RMNAMESZ]	资源管理器名称。libpq指定值为gauss_xa。
long flags	资源管理器提供的选项。libpq指定值为TMNOMIGRATE。
long version	资源管理器的版本。
int (xa_open_entry)(char , int, long)	xa_open函数指针。
int (xa_close_entry)(char , int, long)	xa_close函数指针。
int (xa_start_entry)(XID , int, long)	xa_start函数指针。
int (xa_end_entry)(XID , int, long)	xa_end函数指针。
int (xa_rollback_entry)(XID , int, long)	xa_rollback函数指针。
int (xa_prepare_entry)(XID , int, long)	xa_prepare函数指针。
int (xa_commit_entry)(XID , int, long)	xa_commit函数指针。
int (xa_recover_entry)(XID , long, int, long)	xa_recover函数指针。
int (xa_forget_entry)(XID , int, long)	xa_forget函数指针。libpq暂不支持。
int (xa_complete_entry)(int , int *, int, long)	xa_complete函数指针。libpq暂不支持。

表2 XID结构体
变量名称	说明
long formatID	格式标识符。
long gtrid_length	全局事务标识的字节长度。最大值为64。
long bqual_length	分支标识的字节长度。最大值为64。
char data[XIDDATASIZE]	全局事务标识和分支标识的组合数据，总共128个字节。

表3 操作选项常量
常量名称	说明
TMNOFLAGS	无特殊标志，使用默认行为。
TMSUCCESS	操作成功执行。

表4 返回值常量
常量名称	说明
XA_OK	操作成功完成。
XAER_RMERR	资源管理器内部错误。
XAER_INVAL	调用参数无效。
XAER_PROTO	违反XA协议状态机。
XAER_DUPID	重复的事务分支ID。
XA_RBROLLBACK	回滚是由未指明的原因引起的。
XAER_NOTA	指定XID不存在。