1 // Copyright (c) 2011 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 5 #ifndef APP_SQL_STATEMENT_H_ 6 #define APP_SQL_STATEMENT_H_ 7 #pragma once 8 9 #include <string> 10 #include <vector> 11 12 #include "app/sql/connection.h" 13 #include "base/basictypes.h" 14 #include "base/memory/ref_counted.h" 15 #include "base/string16.h" 16 17 namespace sql { 18 19 // Possible return values from ColumnType in a statement. These should match 20 // the values in sqlite3.h. 21 enum ColType { 22 COLUMN_TYPE_INTEGER = 1, 23 COLUMN_TYPE_FLOAT = 2, 24 COLUMN_TYPE_TEXT = 3, 25 COLUMN_TYPE_BLOB = 4, 26 COLUMN_TYPE_NULL = 5, 27 }; 28 29 // Normal usage: 30 // sql::Statement s(connection_.GetUniqueStatement(...)); 31 // if (!s) // You should check for errors before using the statement. 32 // return false; 33 // 34 // s.BindInt(0, a); 35 // if (s.Step()) 36 // return s.ColumnString(0); 37 // 38 // Step() and Run() just return true to signal success. If you want to handle 39 // specific errors such as database corruption, install an error handler in 40 // in the connection object using set_error_delegate(). 41 class Statement { 42 public: 43 // Creates an uninitialized statement. The statement will be invalid until 44 // you initialize it via Assign. 45 Statement(); 46 47 explicit Statement(scoped_refptr<Connection::StatementRef> ref); 48 ~Statement(); 49 50 // Initializes this object with the given statement, which may or may not 51 // be valid. Use is_valid() to check if it's OK. 52 void Assign(scoped_refptr<Connection::StatementRef> ref); 53 54 // Returns true if the statement can be executed. All functions can still 55 // be used if the statement is invalid, but they will return failure or some 56 // default value. This is because the statement can become invalid in the 57 // middle of executing a command if there is a serioud error and the database 58 // has to be reset. is_valid()59 bool is_valid() const { return ref_->is_valid(); } 60 61 // These operators allow conveniently checking if the statement is valid 62 // or not. See the pattern above for an example. 63 operator bool() const { return is_valid(); } 64 bool operator!() const { return !is_valid(); } 65 66 // Running ------------------------------------------------------------------- 67 68 // Executes the statement, returning true on success. This is like Step but 69 // for when there is no output, like an INSERT statement. 70 bool Run(); 71 72 // Executes the statement, returning true if there is a row of data returned. 73 // You can keep calling Step() until it returns false to iterate through all 74 // the rows in your result set. 75 // 76 // When Step returns false, the result is either that there is no more data 77 // or there is an error. This makes it most convenient for loop usage. If you 78 // need to disambiguate these cases, use Succeeded(). 79 // 80 // Typical example: 81 // while (s.Step()) { 82 // ... 83 // } 84 // return s.Succeeded(); 85 bool Step(); 86 87 // Resets the statement to its initial condition. This includes clearing all 88 // the bound variables and any current result row. 89 void Reset(); 90 91 // Returns true if the last executed thing in this statement succeeded. If 92 // there was no last executed thing or the statement is invalid, this will 93 // return false. 94 bool Succeeded() const; 95 96 // Binding ------------------------------------------------------------------- 97 98 // These all take a 0-based argument index and return true on failure. You 99 // may not always care about the return value (they'll DCHECK if they fail). 100 // The main thing you may want to check is when binding large blobs or 101 // strings there may be out of memory. 102 bool BindNull(int col); 103 bool BindBool(int col, bool val); 104 bool BindInt(int col, int val); 105 bool BindInt64(int col, int64 val); 106 bool BindDouble(int col, double val); 107 bool BindCString(int col, const char* val); 108 bool BindString(int col, const std::string& val); 109 bool BindString16(int col, const string16& value); 110 bool BindBlob(int col, const void* value, int value_len); 111 112 // Retrieving ---------------------------------------------------------------- 113 114 // Returns the number of output columns in the result. 115 int ColumnCount() const; 116 117 // Returns the type associated with the given column. 118 // 119 // Watch out: the type may be undefined if you've done something to cause a 120 // "type conversion." This means requesting the value of a column of a type 121 // where that type is not the native type. For safety, call ColumnType only 122 // on a column before getting the value out in any way. 123 ColType ColumnType(int col) const; 124 125 // These all take a 0-based argument index. 126 bool ColumnBool(int col) const; 127 int ColumnInt(int col) const; 128 int64 ColumnInt64(int col) const; 129 double ColumnDouble(int col) const; 130 std::string ColumnString(int col) const; 131 string16 ColumnString16(int col) const; 132 133 // When reading a blob, you can get a raw pointer to the underlying data, 134 // along with the length, or you can just ask us to copy the blob into a 135 // vector. Danger! ColumnBlob may return NULL if there is no data! 136 int ColumnByteLength(int col) const; 137 const void* ColumnBlob(int col) const; 138 bool ColumnBlobAsString(int col, std::string* blob); 139 void ColumnBlobAsVector(int col, std::vector<char>* val) const; 140 void ColumnBlobAsVector(int col, std::vector<unsigned char>* val) const; 141 142 // Diagnostics -------------------------------------------------------------- 143 144 // Returns the original text of sql statement. Do not keep a pointer to it. 145 const char* GetSQLStatement(); 146 147 private: 148 // This is intended to check for serious errors and report them to the 149 // connection object. It takes a sqlite error code, and returns the same 150 // code. Currently this function just updates the succeeded flag, but will be 151 // enhanced in the future to do the notification. 152 int CheckError(int err); 153 154 // The actual sqlite statement. This may be unique to us, or it may be cached 155 // by the connection, which is why it's refcounted. This pointer is 156 // guaranteed non-NULL. 157 scoped_refptr<Connection::StatementRef> ref_; 158 159 // See Succeeded() for what this holds. 160 bool succeeded_; 161 162 DISALLOW_COPY_AND_ASSIGN(Statement); 163 }; 164 165 } // namespace sql 166 167 #endif // APP_SQL_STATEMENT_H_ 168