Данные клиента подключения к базе данных

void *sqlite3_get_clientdata(sqlite3*,const char*);
int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));

Эти функции используются для связывания одного или нескольких именованных указателей с подключением к базе данных. Вызов sqlite3_set_clientdata(D,N,P,X) приводит к привязке указателя P к подключению к базе данных D под именем N. Последующие вызовы sqlite3_get_clientdata(D,N) возвращают копию указателя P или указатель NULL, если ранее не было вызовов sqlite3_set_clientdata() с теми же значениями D и N. Имена сравниваются с помощью strcmp() и поэтому чувствительны к регистру. При успешном выполнении функция возвращает 0, а при ошибке выделения памяти — SQLITE_NOMEM.

Если P и X не равны NULL, то деструктор X вызывается с аргументом P при первом из следующих событий:

• Во время вызова sqlite3_set_clientdata(), который пытается зарегистрировать указатель P, происходит ошибка нехватки памяти.
• Выполняется последующий вызов sqlite3_set_clientdata(D,N,P,X) с теми же параметрами D и N.
• Подключение к базе данных закрывается. SQLite не гарантирует порядок вызова деструкторов, но гарантирует, что все деструкторы будут вызваны ровно один раз в процессе закрытия подключения к базе данных.

SQLite не выполняет никаких действий с клиентскими данными, кроме вызова деструкторов для этих данных в нужный момент. Предполагается, что клиентские данные будут использоваться библиотеками-обёртками для хранения дополнительной информации о подключении к базе данных SQLite.

Количество различных указателей на клиентские данные (с разными именами), которые можно привязать к одному подключению к базе данных, не ограничено (за исключением доступного объёма памяти). Однако текущая реализация хранит данные в связном списке. Производительность вставки и поиска будет пропорциональна количеству записей. При разработке предполагалось, что приложение будет хранить лишь небольшое число имён клиентских данных, обычно одно или два; именно для такого сценария оптимизирована реализация. Этот интерфейс не предназначен для использования в качестве универсального хранилища «ключ-значение» для тысяч или миллионов ключей. Он будет работать и в таком случае, но производительность может разочаровать.

Перечислить указатели на клиентские данные, связанные с подключением к базе данных, невозможно. Параметр N можно рассматривать как секретный ключ: получить доступ к связанным данным может только код, которому известен этот ключ.

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

Данные клиента подключения к базе данных доступны только в SQLite версии 3.44.0 (2023-11-01) и новее.

См. также: sqlite3_set_auxdata() и sqlite3_get_auxdata().

См. также списки объектов, констант и функций.