LightDB提供一种快速路径接口来向服务器发送简单的函数调用。
这个接口在某种程度上已被废弃,因为我们可以通过创建一个定义该函数调用的预备语句来达到类似或者更强大的功能。然后,用参数和结果的二进制传输执行该语句,从而取代快速函数调用。
PGresult *PQfn(PGconn *conn, int fnid, int *result_buf, int *result_len, int result_is_int, const PQArgBlock *args, int nargs); typedef struct { int len; int isint; union { int *ptr; int integer; } u; } PQArgBlock;
fnid
参数是要被执行的函数的 OID。args
和nargs
定义了要传递给函数的参数;它们必须匹配已声明的函数参数列表。当一个参数结构的isint
域为真时,u.integer
值被以指定长度(必须是 1、2 或者 4 字节)整数的形式发送给服务器;这时候会发生恰当的字节交换。当isint
为假时,*u.ptr
中指定数量的字节将不做任何处理被发送出去;这些数据必须是服务器 预期的用于该函数参数数据类型的二进制传输的格式(由于历史原因u.ptr
被声明为类型int *
,其实把它考虑成void *
会更好)。result_buf
是放置该函数返回值的缓冲区。调用者必须已经分配了足够的空间来存储返回值(这里没有检查!)。实际的结果长度将被放在result_len
指向的整数中返回。如果预期结果是 2 或 4 字节整数,把result_is_int
设为 1;否则设为 0。把result_is_int
设为 1 导致libpq在必要时对值进行交换字节,这样它就作为对客户端机器正确的int
值被传输,注意对任一种允许的结果大小都会传递一个 4 字节到*result_buf
。当result_is_int
是 0 时,服务器发送的二进制格式字节将不做修改直接返回(在这种情况下,把result_buf
考虑为类型void *
更好)。
PQfn
总是返回一个有效的PGresult
指针。在使用结果之前应该检查结果状态。
当结果不再使用后,调用者有义务使用PQclear
释放PGresult
。
要将 NULL 参数传递给函数,请将该参数结构的 len
字段设置为 -1
;此时 isint
和 u
字段无关紧要。(但这仅适用于协议 3.0 及更高版本的连接。)
如果函数返回 NULL,则将 *result_len
设置为 -1
,并且不修改 *result_buf
。(这仅适用于协议 3.0 及更高版本的连接;在协议 2.0 中,*result_len
和 *result_buf
都不会被修改。)
注意我们没办法处理空参数、空结果,也没办法在使用这个接口时处理集值结果。