sqlite_result_code.h 4.1 KB

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