33.11. 其他功能

与往常一样，有些功能根本无法适应任何地方。

• PQfreemem
  • 释放 libpq 分配的内存。

void PQfreemem(void *ptr);

释放 libpq 分配的内存，尤其是PQescapeByteaConn，PQescapeBytea，PQunescapeBytea和PQnotifies。在 Microsoft Windows 上使用此功能而不是free()尤其重要。这是因为仅当 DLL 和应用程序的多线程/单线程，释放/调试和静态/动态标志相同时，才在 DLL 中分配内存并在应用程序中释放它。在非 Microsoft Windows 平台上，此函数与标准库函数free()相同。

• PQconninfoFree
  • 释放PQconndefaults或PQconninfoParse分配的数据结构。

void PQconninfoFree(PQconninfoOption *connOptions);

简单的PQfreemem不会这样做，因为数组包含对辅助字符串的引用。

• PQencryptPasswordConn
  • 准备 PostgreSQL 密码的加密形式。

char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);

此功能供希望发送诸如ALTER USER joe PASSWORD 'pwd'之类的命令的 Client 端应用程序使用。最好不要在这样的命令中发送原始的明文密码，因为它可能会在命令日志，活动显示等中公开。而是使用此功能在发送密码之前将密码转换为加密形式。

• passwd 和 user *参数是明文密码，是用户的 SQL 名称。 * algorithm 指定用于加密密码的加密算法。当前支持的算法是md5和scram-sha-256(为了与较旧的服务器版本兼容，md5的别名也接受on和off)。请注意，对scram-sha-256的支持是在 PostgreSQL 版本 10 中引入的，不适用于较旧的服务器版本。如果 algorithm 是NULL，则此函数将向服务器查询password_encryption设置的当前值。这可能会阻塞，并且如果当前事务中止或连接正忙于执行另一个查询，则将失败。如果希望对服务器使用默认算法，但又希望避免阻塞，请在调用PQencryptPasswordConn之前先查询password_encryption，然后将该值作为 algorithm *传递。

返回值是malloc分配的字符串。调用者可以假定该字符串不包含任何需要转义的特殊字符。完成后，使用PQfreemem释放结果。如果出错，则返回NULL，并且将适当的消息存储在连接对象中。

• PQencryptPassword
  • 准备 md5 加密形式的 PostgreSQL 密码。

char *PQencryptPassword(const char *passwd, const char *user);

PQencryptPassword是PQencryptPasswordConn的旧版本，已弃用。区别在于PQencryptPassword不需要连接对象，并且md5始终用作加密算法。

• PQmakeEmptyPGresult
  • 构造一个具有给定状态的空PGresult对象。

PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

这是 libpq 的内部函数，用于分配和初始化一个空的PGresult对象。如果无法分配内存，此函数将返回NULL。导出它是因为某些应用程序发现自己生成结果对象(尤其是具有错误状态的对象)很有用。如果* conn 不为空，并且 status 指示错误，则将指定连接的当前错误消息复制到PGresult中。同样，如果 conn *不为 null，则将在 Connecting 注册的任何事件过程都复制到PGresult中。 (它们没有获得PGEVT_RESULTCREATE调用，但请参见PQfireResultCreateEvents.)请注意，最终应在对象上调用PQclear，就像 libpq 本身返回的PGresult一样。

• PQfireResultCreateEvents
  • 为PGresult对象中注册的每个事件过程触发PGEVT_RESULTCREATE事件(请参见Section 33.13)。返回非零表示成功，如果任何事件过程失败则返回零。

int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

conn参数传递给事件过程，但不能直接使用。如果事件过程不使用它，则可以为NULL。

已经收到此对象的PGEVT_RESULTCREATE或PGEVT_RESULTCOPY事件的事件过程不会再次触发。

此功能与PQmakeEmptyPGresult分开的主要原因是，通常适合在调用事件过程之前创建PGresult并用数据填充它。

• PQcopyResult
  • 复制PGresult对象。副本不以任何方式链接到源结果，并且在不再需要副本时必须调用PQclear。如果函数失败，则返回NULL。

PGresult *PQcopyResult(const PGresult *src, int flags);

这并不是要精确复制。返回的结果始终处于PGRES_TUPLES_OK状态，并且不会在源中复制任何错误消息。 (但是，它确实会复制命令状态字符串.)* flags *参数确定要复制的内容。它是几个标志的按位或。 PG_COPYRES_ATTRS指定复制源结果的属性(列定义)。 PG_COPYRES_TUPLES指定复制源结果的 Tuples。 (这也意味着也要复制属性.)PG_COPYRES_NOTICEHOOKS指定复制源结果的通知钩子。 PG_COPYRES_EVENTS指定复制源结果的事件。 (但是不会复制与源关联的任何实例数据.)

• PQsetResultAttrs
  • 设置PGresult对象的属性。

int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);

提供的* attDescs 将复制到结果中。如果 attDescs 指针为NULL或 numAttributes 小于 1，则忽略该请求，该函数成功。如果 res *已经包含属性，则该函数将失败。如果函数失败，则返回值为零。如果函数成功，则返回值为非零。

• PQsetvalue
  • 设置PGresult对象的 Tuples 字段值。

int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);

该函数将根据需要自动增长结果的内部 Tuples 数组。但是，* tup_num 参数必须小于或等于PQntuples，这意味着此函数一次只能将一个 Tuples 数组增长一个 Tuples 数组。但是任何现有 Tuples 的任何字段都可以按任何 Sequences 进行修改。如果 field_num 处的值已经存在，它将被覆盖。如果 len 为-1 或 value *为NULL，则字段值将设置为 SQL 空值。 * value *复制到结果的专用存储中，因此在函数返回后不再需要。如果函数失败，则返回值为零。如果函数成功，则返回值为非零。

• PQresultAlloc
  • 为PGresult对象分配辅助存储。

void *PQresultAlloc(PGresult *res, size_t nBytes);

清除* res *时，将释放为此功能分配的所有内存。如果函数失败，则返回值为NULL。与malloc一样，对于任何类型的数据，结果都保证充分对齐。

• PQlibVersion
  • 返回正在使用的 libpq 的版本。

int PQlibVersion(void);

该功能的结果可用于在运行时确定 libpq 的当前加载版本中是否提供了特定功能。例如，该功能可用于确定PQconnectdb中可用的连接选项。

通过将库的主要版本号乘以 10000 并加上次要版本号来形成结果。例如，版本 10.1 将返回为 100001，版本 11.0 将返回为 110000.

在主要版本 10 之前，PostgreSQL 使用三部分的版本号，其中前两个部分一起代表主要版本。对于这些版本，PQlibVersion的每个部分使用两位数字；例如，版本 9.1.5 将返回为 90105，版本 9.2.0 将返回为 90200.

因此，为了确定功能兼容性，应用程序应将PQlibVersion的结果除以 100 而不是 10000，以确定逻辑主版本号。在所有发行版系列中，次要发行版(错误修复发行版)之间只有后两位不同。