连接状态函数

提示: libpq应用程序员应该小心地维护PGconn抽象。使用下面描述的访问函数来理解PGconn的内容。我们不推荐使用libpq-int.h引用内部的PGconn域，因为它们可能在未来改变。

PQdb

返回该连接的数据库名。

char *PQdb(const PGconn *conn);

PQuser

返回该连接的用户名。

char *PQuser(const PGconn *conn);

PQpass

返回该连接的口令。

char *PQpass(const PGconn *conn);

PQhost

返回该连接的服务器主机名。

char *PQhost(const PGconn *conn);

PQport

返回该连接的端口。

char *PQport(const PGconn *conn);

PQtty

返回该连接的调试TTY（这已被废弃，因为服务器不再关心TTY设置，但这个函数保持了向后兼容）。

char *PQtty(const PGconn *conn);

PQoptions

返回被传递给连接请求的命令行选项。

char *PQoptions(const PGconn *conn);

PQstatus

返回该连接的状态。

ConnStatusType PQstatus(const PGconn *conn);

该状态可以是一系列值之一。不过，其中只有两个在一个异步连接过程之外可见：CONNECTION_OK和CONNECTION_BAD。一个到数据库的完好连接的状态为CONNECTION_OK。一个失败的连接尝试则由状态CONNECTION_BAD表示。通常，一个 OK 状态将一直保持到PQfinish，但是一次通信失败可能导致该状态过早地改变为CONNECTION_BAD。在那种情况下，该应用可以通过调用PQreset尝试恢复。

关于其他可能会被返回的状态代码，请见PQconnectStartParams、PQconnectStart和PQconnectPoll的条目。

PQtransactionStatus

返回服务器的当前事务内状态。

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

该状态可能是PQTRANS_IDLE（当前空闲）、 PQTRANS_ACTIVE（一个命令运行中）、 PQTRANS_INTRANS（空闲，处于一个合法的事务块中） 或者PQTRANS_INERROR（空闲，处于一个失败的事务块中）。 如果该连接损坏，将会报告PQTRANS_UNKNOWN。 只有当一个查询已经被发送给服务器并且还没有完成时，才会报告PQTRANS_ACTIVE。

PQparameterStatus

查找服务器的一个当前参数设置。

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

某一参数值会被服务器在连接开始或值改变时自动报告。PQparameterStatus可以被用来询问这些设置。它为已知的参数返回当前值，为未知的参数返回NULL。

自当前发布开始会被报告的参数包括 server_version、 server_encoding、 client_encoding、 application_name、 is_superuser、 session_authorization、 DateStyle、 IntervalStyle、 TimeZone、 integer_datetimes以及 standard_conforming_strings（ server_encoding、TimeZone以及integer_datetimes在 8.0 以前的发布中不被报告；standard_conforming_strings在 8.1 以前的发布中不被报告；IntervalStyle在 8.4 以前的发布中不被报告；application_name在 9.0 以前的发布中不被报告）。注意 server_version、 server_encoding以及 integer_datetimes在启动之后无法改变。

3.0 之前协议的服务器不报告参数设置，但是libpq包括获得server_version以及client_encoding值的逻辑。我们鼓励应用使用PQparameterStatus而不是ad hoc代码来确定这些值（不过注意在一个 3.0 之前的连接上，连接开始后通过SET改变client_encoding不会被PQparameterStatus反映）。对于server_version（另见PQserverVersion），它以一种数字形式返回信息，这样更容易进行比较。

如果没有为standard_conforming_strings报告值，应用能假设它是off，也就是说反斜线会被视为字符串中的转义。还有，这个参数的存在可以被作为转义字符串语法（E'...'）被接受的指示。

尽管被返回的指针被声明成const，它事实上指向与PGconn结构相关的可变存储。假定该指针在查询之间保持有效是不明智的。

PQprotocolVersion

询问所使用的 前端/后端协议。

int PQprotocolVersion(const PGconn *conn);

应用可能希望用这个函数来确定某些特性是否被支持。当前，可能值是 2（2.0 协议）、3（3.0 协议）或零（连接损坏）。协议版本在连接启动完成后将不会改变，但是理论上在连接重置期间是可以改变的。当与PostgreSQL 7.4 或以后的服务器通信时通常使用 3.0 协议，7.4 之前的服务器只支持协议 2.0（协议 1.0 已被废弃并且不再被libpq支持）。

PQserverVersion

返回一个表示后端版本的整数。

int PQserverVersion(const PGconn *conn);

应用可能会使用这个函数来决定它们连接到的数据库服务器的版本。该数字通过将主、次和修订数字转换成两位十进制数并连接在一起形成。例如，版本 8.1.5 将被返回为 80105，版本 8.2 将被返回为 80200（前导零没有被显示）。如果连接损坏，将返回零。

PQerrorMessage

返回连接上的一个操作最近产生的错误消息。

char *PQerrorMessage(const PGconn *conn);

几乎所有的libpq在失败时都会为PQerrorMessage设置一个消息。注意按照libpq习惯，一个非空PQerrorMessage结果由多行构成，并且将包括一个尾部新行。调用者不应该直接释放结果。当相关的PGconn句柄被传递给PQfinish时，它将被释放。在PGconn结构上的多个操作之间，不能指望结果字符串会保持不变。

PQsocket

获得到服务器连接套接字的文件描述符号。一个合法的描述符将会大于等于零。结果为 -1 表示当前没有打开服务器连接（在普通操作期间这将不会改变，但是在连接设置或重置期间可能改变）。

int PQsocket(const PGconn *conn);

PQbackendPID

返回处理这个连接的后端进程的进程ID（PID）。

int PQbackendPID(const PGconn *conn);

后端PID有助于调试目的并且可用于与NOTIFY消息（它包括发出提示的后端进程的PID）进行比较。注意PID属于一个在数据库服务器主机上执行的进程，而不是本地主机进程！

PQconnectionNeedsPassword

如果连接认证方法要求一个口令但没有可用的口令，返回真（1）。否则返回假（0）。

int PQconnectionNeedsPassword(const PGconn *conn);

这个函数可以在连接尝试失败后被应用于决定是否向用户提示要求一个口令。

PQconnectionUsedPassword

如果连接认证方法使用一个口令，返回真（1）。否则返回假（0）。

int PQconnectionUsedPassword(const PGconn *conn);

这个函数能在一次连接尝试失败或成功后用于检测该服务器是否要求一个口令。

PQsslInUse

如果连接使用SSL，则返回true（1），否则返回false（0）。

int PQsslInUse(const PGconn *conn);

PQsslAttribute

返回关于连接的SSL相关的信息。

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

可用属性的列表因使用的SSL库和连接类型而异。如果某个属性不可用，则返回NULL。

以下属性通常可用：

library

正在使用的SSL实现的名称。(目前，只实现了"OpenSSL")

protocol

正在使用的SSL/TLS版本。常见值为"SSLv2"、 "SSLv3"、"TLSv1"、 "TLSv1.1"和"TLSv1.2"， 但如果使用某些其他协议，实现可能返回其他字符串。

key_bits

加密算法使用的密钥位数。

cipher

使用的密码组的短名称，例如"DHE-RSA-DES-CBC3-SHA"。 这些名称特定于每个SSL实现的。

compression

如果正在使用SSL压缩，则返回压缩算法的名称，如果使用了压缩但不知道算法， 则为“on”。如果不使用压缩，则返回“off”。

PQsslAttributeNames

返回可用的SSL属性名称数组。该数组由NULL指针终止。

const char * const * PQsslAttributeNames(const PGconn *conn);

PQsslStruct

返回指向描述连接的特定于SSL实现的对象的指针。

void *PQsslStruct(const PGconn *conn, const char *struct_name);

可用的结构取决于正在使用的SSL实现。对于OpenSSL，有一个结构， 可用名称为“OpenSSL”，它返回一个指向OpenSSL SSL结构的指针。 要使用这个函数，可以使用下列代码：

#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }

这个结构可以被用来验证加密级别、检查服务器证书等等。 关于这个结构可参考OpenSSL文档。

PQgetssl

返回在连接中使用的 SSL 结构，如果没有使用 SSL 则返回空。

void *PQgetssl(const PGconn *conn);

此函数等效于PQsslStruct(conn, "OpenSSL")。 它不应该在新的应用程序中使用，因为返回的结构是特定于OpenSSL的， 并且如果使用了另一个SSL实现则返回的结构将不可用。要检查一个连接是否使用了SSL， 请调用PQsslInUse，有关连接的更多详细信息， 请使用PQsslAttribute。