Прочие функции

Как всегда, существуют функции, не попадающие ни в одну из категорий.

PQfreemem

Освобождает память, выделенную libpq.

void PQfreemem(void *ptr);

Освобождает память, выделенную libpq, в частности, функциями PQescapeByteaConn, PQescapeBytea, PQunescapeBytea и PQnotifies. Эта функция на всех платформах (кроме Microsoft Windows) действует так же, как и стандартная библиотечная функция free().

PQconninfoFree

Освобождает структуры данных, выделенные функцией PQconndefaults или PQconninfoParse.

void PQconninfoFree(PQconninfoOption *connOptions);

Простая функция PQfreemem не станет этого делать, поскольку эти массивы содержат ссылки на подчиненные строки.

PQencryptPasswordConn

Подготавливает зашифрованную форму пароля QHB.

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

Эта функция предназначена для использования клиентскими приложениями, желающими передавать команды наподобие ALTER USER joe PASSWORD 'pwd'. Рекомендуется не передавать в такой команде исходный пароль открытым текстом, поскольку он может появиться в журналах команд, выводах активности и т. д. Вместо этого примените данную функцию, чтобы перед отправкой перевести пароль в зашифрованную форму.

В аргументах passwd и user передается пароль открытым текстом и SQL-имя пользователя, для которого он предназначен. В аргументе algorithm задается алгоритм для шифрования пароля. В настоящее время поддерживаются алгоритмы md5 и scram-sha-256 (для совместимости со старыми версиями сервера в качестве псевдонимов md5 также принимаются значения on и off). Если algorithm равен NULL, эта функция запросит у сервера текущее значение параметра password_encryption. При этом возможна блокировка функции, а если текущая транзакция прервется или если соединение занято выполнением другого запроса, произойдет сбой. Если вы желаете использовать алгоритм сервера по умолчанию, но при этом избежать блокировки, сами запросите значение password_encryption перед вызовом функции PQencryptPasswordConn и передайте его в аргументе algorithm.

Возвращаемое значение является строкой, выделенной функцией malloc. Вызывающая функция может рассчитывать, что строка не содержит никаких специальных символов, требующих экранирования. Когда в результате больше не будет необходимости, для освобождения занимаемой им памяти воспользуйтесь функцией PQfreemem. При ошибке возвращает NULL, а подходящее сообщение сохраняется в объекте подключения.

PQencryptPassword

Подготавливает зашифрованную md5 форму пароля QHB.

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

Функция PQencryptPassword является более старой, выводимой из употребления версией функции PQencryptPasswordConn. Разница между ними заключается в том, что PQencryptPassword не требуется объект подключения, а в качестве алгоритма шифрования всегда используется md5.

PQmakeEmptyPGresult

Конструирует пустой объект PGresult с заданным статусом.

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

Это внутренняя функция libpq для выделения памяти и инициализации пустого объекта PGresult. Эта функция возвращает NULL, если память выделить невозможно. Она является экспортируемой, поскольку некоторые приложения находят полезным создавать объекты результатов (в частности, объекты со статусом ошибки) самостоятельно. Если conn отличен от NULL и status указывает на ошибку, в PGresult копируется текущее сообщение об ошибке для заданного подключения. Кроме того, если conn отличен от NULL, в PGresult копируются все процедуры событий, зарегистрированные в этом подключении. (Они не производят вызовы PGEVT_RESULTCREATE; см. описание функции PQfireResultCreateEvents.) Обратите внимание, что в итоге для этого объекта нужно вызвать функцию PQclear, как и для объекта PGresult, возвращенного самой libpq.

PQfireResultCreateEvents

Запускает событие PGEVT_RESULTCREATE (см. раздел Система событий) для каждой процедуры событий, зарегистрированной в объекте PGresult. Возвращает ненулевое значение при успехе и ноль при ошибке в любой из процедур событий.

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 задает копирование кортежей исходного результата. (Это подразумевает копирование также и атрибутов.) Флаг PG_COPYRES_NOTICEHOOKS задает копирование обработчиков уведомлений исходного результата. Флаг PG_COPYRES_EVENTS задает копирование событий исходного результата. (Но любые данные, связанные с экземпляром исходного результата, не копируются.) Процедуры событий получают события PGEVT_RESULTCOPY.

PQsetResultAttrs

Устанавливает атрибуты объекта PGresult.

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

Предоставленная структура attDescs копируется в результат. Если указатель attDescs равен NULL или numAttributes меньше единицы, запрос игнорируется, и функция выполняется успешно. Если res уже содержит атрибуты, функция завершается ошибкой. В случае ошибки возвращается ноль, а в случае успеха — ненулевое значение.

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 NULL. Аргумент value (устанавливаемое значение) копируется в закрытую область памяти результата, поэтому после завершения функции в нем не будет необходимости. В случае ошибки возвращается ноль, в случае успеха — ненулевое значение.

PQresultAlloc

Выделяет подчиненную область памяти для объекта PGresult.

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

Любая память, выделенная этой функцией, будет освобождена при очистке объекта res. При ошибке возвращается NULL. Результат гарантированно выравнивается надлежащим образом для любого типа данных, как и в случае с функцией malloc.

PQresultMemorySize

Выводит количество байтов, выделенное для объекта PGresult.

size_t PQresultMemorySize(const PGresult *res);

Это значение равно сумме всех запросов malloc, связанных с этим объектом PGresult, то есть это общий объем памяти, который будет освобожден функцией PQclear. Эта информация может быть полезна для управления потреблением памяти.

PQlibVersion

Возвращает версию используемой библиотеки libpq.

int PQlibVersion(void);

Результат этой функции можно использовать для определения (во время выполнения), доступна ли определенная функциональность в загруженной в настоящий момент версии libpq. Эту функцию можно применять, к примеру, для определения того, какие параметры подключения доступны в функции PQconnectdb.

Результат формируется путем умножения номера основной версии библиотеки на 10000 и добавления дополнительного номера версии. Например, версия 1.5 будет возвращена как 10005.

Если номер версии состоит из трех чисел, то основную версию представляют первые два числа. Для таких версий функция PQlibVersion использует для каждой части по две цифры; например, версия 1.4.1 будет возвращена как 10401, а версия 1.5.0 — как 10500.

Таким образом, для получения логического номера основной версии, чтобы определить совместимость функциональности, приложения должны разделить результат PQlibVersion на 100, а не на 10000. Во всех выпускаемых сериях номера дополнительных версий (с исправлениями) отличаются только двумя последними цифрами.