sqlite.h


Obtener contexto de función agregada

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

Las implementaciones de funciones SQL agregadas usan esta función para solicitar memoria para almacenar sus estados.

La primera vez que se invoca a la función sqlite3_aggregate_context(C,N) para una función agregada en particular, SQLite reserva N bytes de memoria, la llena de ceros y retorna un puntero a la nueva memoria. En la segunda y subsecuentes llamadas a sqlite3_aggregate_context() para la misma istancia de la función agregada, se devuelve el mismo buffer. Sqlite3_aggregate_context() es invocada normalmente para cada invocación de la retrollamada xStep y entonces una última vez cuando la retrollamada xFinal es invocada. Cuando ninguna fila coincide con una consulta agregada, la retrollamada xStep() para la implementación de la función agragada nunca es invocada y xFinal() es invocada exactamente una vez. En esos casos, sqlite3_aggregate_context() podría ser invocada por primera vez desde xFinal().

La función sqlite3_aggregate_context(C,N) retorna un puntero NULL si N es menor o igual a cero o si ocurre un error de reserva de memoria.

La cantidad de espacio reservado por sqlite3_aggregate_context(C,N) es determinada por el parámetro N en la primera llamada con éxito. Cambiando el valor de N en subsiguientes llamadas a sqlite3_aggregate_context() dentro de la misma instancia de la función agregada no redimensionará la memoria reservada.

SQLite automáticamente libera la memoria obtenida por sqlite3_aggregate_context() cuando la consulta agregada termina.

El primer parámetro debe ser una copia del contexto de la función SQL que es el primer parámetro de la rutina de la retrollamada xStep o xFinal que implementa la función agregada.

Esta rutina debe ser llamada desde el mismo hilo en el que la función agregada SQL se está ejecutando.