这些函数可以用于询问现存数据库连接对象的状态。
Tip: libpq应用程序员应该仔细维护PGconn结构。 使用下面的访问函数来获取PGconn的内容。 避免直接引用PGconn结构里的字段, 因为这些字段在今后可能被改变。 (从 PostgreSQL 版本 6.4 开始, 类型 struct PGconn 后面的定义甚至都 没有放在 libpq-fe.h里。 如果你有一些直接访问PGconn数据域的旧代码, 你可以通过包含 libpq-int.h 来访问它们,但我们鼓励你赶快修改那些代码。)
下面的函数返回连接建立时的参数。这些参数在 PGconn 对象的生命期期间是固定的。
返回连接的数据库名。
char *PQdb(const PGconn *conn);
返回连接的用户名。
char *PQuser(const PGconn *conn);
返回连接的口令。
char *PQpass(const PGconn *conn);
返回连接的服务器主机名。
char *PQhost(const PGconn *conn);
返回连接的端口号。
char *PQport(const PGconn *conn);
返回连接的调试控制台TTY。 (这个已经过时了,因为服务器不再注意 TTY 设置,这个函数存在是为了向下兼容。)
char *PQtty(const PGconn *conn);
PQoptions 返回连接请求中传递的命令行选项。
char *PQoptions(const PGconn *conn);
下面的函数返回那些在对 PGconn 对象进行操作的过程中可能变化的状态数据。
返回连接的状态。
ConnStatusType PQstatus(const PGconn *conn);
这个状态可以是一系列值之一。 不过,我们在一个异步连接过程外面只能看到其中的两个: CONNECTION_OK 或 CONNECTION_BAD。一个与数据库的成功的连接返回状态 CONNECTION_OK。 一次失败的企图用状态 CONNECTION_BAD 标识。 通常,一个 OK 状态将保持到 PQfinish,但是一个通讯失败可能会导致状态过早地改变为 CONNECTION_BAD 。这时应用可以试着调用 PQreset 来恢复。
参阅PQconnectStart和PQconnectPoll条目看看可能出现的其他的状态码。
返回当前服务器的事务内状态。
PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
状态可以是 PQTRANS_IDLE (当前空闲), PQTRANS_ACTIVE (正在处理一个命令), PQTRANS_INTRANS (空闲,在一个合法的事务块内), 或者 PQTRANS_INERROR (空闲,在一个失败的事务块内)。 如果连接有问题,则返回 PQTRANS_UNKNOWN。 只有在一个查询发送给了服务器并且还没有完成的时候才返回 PQTRANS_ACTIVE。
Caution |
如果使用一个支持 autocommit 参数,并且设置为关闭的 PostgreSQL 7.3 版本的服务器, 那么 PQtransactionStatus 将给出不正确的结果。服务器端的 autocommit (自动提交)特性已经废弃了, 在将来的版本的服务器中不再存在。 |
查找服务器的一个当前参数设置。
const char *PQparameterStatus(const PGconn *conn, const char *paramName);
有些参数在建立连接或者它们的值改变的时候会由服务器自动报告。 PQparameterStatus 可以用于查询这些设置。 如果它认识这些参数,那么它返回当前值,否则返回 NULL。
当前版本报告的参数有 server_version (启动后无法更改); client_encoding,is_superuser,session_authorization, 和 DateStyle。
协议版本 3.0 之前的服务器不会报告参数设置,但是 libpq 里包含一些逻辑用于获取 server_version,和 client_encoding 的数值。 我们鼓励应用里面使用 PQparameterStatus,而不是使用特殊的代码来检测这些值。 (不过要注意,在 3.0 之前的连接协议里,启动后通过 SET 改变了 client_encoding 将不会被 PQparameterStatus 反映出来。)
查询所使用的前/后端协议。
int PQprotocolVersion(const PGconn *conn);
应用可能希望使用这个函数来判断某种特性是否被支持。 目前,可能的数值是 2(2.0 版本的协议),3(3.0 版本的协议),或者零(连接错误)。 在连接启动完成之后,这个数值将不会改变,但是在连接重置的过程中,理论上是可能改变的。 3.0 协议通常将用于与 PostgreSQL 7.4 或者更新版本的服务器通讯; 7.4 以前的版本只支持 2.0 版本的协议。(1.0 版本的协议已经过时了,不再被 libpq 支持。)
char *PQerrorMessage(const PGconn* conn);
几乎所有libpq函数在失败时都会为 PQerrorMessage 设置一个信息。 注意libpq的传统是,一个非空的PQerrorMessage 将在结尾包含一个新行。
获取与服务器连接的套接字的文件描述符编号。 一个有效的描述符应该是大于或等于 0;结果为 -1 表示当前没有与服务器的连接打开。 (在正常的操作中,这个结果不会改变,但是可能在启动或者重置的过程中变化。)
int PQsocket(const PGconn *conn);
int PQbackendPID(const PGconn *conn);
这个服务器PID 在调试和对比NOTIFY信息 (包含发出通知的服务器进程的 PID )时很有用。 注意该PID 属于运行数据库服务器的主机的进程,而不是本地主机!
返回连接使用的 SSL 结构,或者如果没有使用 SSL 的话返回 NULL。
SSL *PQgetssl(const PGconn *conn);
这个结构可以用于核实加密级别,检查服务器认证等信息。参考 OpenSSL 文档获取关于这个结构的更多信息。
为了获取这个函数的原形,你必须定义 USE_SSL。 这样做会自动包含来自OpenSSL的ssl.h。