1 // Copyright (c) 2012 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 SQL_STATEMENT_H_ 6 #define SQL_STATEMENT_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/basictypes.h" 12 #include "base/memory/ref_counted.h" 13 #include "base/strings/string16.h" 14 #include "sql/connection.h" 15 #include "sql/sql_export.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 // s.BindInt(0, a); 32 // if (s.Step()) 33 // return s.ColumnString(0); 34 // 35 // If there are errors getting the statement, the statement will be inert; no 36 // mutating or database-access methods will work. If you need to check for 37 // validity, use: 38 // if (!s.is_valid()) 39 // return false; 40 // 41 // Step() and Run() just return true to signal success. If you want to handle 42 // specific errors such as database corruption, install an error handler in 43 // in the connection object using set_error_delegate(). 44 class SQL_EXPORT Statement { 45 public: 46 // Creates an uninitialized statement. The statement will be invalid until 47 // you initialize it via Assign. 48 Statement(); 49 50 explicit Statement(scoped_refptr<Connection::StatementRef> ref); 51 ~Statement(); 52 53 // Initializes this object with the given statement, which may or may not 54 // be valid. Use is_valid() to check if it's OK. 55 void Assign(scoped_refptr<Connection::StatementRef> ref); 56 57 // Resets the statement to an uninitialized state corrosponding to 58 // the default constructor, releasing the StatementRef. 59 void Clear(); 60 61 // Returns true if the statement can be executed. All functions can still 62 // be used if the statement is invalid, but they will return failure or some 63 // default value. This is because the statement can become invalid in the 64 // middle of executing a command if there is a serious error and the database 65 // has to be reset. 66 bool is_valid() const { return ref_->is_valid(); } 67 68 // Running ------------------------------------------------------------------- 69 70 // Executes the statement, returning true on success. This is like Step but 71 // for when there is no output, like an INSERT statement. 72 bool Run(); 73 74 // Executes the statement, returning true if there is a row of data returned. 75 // You can keep calling Step() until it returns false to iterate through all 76 // the rows in your result set. 77 // 78 // When Step returns false, the result is either that there is no more data 79 // or there is an error. This makes it most convenient for loop usage. If you 80 // need to disambiguate these cases, use Succeeded(). 81 // 82 // Typical example: 83 // while (s.Step()) { 84 // ... 85 // } 86 // return s.Succeeded(); 87 bool Step(); 88 89 // Resets the statement to its initial condition. This includes any current 90 // result row, and also the bound variables if the |clear_bound_vars| is true. 91 void Reset(bool clear_bound_vars); 92 93 // Returns true if the last executed thing in this statement succeeded. If 94 // there was no last executed thing or the statement is invalid, this will 95 // return false. 96 bool Succeeded() const; 97 98 // Binding ------------------------------------------------------------------- 99 100 // These all take a 0-based argument index and return true on success. You 101 // may not always care about the return value (they'll DCHECK if they fail). 102 // The main thing you may want to check is when binding large blobs or 103 // strings there may be out of memory. 104 bool BindNull(int col); 105 bool BindBool(int col, bool val); 106 bool BindInt(int col, int val); 107 bool BindInt64(int col, int64 val); 108 bool BindDouble(int col, double val); 109 bool BindCString(int col, const char* val); 110 bool BindString(int col, const std::string& val); 111 bool BindString16(int col, const string16& value); 112 bool BindBlob(int col, const void* value, int value_len); 113 114 // Retrieving ---------------------------------------------------------------- 115 116 // Returns the number of output columns in the result. 117 int ColumnCount() const; 118 119 // Returns the type associated with the given column. 120 // 121 // Watch out: the type may be undefined if you've done something to cause a 122 // "type conversion." This means requesting the value of a column of a type 123 // where that type is not the native type. For safety, call ColumnType only 124 // on a column before getting the value out in any way. 125 ColType ColumnType(int col) const; 126 ColType DeclaredColumnType(int col) const; 127 128 // These all take a 0-based argument index. 129 bool ColumnBool(int col) const; 130 int ColumnInt(int col) const; 131 int64 ColumnInt64(int col) const; 132 double ColumnDouble(int col) const; 133 std::string ColumnString(int col) const; 134 string16 ColumnString16(int col) const; 135 136 // When reading a blob, you can get a raw pointer to the underlying data, 137 // along with the length, or you can just ask us to copy the blob into a 138 // vector. Danger! ColumnBlob may return NULL if there is no data! 139 int ColumnByteLength(int col) const; 140 const void* ColumnBlob(int col) const; 141 bool ColumnBlobAsString(int col, std::string* blob); 142 bool ColumnBlobAsString16(int col, string16* val) const; 143 bool ColumnBlobAsVector(int col, std::vector<char>* val) const; 144 bool ColumnBlobAsVector(int col, std::vector<unsigned char>* val) const; 145 146 // Diagnostics -------------------------------------------------------------- 147 148 // Returns the original text of sql statement. Do not keep a pointer to it. 149 const char* GetSQLStatement(); 150 151 private: 152 // This is intended to check for serious errors and report them to the 153 // connection object. It takes a sqlite error code, and returns the same 154 // code. Currently this function just updates the succeeded flag, but will be 155 // enhanced in the future to do the notification. 156 int CheckError(int err); 157 158 // Contraction for checking an error code against SQLITE_OK. Does not set the 159 // succeeded flag. 160 bool CheckOk(int err) const; 161 162 // Should be called by all mutating methods to check that the statement is 163 // valid. Returns true if the statement is valid. DCHECKS and returns false 164 // if it is not. 165 // The reason for this is to handle two specific cases in which a Statement 166 // may be invalid. The first case is that the programmer made an SQL error. 167 // Those cases need to be DCHECKed so that we are guaranteed to find them 168 // before release. The second case is that the computer has an error (probably 169 // out of disk space) which is prohibiting the correct operation of the 170 // database. Our testing apparatus should not exhibit this defect, but release 171 // situations may. Therefore, the code is handling disjoint situations in 172 // release and test. In test, we're ensuring correct SQL. In release, we're 173 // ensuring that contracts are honored in error edge cases. 174 bool CheckValid() const; 175 176 // The actual sqlite statement. This may be unique to us, or it may be cached 177 // by the connection, which is why it's refcounted. This pointer is 178 // guaranteed non-NULL. 179 scoped_refptr<Connection::StatementRef> ref_; 180 181 // See Succeeded() for what this holds. 182 bool succeeded_; 183 184 DISALLOW_COPY_AND_ASSIGN(Statement); 185 }; 186 187 } // namespace sql 188 189 #endif // SQL_STATEMENT_H_ 190
