int sqlite3_get_table( sqlite3 *db, /* An open database */ const char *zSql, /* SQL to be evaluated */ char ***pazResult, /* Results of the query */ int *pnRow, /* Number of result rows written here */ int *pnColumn, /* Number of result columns written here */ char **pzErrmsg /* Error msg written here */ ); void sqlite3_free_table(char **result);
Это устаревший интерфейс, который сохранен для совместимости. Использование этого интерфейса не рекомендуется.
Определение: таблица результата это структура данных в оперативной памяти, созданная sqlite3_get_table(). Таблица результатов хранит запись полных результатов от одного или более запросов.
У таблицы концептуально есть много строк и колонок. Но эти числа не часть самой таблицы результата. Эти числа получены отдельно. Допустим, N количество строк, а M количество колонок.
Таблица результата это множество указателей на законченные нолем последовательности UTF-8. Есть (N+1)*M элементов во множестве. Первые указатели M указывают на законченные нолем последовательности, которые содержат названия колонок. Остающиеся записи указывают на результаты запроса. Значения NULL указывают на NULL. Все другие значения находятся в их UTF-8 законченным нолем строковом представлении, как возвращено sqlite3_column_text().
Таблица результата могла бы состоять из одного или более выделений памяти. Небезопасно передать его непосредственно sqlite3_free(). Таблица результата должна быть освобождена, используя sqlite3_free_table().
Как пример формата таблицы результата, предположите, что результаты запроса следующие:
Name | Age ----------------------- Alice | 43 Bob | 28 Cindy | 21
Есть две колонки (M == 2) и три строки (N==3). Таким образом у таблицы результата есть 8 записей. Предположим, что таблица результата сохранена во множестве, названном azResult. Тогда azResult имеет это содержание:
azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3] = "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy"; azResult[7] = "21";
sqlite3_get_table() оценивает один или несколько отделенных точкой с запятой SQL-операторов в законченной нолем последовательности UTF-8 ее 2-го параметра и возвращает таблицу результата указателю в ее 3-м параметре.
После того, как приложение закончило работу с результатом sqlite3_get_table(), это должно передать указатель таблицы результата в sqlite3_free_table(), чтобы освободить память, которая была выделена. Из-за того, как sqlite3_malloc() вызывается в sqlite3_get_table() функция запроса не должна пытаться вызвать напрямую sqlite3_free(). Только sqlite3_free_table() is в состоянии освободить память правильно и безопасно.
sqlite3_get_table() осуществляется как обертка вокруг sqlite3_exec(). sqlite3_get_table() не имеет доступа ни к каким внутренним структурам данных SQLite. Это использует только открытый интерфейс, определенный здесь. Как следствие ошибки, которые происходят в слое обертки за пределами внутреннего sqlite3_exec(), не отражены в последующих sqlite3_errcode() или sqlite3_errmsg().