PostgreSQL 9.3.1 文档 | ||||
---|---|---|---|---|
上一页 | 上一级 | 章 31. libpq - C 库 | 下一页 |
一如往常,也有一些函数,只是不是在任何地方都适合。
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上创建一个连接依赖。