32.12. Различные функции#

32.12. Различные функции
32.12. Различные функции
Назад НаверхГлава 32. libpq — C БиблиотекаНачало Далее

32.12. Различные функции

Как всегда, есть некоторые функции, которые просто никуда не подходят.

PQfreemem

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

void PQfreemem(void *ptr);

Освобождает память, выделенную libpq, в частности PQescapeByteaConn, PQescapeBytea, PQunescapeBytea, и PQnotifies.

PQconninfoFree

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

void PQconninfoFree(PQconninfoOption *connOptions);

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

PQencryptPasswordConn

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

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 (также принимаются псевдонимы on и off вместо md5 для обеспечения совместимости с более старыми версиями сервера). Обратите внимание, что поддержка алгоритма scram-sha-256 была введена в PostgreSQL версии 10 и не будет работать правильно с более старыми версиями сервера. Если значение algorithm равно NULL, эта функция запросит текущее значение параметра password_encryption у сервера. Это может заблокировать выполнение и завершиться неудачей, если текущая транзакция была отменена или если соединение занято выполнением другого запроса. Если нужно использовать алгоритм по умолчанию для сервера, но хотите избежать блокировки, запросите значение password_encryption самостоятельно перед вызовом PQencryptPasswordConn и передайте это значение в качестве аргумента algorithm.

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

PQencryptPassword

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

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

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

PQmakeEmptyPGresult

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

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

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

PQfireResultCreateEvents

Вызывает событие PGEVT_RESULTCREATE (см. Раздел 32.14) для каждой зарегистрированной процедуры события в объекте 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 и добавления номера минорной версии. Например, версия 10.1 будет возвращена как 100001, а версия 11.0 будет возвращена как 110000.

До основной версии 10 PostgreSQL использовал трехчастные номера версий, в которых первые две части вместе представляли основную версию. Для этих версий PQlibVersion использует две цифры для каждой части; например, версия 9.1.5 будет возвращена как 90105, а версия 9.2.0 будет возвращена как 90200.

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

Примечание

Эта функция появилась в версии PostgreSQL 9.1, поэтому ее нельзя использовать для определения необходимой функциональности в более ранних версиях, так как вызов ее создаст зависимость от версии 9.1 или более поздней.

Назад Наверх Далее
32.11. Функции управления Начало 32.13. Обработка уведомлений