sql/sqlite_result_code.h

   1 // Copyright 2022 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef SQL_SQLITE_RESULT_CODE_H_
   6 #define SQL_SQLITE_RESULT_CODE_H_
   7
   8 #include <iosfwd>
   9
  10 #include "base/component_export.h"
  11 #include "base/dcheck_is_on.h"
  12
  13 namespace sql {
  14
  15 // Strongly typed enumeration of all known SQLite result codes.
  16 //
  17 // The meaning of the codes is listed at https://www.sqlite.org/rescode.html
  18 //
  19 // Chrome's SQLite expose SqliteResultCode and SqliteErrorCode instead of plain
  20 // ints. This isolates the use of sqlite3.h to the SQLite wrapper code itself.
  21 //
  22 // The forwarding declaration here is sufficient for most usage. The values are
  23 // defined in sqlite_result_code_values.h.
  24 enum class SqliteResultCode : int;
  25
  26 // Strongly typed enumeration of all known SQLite error codes.
  27 //
  28 // Error codes are a subset of all the result codes. Therefore, every
  29 // SqliteErrorCode is a valid SqliteResultCode.
  30 //
  31 // The forwarding declaration here is sufficient for most usage. The values are
  32 // defined in sqlite_result_code_values.h.
  33 enum class SqliteErrorCode : int;
  34
  35 // SQLite result codes, mapped into a more compact form for UMA logging.
  36 //
  37 // SQLite's (extended) result codes cover a wide range of integer values, and
  38 // are not suitable for direct use with our UMA logging infrastructure. This
  39 // enum compresses the range by removing gaps and by mapping multiple SQLite
  40 // result codes to the same value where appropriate.
  41 //
  42 // The forwarding declaration here is sufficient for most headers. The values
  43 // are defined in sqlite_result_code_values.h.
  44 enum class SqliteLoggedResultCode : int;
  45
  46 // Converts an int returned by SQLite into a strongly typed result code.
  47 //
  48 // This method DCHECKs that `sqlite_result_code` is a known SQLite result code.
  49 #if DCHECK_IS_ON()
  50 COMPONENT_EXPORT(SQL)
  51 SqliteResultCode ToSqliteResultCode(int sqlite_result_code);
  52 #else
  53 inline SqliteResultCode ToSqliteResultCode(int sqlite_result_code) {
  54   return static_cast<SqliteResultCode>(sqlite_result_code);
  55 }
  56 #endif  // DCHECK_IS_ON()
  57
  58 // Converts a SqliteResultCode into a SqliteErrorCode.
  59 //
  60 // Callers should make sure that `sqlite_result_code` is indeed an error code,
  61 // and does not indicate success. IsSqliteSuccessCode() could be used for this
  62 // purpose.
  63 #if DCHECK_IS_ON()
  64 COMPONENT_EXPORT(SQL)
  65 SqliteErrorCode ToSqliteErrorCode(SqliteResultCode sqlite_error_code);
  66 #else
  67 inline SqliteErrorCode ToSqliteErrorCode(SqliteResultCode sqlite_error_code) {
  68   return static_cast<SqliteErrorCode>(sqlite_error_code);
  69 }
  70 #endif  // DCHECK_IS_ON()
  71
  72 // Returns true if `sqlite_result_code` reports a successful operation.
  73 //
  74 // `sqlite_result_code` should only be passed to ToSqliteErrorCode() if this
  75 // function returns false.
  76 COMPONENT_EXPORT(SQL)
  77 bool IsSqliteSuccessCode(SqliteResultCode sqlite_result_code);
  78
  79 // Helper for logging a SQLite result code to a UMA histogram.
  80 //
  81 // The histogram should be declared as enum="SqliteLoggedResultCode".
  82 //
  83 // Works for all result codes, including success codes and extended error codes.
  84 // DCHECKs if provided result code should not occur in Chrome's usage of SQLite.
  85 COMPONENT_EXPORT(SQL)
  86 void UmaHistogramSqliteResult(const char* histogram_name,
  87                               int sqlite_result_code);
  88
  89 // Converts a SQLite result code into a UMA logging-friendly form.
  90 //
  91 // Works for all result codes, including success codes and extended error codes.
  92 // DCHECKs if provided result code should not occur in Chrome's usage of SQLite.
  93 //
  94 // UmaHistogramSqliteResult() should be preferred for logging results to UMA.
  95 COMPONENT_EXPORT(SQL)
  96 SqliteLoggedResultCode ToSqliteLoggedResultCode(int sqlite_result_code);
  97
  98 // Logging support.
  99 COMPONENT_EXPORT(SQL)
 100 std::ostream& operator<<(std::ostream& os, SqliteResultCode sqlite_result_code);
 101 COMPONENT_EXPORT(SQL)
 102 std::ostream& operator<<(std::ostream& os, SqliteErrorCode sqlite_error_code);
 103
 104 // Called by unit tests.
 105 //
 106 // DCHECKs the representation invariants of the mapping table used to convert
 107 // SQLite result codes to logging-friendly values.
 108 COMPONENT_EXPORT(SQL) void CheckSqliteLoggedResultCodeForTesting();
 109
 110 }  // namespace sql
 111
 112 #endif  // SQL_SQLITE_RESULT_CODE_H_