各种函数

PostgreSQL 9.4.4 中文手册
上一页 | 上一级 | 章 31. libpq - C 库 | 下一页

# 31.11. 各种函数

一如往常，也有一些函数，只是不是在任何地方都适合。

`PQfreemem`

  释放libpq分配的内存。

      void PQfreemem(void *ptr);

  释放libpq分配的内存，尤其是`PQescapeByteaConn`， `PQescapeBytea`，`PQunescapeBytea`和`PQnotifies`。 尤其重要的是，在Windows系统上使用这个函数，而不是`free()`。 这是因为只有DLL和应用程序的多线程/单线程，发布/调试，静态/动态标志是相同的时， 才在一个DLL中分配内存，并在应用程序工作时释放内存。在非Windows平台上， 这个函数与标准库函数`free()`相同。

`PQconninfoFree`

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

      void PQconninfoFree(PQconninfoOption *connOptions);

  一个简单的`PQfreemem`不会这样做，因为数组包含对子字符串的引用。

`PQencryptPassword`

  准备一个PostgreSQL密码的加密形式：

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

  这个函数旨在用于那些发送类似于`ALTER USER joe PASSWORD 'pwd'`命令的客户端应用程序。 这是一个很好的方法，这种命令不发送原始的明文密码，因为它可能被暴露在命令日志，活动显示中等等。 相反，在发送前，使用这个函数可以将密码转换为加密的形式。参数是明文密码和用户的SQL名字。 返回值是`malloc`分配的一个字符串，或超出内存时为`NULL`。 调用可以认为字符串中不包含需要转义的特殊字符。当使用结束之后，用`PQfreemem`进行释放。

`PQmakeEmptyPGresult`

  用给定的状态构造一个空`PGresult`对象。

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

  这是libpq的内部函数，用于分配和初始化一个空`PGresult`对象。 如果不能分配内存，那么这个函数返回`NULL`。这是输出， 因为一些应用程序发现它可以有效的生成结果对象本身（特别是带有错误状态的对象）。 如果`conn`非空，并且`status`用于表示一个错误， 那么指定连接的当前错误消息被复制到`PGresult`中。同时， 如果`conn`非空，那么连接中的任何事件过程会被复制到 `PGresult`中。（它们不会获得`PGEVT_RESULTCREATE`请求， 但会看到`PQfireResultCreateEvents`）。需要注意的是随着libpq 本身返回`PGresult`时，对象最后应该请求`PQclear`。

`PQfireResultCreateEvents`

  为`PGresult`对象中的每个事件过程触发一个`PGEVT_RESULTCREATE`事件 （参阅第 31.13 节）。成功时返回非0，如果任何事件过程失败返回0。

      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_ATTRS`声明复制源结果的属性（列定义）。 `PG_COPYRES_TUPLES`声明复制源结果的元组（这意味着也复制属性）。 `PG_COPYRES_NOTICEHOOKS`声明复制源结果的通知陷阱。 `PG_COPYRES_EVENTS`声明负值源结果的事件。（但任何与源关联的实例数据不会被复制。）

`PQsetResultAttrs`

  设置`PGresult`对象的属性。

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

  提供的`attDescs`被复制到结果中。如果`attDescs` 指针为`NULL`，或`numAttributes`小于1，那么请求将被忽略， 并且函数成功。如果`res`已经有了属性，那么函数会失败。如果函数失败， 会返回0。如果函数成功，会返回非0。

`PQsetvalue`

  设置`PGresult`对象的元组字段值。

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

  这个函数会自动按需增加结果的内置元组。然而，`tup_num` 参数必须小于等于`PQntuples`，意味着这个函数一次只能增加一个元组。 但已存在的任意的元组中的任意字段可以以任意顺序进行调整。如果`field_num` 中的一个值已经存在，会被覆盖重写。如果`len`是-1，或`value` 是`NULL`，字段值会被设置为一个SQL空值。`value` 被复制到结果的私有存储中，因此函数返回结果后就不再需要了。如果函数失败，会返回0。 如果函数成功，会返回非0。

`PQresultAlloc`

  为`PGresult`对象分配子存储。

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

  当`res`被清理时，该函数分配的内存也会被释放掉。如果函数失败， 返回`NULL`。结果是保证任何类型的数据能够充分对齐，如同对`malloc`一样。

`PQlibVersion`

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

      int PQlibVersion(void);

  如果特定的功能在libpq当前加载的版本中可用，那么用于决定运行时此函数的结果。 该函数可以使用，比如，用来确定可用于`PQconnectdb`的连接选项， 或者是否支持PostgreSQL 9.0中添加的`hex` `bytea`输出。

  数字是通过把主、次及版本号转换成两位十进制数并且把它们连接在一起组成的。例如， 版本9.1将被返回901000，版本9.1.2将被返回90102（前导零没有显示）。

  > 注意: 这个函数是在PostgreSQL版本9.1中出现的，所以它不能用来在较早的版本中检测所需功能， 因此连接它将在版本9.1上创建一个连接依赖。

上一页 | 起始页 | 下一页
控制函数 | 上一级 | 通知处理