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