// Copyright (c) 2012 The Chromium Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file.

#ifndef SQL_STATEMENT_H_

#define SQL_STATEMENT_H_

#include <stdint.h>

#include <string>

#include <vector>

#include "base/component_export.h"

#include "base/containers/span.h"

#include "base/memory/ref_counted.h"

#include "base/sequence_checker.h"

#include "base/strings/string_piece_forward.h"

#include "base/time/time.h"

#include "build/build_config.h" // TODO(crbug.com/866218): Remove this include.

#include "sql/database.h"

namespace sql {

// Possible return values from ColumnType in a statement. These should match

// the values in sqlite3.h.

enum class ColumnType {

kInteger = 1,

kFloat = 2,

kText = 3,

kBlob = 4,

kNull = 5,

};

// Compiles and executes SQL statements.

//

// This class is not thread-safe. An instance must be accessed from a single

// sequence. This is enforced in DCHECK-enabled builds.

//

// Normal usage:

// sql::Statement s(connection_.GetUniqueStatement(...));

// s.BindInt(0, a);

// if (s.Step())

// return s.ColumnString(0);

//

// If there are errors getting the statement, the statement will be inert; no

// mutating or database-access methods will work. If you need to check for

// validity, use:

// if (!s.is_valid())

// return false;

//

// Step() and Run() just return true to signal success. If you want to handle

// specific errors such as database corruption, install an error handler in

// in the connection object using set_error_delegate().

class COMPONENT_EXPORT(SQL) Statement {

public:

// Creates an uninitialized statement. The statement will be invalid until

// you initialize it via Assign.

Statement();

explicit Statement(scoped_refptr<Database::StatementRef> ref);

Statement(const Statement&) = delete;

Statement& operator=(const Statement&) = delete;

~Statement();

// Initializes this object with the given statement, which may or may not

// be valid. Use is_valid() to check if it's OK.

void Assign(scoped_refptr<Database::StatementRef> ref);

// Resets the statement to an uninitialized state corresponding to

// the default constructor, releasing the StatementRef.

void Clear();

// Returns true if the statement can be executed. All functions can still

// be used if the statement is invalid, but they will return failure or some

// default value. This is because the statement can become invalid in the

// middle of executing a command if there is a serious error and the database

// has to be reset.

bool is_valid() const {

#if !defined(OS_ANDROID) // TODO(crbug.com/866218): Remove this conditional

DCHECK_CALLED_ON_VALID_SEQUENCE(sequence_checker_);

#endif // !defined(OS_ANDROID)

return ref_->is_valid();

}

// Running -------------------------------------------------------------------

// Executes the statement, returning true on success. This is like Step but

// for when there is no output, like an INSERT statement.

bool Run();

// Executes the statement, returning true if there is a row of data returned.

// You can keep calling Step() until it returns false to iterate through all

// the rows in your result set.

//

// When Step returns false, the result is either that there is no more data

// or there is an error. This makes it most convenient for loop usage. If you

// need to disambiguate these cases, use Succeeded().

//

// Typical example:

// while (s.Step()) {

// ...

// }

// return s.Succeeded();

bool Step();

// Resets the statement to its initial condition. This includes any current

// result row, and also the bound variables if the |clear_bound_vars| is true.

void Reset(bool clear_bound_vars);

// Returns true if the last executed thing in this statement succeeded. If

// there was no last executed thing or the statement is invalid, this will

// return false.

bool Succeeded() const;

// Binding -------------------------------------------------------------------

// These all take a 0-based argument index and return true on success. You

// may not always care about the return value (they'll DCHECK if they fail).

// The main thing you may want to check is when binding large blobs or

// strings there may be out of memory.

bool BindNull(int col);

bool BindBool(int col, bool val);

bool BindInt(int col, int val);

bool BindInt(int col, int64_t val) = delete; // Call BindInt64() instead.

bool BindInt64(int col, int64_t val);

bool BindDouble(int col, double val);

bool BindCString(int col, const char* val);

bool BindString(int col, base::StringPiece val);

bool BindString16(int col, base::StringPiece16 value);

bool BindBlob(int col, base::span<const uint8_t> value);

// Overload that makes it easy to pass in std::string values.

bool BindBlob(int col, base::span<const char> value) {

return BindBlob(col, base::as_bytes(base::make_span(value)));

}

// Conforms with base::Time serialization recommendations.

//

// This is equivalent to the following snippets, which should be replaced.

// * BindInt64(col, val.ToInternalValue())

// * BindInt64(col, val.ToDeltaSinceWindowsEpoch().InMicroseconds())

//

// Features that serialize base::Time in other ways, such as ToTimeT() or

// ToJavaTime(), will require a database migration to be converted to this

// (recommended) serialization method.

//

// TODO(crbug.com/1195962): Migrate all time serialization to this method, and

// then remove the migration details above.

bool BindTime(int col, base::Time time);

// Retrieving ----------------------------------------------------------------

// Returns the number of output columns in the result.

int ColumnCount() const;

// Returns the type associated with the given column.

//

// Watch out: the type may be undefined if you've done something to cause a

// "type conversion." This means requesting the value of a column of a type

// where that type is not the native type. For safety, call ColumnType only

// on a column before getting the value out in any way.

ColumnType GetColumnType(int col) const;

// These all take a 0-based argument index.

bool ColumnBool(int col) const;

int ColumnInt(int col) const;

int64_t ColumnInt64(int col) const;

double ColumnDouble(int col) const;

std::string ColumnString(int col) const;

std::u16string ColumnString16(int col) const;

// Conforms with base::Time serialization recommendations.

//

// This is equivalent to the following snippets, which should be replaced.

// * base::Time::FromInternalValue(ColumnInt64(col))

// * base::Time::FromDeltaSinceWindowsEpoch(

// base::TimeDelta::FromMicroseconds(ColumnInt64(col)))

//

// TODO(crbug.com/1195962): Migrate all time serialization to this method, and

// then remove the migration details above.

base::Time ColumnTime(int col) const;

// When reading a blob, you can get a raw pointer to the underlying data,

// along with the length, or you can just ask us to copy the blob into a

// vector. Danger! ColumnBlob may return nullptr if there is no data!

int ColumnByteLength(int col) const;

const void* ColumnBlob(int col) const;

bool ColumnBlobAsString(int col, std::string* blob) const;

bool ColumnBlobAsString16(int col, std::u16string* val) const;

bool ColumnBlobAsVector(int col, std::vector<char>* val) const;

bool ColumnBlobAsVector(int col, std::vector<uint8_t>* val) const;

// Diagnostics --------------------------------------------------------------

// Returns the original text of sql statement. Do not keep a pointer to it.

const char* GetSQLStatement();

private:

friend class Database;

// This is intended to check for serious errors and report them to the

// Database object. It takes a sqlite error code, and returns the same

// code. Currently this function just updates the succeeded flag, but will be

// enhanced in the future to do the notification.

int CheckError(int err);

// Contraction for checking an error code against SQLITE_OK. Does not set the

// succeeded flag.

bool CheckOk(int err) const;

// Should be called by all mutating methods to check that the statement is

// valid. Returns true if the statement is valid. DCHECKS and returns false

// if it is not.

// The reason for this is to handle two specific cases in which a Statement

// may be invalid. The first case is that the programmer made an SQL error.

// Those cases need to be DCHECKed so that we are guaranteed to find them

// before release. The second case is that the computer has an error (probably

// out of disk space) which is prohibiting the correct operation of the

// database. Our testing apparatus should not exhibit this defect, but release

// situations may. Therefore, the code is handling disjoint situations in

// release and test. In test, we're ensuring correct SQL. In release, we're

// ensuring that contracts are honored in error edge cases.

bool CheckValid() const;

// Helper for Run() and Step(), calls sqlite3_step() and returns the checked

// value from it.

int StepInternal();

// The actual sqlite statement. This may be unique to us, or it may be cached

// by the Database, which is why it's ref-counted. This pointer is

// guaranteed non-null.

scoped_refptr<Database::StatementRef> ref_;

// Set after Step() or Run() are called, reset by Reset(). Used to

// prevent accidental calls to API functions which would not work

// correctly after stepping has started.

bool stepped_ = false;

// See Succeeded() for what this holds.

bool succeeded_ = false;

SEQUENCE_CHECKER(sequence_checker_);

};

} // namespace sql

#endif // SQL_STATEMENT_H_