Получение контекста агрегирующей функции

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

Реализации агрегирующих SQL-функций используют эту процедуру для выделения памяти для хранения состояния.

В первый раз, когда вызывается процедура sqlite3_aggregate_context(C,N) для определенной агрегирующей функции, SQLite выделяет N байтов памяти, обнуляет эту память и возвращает указатель на новую память. При последующих вызовах sqlite3_aggregate_context() для того же экземпляра агрегирующей функции возвращается тот же буфер. sqlite3_aggregate_context() обычно вызывается один раз для каждого вызова обратного вызова xStep и затем один раз в последний раз, когда вызывается обратный вызов xFinal. Когда ни одна строка не соответствует запросу агрегации, обратный вызов xStep реализации агрегирующей функции никогда не вызывается, а xFinal вызывается ровно один раз. В этих случаях sqlite3_aggregate_context() может быть вызван в первый раз изнутри xFinal().

Процедура sqlite3_aggregate_context(C,N) возвращает значение NULL при первом вызове, если N меньше или равно нулю или если произошла ошибка выделения памяти.

Размер выделенной памяти sqlite3_aggregate_context(C,N) определяется параметром N при первом успешном вызове. Изменение значения N в любом последующем вызове sqlite3_aggregate_context() внутри того же экземпляра агрегирующей функции не приведет к изменению размера выделения памяти. В обратном вызове xFinal обычно устанавливается N=0 в вызовах sqlite3_aggregate_context(C,N), чтобы не происходило бесполезных выделений памяти.

SQLite автоматически освобождает выделенную память sqlite3_aggregate_context() по завершении запроса агрегации.

Первый параметр должен быть копией контекста SQL-функции, который является первым параметром процедуры обратного вызова xStep или xFinal, реализующей агрегирующую функцию.

Эта процедура должна вызываться из того же потока, в котором выполняется агрегирующая SQL-функция.

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