Коды и сообщения об ошибках

int sqlite3_errcode(sqlite3 *db);
int sqlite3_extended_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
const char *sqlite3_errstr(int);
int sqlite3_error_offset(sqlite3 *db);

Если последний вызов API sqlite3_* связанный с соединением с базой данных D завершился ошибкой, то интерфейс sqlite3_errcode(D) возвращает числовой код результата или расширенный код результата для этого вызова API. Интерфейс sqlite3_extended_errcode() аналогичен, за исключением того, что он всегда возвращает расширенный код результата, даже если расширенные коды результатов отключены.

Значения, возвращаемые sqlite3_errcode() и/или sqlite3_extended_errcode(), могут изменяться после каждого вызова API. Однако существуют некоторые интерфейсы, гарантирующие, что значение кода ошибки не изменится. К этим интерфейсам относятся:

• sqlite3_errcode()
• sqlite3_extended_errcode()
• sqlite3_errmsg()
• sqlite3_errmsg16()
• sqlite3_error_offset()

sqlite3_errmsg() и sqlite3_errmsg16() возвращают текстовое описание ошибки на английском языке, соответственно, в кодировках UTF-8 и UTF-16, или NULL, если сообщение об ошибке недоступно. (См. как SQLite обрабатывает неправильный UTF для исключений из этого правила.) Память для хранения строки сообщения об ошибке управляется внутри. Приложению не нужно беспокоиться об освобождении результата. Однако строка ошибки может быть перезаписана или освобождена последующими вызовами других функций интерфейса SQLite.

Интерфейс sqlite3_errstr(E) возвращает текстовое описание кода результата E на английском языке в кодировке UTF-8 или NULL, если для E нет доступного текстового сообщения об ошибке. Память для хранения строки сообщения об ошибке управляется внутри и не должна освобождаться приложением.

Если последняя ошибка относится к определенному токену в входном SQL-запросе, интерфейс sqlite3_error_offset() возвращает байтовый смещение начала этого токена. Байтовое смещение, возвращаемое sqlite3_error_offset(), предполагает, что входной SQL-запрос находится в кодировке UTF8. Если последняя ошибка не относится к определенному токену в входном SQL-запросе, функция sqlite3_error_offset() возвращает -1.

При использовании сериализованного режима многопоточности возможно возникновение второй ошибки на отдельной нити между первой ошибкой и вызовом этих интерфейсов. В этом случае вторая ошибка будет отображена, так как эти интерфейсы всегда отображают последний результат. Чтобы этого избежать, каждая нить может получить эксклюзивное использование соединения с базой данных D, вызвав sqlite3_mutex_enter(sqlite3_db_mutex(D)) перед началом использования D и вызвав sqlite3_mutex_leave(sqlite3_db_mutex(D)) после завершения всех вызовов перечисленных здесь интерфейсов.

Если интерфейс завершается с SQLITE_MISUSE, это означает, что интерфейс был вызван приложением неправильно. В этом случае код и сообщение об ошибке могут быть или не быть установлены.

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