34.11. 其他功能

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

  • PQfreemem
    • 释放 libpq 分配的内存。
void PQfreemem(void *ptr);

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

  • PQconninfoFree
    • 释放PQconndefaultsPQconninfoParse分配的数据结构。
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 指定用于加密密码的加密算法。当前支持的算法是md5scram-sha-256(为了与较旧的服务器版本兼容,md5的别名也接受onoff)。请注意,对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);

PQencryptPasswordPQencryptPasswordConn的旧版本,已弃用。区别在于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 34.13)。返回非零表示成功,如果任何事件过程失败则返回零。
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

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

已经收到此对象的PGEVT_RESULTCREATEPGEVT_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,以确定逻辑主版本号。在所有发行版系列中,次要发行版(错误修复发行版)之间只有后两位不同。

Note

该函数出现在 PostgreSQL 9.1 版中,因此不能用于检测早期版本中的必需功能,因为调用它会在 9.1 版或更高版本上创建链接依赖项。