OLD | NEW |
| (Empty) |
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. | |
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_ | |
OLD | NEW |