dvander@868: /**
dvander@868: * vim: set ts=4 :
ds@1330: * =============================================================================
ds@1947: * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
ds@1330: * =============================================================================
ds@1330: *
ds@1330: * This file is part of the SourceMod/SourcePawn SDK.
dvander@868: *
ds@1330: * This program is free software; you can redistribute it and/or modify it under
ds@1330: * the terms of the GNU General Public License, version 3.0, as published by the
ds@1330: * Free Software Foundation.
ds@1330: *
ds@1330: * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1330: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1330: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1330: * details.
ds@1330: *
ds@1330: * You should have received a copy of the GNU General Public License along with
ds@1330: * this program. If not, see .
ds@1330: *
ds@1330: * As a special exception, AlliedModders LLC gives you permission to link the
ds@1330: * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1330: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1330: * by the Valve Corporation. You must obey the GNU General Public License in
ds@1330: * all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1330: * this exception to all derivative works. AlliedModders LLC defines further
ds@1330: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1330: * or .
dvander@868: *
dvander@868: * Version: $Id$
dvander@868: */
dvander@868:
dvander@868: #if defined _dbi_included
dvander@868: #endinput
dvander@868: #endif
dvander@868: #define _dbi_included
dvander@868:
dvander@868: /**
dvander@868: * @handle Driver
dvander@868: *
dvander@868: * Contains information about an SQL driver.
dvander@868: */
dvander@868:
dvander@868: /**
dvander@868: * @handle Database
dvander@868: *
dvander@868: * Contains information about a database connection.
dvander@868: */
dvander@868:
dvander@868: /**
dvander@868: * @handle Query
dvander@868: *
dvander@868: * Contains information about an active query and its
dvander@868: * result sets.
dvander@868: */
dvander@868:
dvander@868: /**
dvander@868: * @handle Statement : Query
dvander@868: *
dvander@868: * Extends a Query Handle and can be used as a Query Handle.
dvander@868: * Statement Handles are for prepared queries and contain
dvander@868: * their own function for binding parameters. Statement
dvander@868: * Handles can be used instead of database Handles in a few
dvander@868: * select functions.
dvander@868: */
dvander@868:
dvander@868: /**
dvander@868: * Describes a database field fetch status.
dvander@868: */
dvander@868: enum DBResult
dvander@868: {
dvander@868: DBVal_Error = 0, /**< Column number/field is invalid. */
dvander@868: DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type. */
dvander@868: DBVal_Null = 2, /**< Field has no data (NULL) */
dvander@868: DBVal_Data = 3, /**< Field has data */
dvander@1096: };
dvander@1096:
dvander@1096: /**
dvander@1096: * Describes binding types.
dvander@1096: */
dvander@1096: enum DBBindType
dvander@1096: {
dvander@1096: DBBind_Int = 0, /**< Bind an integer. */
dvander@1096: DBBind_Float = 1, /**< Bind a float. */
dvander@1096: DBBind_String = 2, /**< Bind a string. */
dvander@1096: };
dvander@1096:
dvander@1096: /**
dvander@1096: * Threading priority level.
dvander@1096: */
dvander@1096: enum DBPriority
dvander@1096: {
dvander@1096: DBPrio_High = 0, /**< High priority. */
dvander@1096: DBPrio_Normal = 1, /**< Normal priority. */
dvander@1096: DBPrio_Low = 2, /**< Low priority. */
dvander@1096: };
dvander@868:
dvander@868: /**
dvander@868: * Creates an SQL connection from a named configuration.
dvander@868: *
dvander@868: * @param confname Named configuration.
dvander@868: * @param persistent True to re-use a previous persistent connection if
dvander@868: * possible, false otherwise.
dvander@868: * @param error Error buffer.
dvander@868: * @param maxlength Maximum length of the error buffer.
dvander@868: * @return A database connection Handle, or INVALID_HANDLE on failure.
dvander@868: */
dvander@868: native Handle:SQL_Connect(const String:confname[], bool:persistent, String:error[], maxlength);
dvander@868:
dvander@868: /**
dvander@868: * Creates a default SQL connection.
dvander@868: *
dvander@868: * @param error Error buffer.
dvander@868: * @param maxlength Maximum length of the error buffer.
dvander@868: * @param persistent True to re-use a previous persistent connection
dvander@868: * if possible, false otherwise.
dvander@868: * @return A database connection Handle, or INVALID_HANDLE on failure.
dvander@2357: * On failure the error buffer will be filled with a message.
dvander@868: */
dvander@868: stock Handle:SQL_DefConnect(String:error[], maxlength, bool:persistent=true)
dvander@868: {
dvander@868: return SQL_Connect("default", persistent, error, maxlength);
dvander@868: }
dvander@868:
dvander@868: /**
dvander@2357: * Connects to a database using key value pairs containing the database info.
dvander@2357: * The key/value pairs should match what would be in databases.cfg.
dvander@868: *
dvander@2357: * I.e. "driver" should be "default" or a driver name (or ommitted for
dvander@2357: * the default). For SQLite, only the "database" parameter is needed in addition.
dvander@2357: * For drivers which require external connections, more of the parameters may be
dvander@2357: * needed.
dvander@2357: *
dvander@2357: * In general it is discouraged to use this function. Connections should go through
dvander@2357: * databases.cfg for greatest flexibility on behalf of users.
dvander@2357: *
dvander@2357: * @param keyvalues Key/value pairs from a KeyValues handle, describing the connection.
dvander@868: * @param error Error buffer.
dvander@868: * @param maxlength Maximum length of the error buffer.
dvander@2357: * @return A database connection Handle, or INVALID_HANDLE on failure.
dvander@2357: * On failure the error buffer will be filled with a message.
dvander@2357: * @error Invalid KeyValues handle.
dvander@2357: */
dvander@2357: native Handle:SQL_ConnectCustom(Handle:keyvalues,
dvander@2357: String:error[],
dvander@2357: maxlength,
dvander@2357: bool:persistent);
dvander@2357:
dvander@2357: /**
dvander@2357: * Grabs a handle to an SQLite database, creating one if it does not exist.
dvander@2357: *
dvander@2357: * Unless there are extenuating circumstances, you should consider using "sourcemod-local" as the
dvander@2571: * database name. This provides some unification between plugins on behalf of users.
dvander@2357: *
dvander@2357: * As a precaution, you should always create some sort of unique prefix to your table names so
dvander@2357: * there are no conflicts, and you should never drop or modify tables that you do not own.
dvander@2357: *
dvander@2357: * @param database Database name.
dvander@2357: * @param error Error buffer.
dvander@2357: * @param maxlength Maximum length of the error buffer.
dvander@868: * @return A database connection Handle, or INVALID_HANDLE on failure.
dvander@2357: * On failure the error buffer will be filled with a message.
dvander@868: */
dvander@2357: stock Handle:SQLite_UseDatabase(const String:database[],
dvander@2571: String:error[],
dvander@2357: maxlength)
dvander@2357: {
dvander@2357: new Handle:kv, Handle:db;
dvander@2357:
dvander@2357: kv = CreateKeyValues("");
dvander@2357: KvSetString(kv, "driver", "sqlite");
dvander@2357: KvSetString(kv, "database", database);
dvander@2357:
dvander@2571: db = SQL_ConnectCustom(kv, error, maxlength, false);
dvander@2357:
dvander@2357: CloseHandle(kv);
dvander@2357:
dvander@2357: return db;
dvander@2357: }
dvander@2357:
dvander@2357: /**
dvander@2357: * This function is deprecated. Use SQL_ConnectCustom or SQLite_UseDatabase instead.
dvander@2357: */
dvander@2357: #pragma deprecated Use SQL_ConnectCustom instead.
dvander@868: native Handle:SQL_ConnectEx(Handle:driver,
dvander@868: const String:host[],
dvander@868: const String:user[],
dvander@868: const String:pass[],
dvander@868: const String:database[],
dvander@868: String:error[],
dvander@868: maxlength,
dvander@868: bool:persistent=true,
dvander@868: port=0,
dvander@868: maxTimeout=0);
dvander@1324:
dvander@1324: /**
dvander@1324: * Returns if a named configuration is present in databases.cfg.
dvander@1324: *
dvander@1324: * @param name Configuration name.
dvander@1324: * @return True if it exists, false otherwise.
dvander@1324: */
dvander@1324: native bool:SQL_CheckConfig(const String:name[]);
dvander@868:
dvander@868: /**
dvander@868: * Returns a driver Handle from a name string.
dvander@868: *
dvander@868: * If the driver is not found, SourceMod will attempt
dvander@868: * to load an extension named dbi..ext.[dll|so].
dvander@868: *
dvander@868: * @param name Driver identification string, or an empty
dvander@868: * string to return the default driver.
dvander@868: * @return Driver Handle, or INVALID_HANDLE on failure.
dvander@868: */
dvander@868: native Handle:SQL_GetDriver(const String:name[]="");
dvander@868:
dvander@868: /**
dvander@1294: * Reads the driver of an opened database.
dvander@1294: *
dvander@1294: * @param database Database Handle.
dvander@1294: * @param ident Option buffer to store the identification string.
dvander@1294: * @param ident_length Maximum length of the buffer.
dvander@1294: * @return Driver Handle.
dvander@1294: */
dvander@1294: native Handle:SQL_ReadDriver(Handle:database, String:ident[]="", ident_length=0);
dvander@1294:
dvander@1294: /**
dvander@868: * Retrieves a driver's identification string.
dvander@868: *
dvander@1294: * Example: "mysql", "sqlite"
dvander@1294: *
dvander@868: * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
dvander@868: * @param ident Identification string buffer.
dvander@868: * @param maxlength Maximum length of the buffer.
dvander@868: * @noreturn
dvander@868: * @error Invalid Handle other than INVALID_HANDLE.
dvander@868: */
dvander@868: native SQL_GetDriverIdent(Handle:driver, String:ident[], maxlength);
dvander@868:
dvander@868: /**
dvander@868: * Retrieves a driver's product string.
dvander@868: *
dvander@1294: * Example: "MySQL", "SQLite"
dvander@1294: *
dvander@868: * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
dvander@868: * @param product Product string buffer.
dvander@868: * @param maxlength Maximum length of the buffer.
dvander@868: * @noreturn
dvander@868: * @error Invalid Handle other than INVALID_HANDLE.
dvander@868: */
dvander@868: native SQL_GetDriverProduct(Handle:driver, String:product[], maxlength);
dvander@868:
dvander@868: /**
dvander@868: * Returns the number of affected rows from the last query.
dvander@868: *
dvander@868: * @param hndl A database OR statement Handle.
dvander@868: * @return Number of rows affected by the last query.
dvander@868: * @error Invalid database or statement Handle.
dvander@868: */
dvander@868: native SQL_GetAffectedRows(Handle:hndl);
dvander@868:
dvander@868: /**
dvander@868: * Returns the last query's insertion id.
dvander@868: *
dvander@868: * @param hndl A database OR statement Handle.
dvander@868: * @return Last query's insertion id.
dvander@868: * @error Invalid database or statement Handle.
dvander@868: */
dvander@868: native SQL_GetInsertId(Handle:hndl);
dvander@868:
dvander@868: /**
dvander@868: * Returns the error reported by the last query.
dvander@868: *
dvander@868: * @param hndl A database OR statement Handle.
dvander@868: * @param error Error buffer.
dvander@868: * @param maxlength Maximum length of the buffer.
dvander@868: * @return True if there was an error, false otherwise.
dvander@868: * @error Invalid database or statement Handle.
dvander@868: */
dvander@868: native bool:SQL_GetError(Handle:hndl, String:error[], maxlength);
dvander@868:
dvander@868: /**
dvander@1874: * Escapes a database string for literal insertion. This is not needed
dvander@1874: * for binding strings in prepared statements.
dvander@1874: *
dvander@1874: * Generally, database strings are inserted into queries enclosed in
dvander@1874: * single quotes ('). If user input has a single quote in it, the
dvander@1874: * quote needs to be escaped. This function ensures that any unsafe
dvander@1874: * characters are safely escaped according to the database engine and
dvander@1874: * the database's character set.
dvander@868: *
dvander@2767: * NOTE: SourceMod only guarantees properly escaped strings when the query
dvander@2767: * encloses the string in ''. While drivers tend to allow " instead, the string
dvander@2767: * may be not be escaped (for example, on SQLite)!
dvander@2767: *
dvander@868: * @param hndl A database Handle.
dvander@868: * @param string String to quote.
dvander@868: * @param buffer Buffer to store quoted string in.
dvander@868: * @param maxlength Maximum length of the buffer.
dvander@868: * @param written Optionally returns the number of bytes written.
dvander@868: * @return True on success, false if buffer is not big enough.
dvander@868: * The buffer must be at least 2*strlen(string)+1.
dvander@868: * @error Invalid database or statement Handle.
dvander@868: */
dvander@1874: native bool:SQL_EscapeString(Handle:database,
dvander@1874: const String:string[],
dvander@1874: String:buffer[],
dvander@1874: maxlength,
dvander@1874: &written=0);
dvander@1874:
dvander@1874: /**
dvander@1874: * This is a backwards compatibility stock. You should use SQL_EscapeString()
dvander@1874: * instead, as this function will probably be deprecated in SourceMod 1.1.
dvander@1874: */
dvander@1874: stock bool:SQL_QuoteString(Handle:database,
dvander@1874: const String:string[],
dvander@1874: String:buffer[],
dvander@1874: maxlength,
dvander@1874: &written=0)
dvander@1874: {
dvander@1874: return SQL_EscapeString(database, string, buffer, maxlength, written);
dvander@1874: }
dvander@868:
dvander@868: /**
dvander@868: * Executes a query and ignores the result set.
dvander@868: *
dvander@868: * @param database A database Handle.
dvander@868: * @param query Query string.
dvander@1912: * @param len Optional parameter to specify the query length, in
dvander@1912: * bytes. This can be used to send binary queries that
dvander@1912: * have a premature terminator.
dvander@868: * @return True if query succeeded, false otherwise. Use
dvander@868: * SQL_GetError to find the last error.
dvander@868: * @error Invalid database Handle.
dvander@868: */
dvander@1912: native bool:SQL_FastQuery(Handle:database, const String:query[], len=-1);
dvander@868:
dvander@868: /**
dvander@868: * Executes a simple query and returns a new query Handle for
dvander@868: * receiving the results.
dvander@868: *
dvander@868: * @param database A database Handle.
dvander@868: * @param query Query string.
dvander@1912: * @param len Optional parameter to specify the query length, in
dvander@1912: * bytes. This can be used to send binary queries that
dvander@1912: * have a premature terminator.
dvander@868: * @return A new Query Handle on success, INVALID_HANDLE
dvander@868: * otherwise. The Handle must be freed with CloseHandle().
dvander@868: * @error Invalid database Handle.
dvander@868: */
dvander@1912: native Handle:SQL_Query(Handle:database, const String:query[], len=-1);
dvander@868:
dvander@868: /**
dvander@868: * Creates a new prepared statement query. Prepared statements can
dvander@868: * be executed any number of times. They can also have placeholder
dvander@868: * parameters, similar to variables, which can be bound safely and
dvander@868: * securely (for example, you do not need to quote bound strings).
dvander@868: *
dvander@868: * Statement handles will work in any function that accepts a Query handle.
dvander@868: *
dvander@868: * @param database A database Handle.
dvander@868: * @param query Query string.
dvander@868: * @param error Error buffer.
dvander@868: * @param maxlength Maximum size of the error buffer.
dvander@868: * @return A new statement Handle on success, INVALID_HANDLE
dvander@868: * otherwise. The Handle must be freed with CloseHandle().
dvander@868: * @error Invalid database Handle.
dvander@868: */
dvander@868: native Handle:SQL_PrepareQuery(Handle:database, const String:query[], String:error[], maxlength);
dvander@868:
dvander@868: /**
dvander@868: * Advances to the next set of results.
dvander@868: *
dvander@868: * In some SQL implementations, multiple result sets can exist on one query.
dvander@868: * This is possible in MySQL with simple queries when executing a CALL
dvander@868: * query. If this is the case, all result sets must be processed before
dvander@868: * another query is made.
dvander@868: *
dvander@868: * @param query A query Handle.
dvander@868: * @return True if there was another result set, false otherwise.
dvander@868: * @error Invalid query Handle.
dvander@868: */
dvander@868: native bool:SQL_FetchMoreResults(Handle:query);
dvander@868:
dvander@868: /**
dvander@868: * Returns whether or not a result set exists. This will
dvander@868: * return true even if 0 results were returned, but false
dvander@868: * on queries like UPDATE, INSERT, or DELETE.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @return True if there is a result set, false otherwise.
dvander@868: * @error Invalid query Handle.
dvander@868: */
dvander@868: native bool:SQL_HasResultSet(Handle:query);
dvander@868:
dvander@868: /**
dvander@868: * Retrieves the number of rows in the last result set.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@869: * @return Number of rows in the current result set.
dvander@868: * @error Invalid query Handle.
dvander@868: */
dvander@868: native SQL_GetRowCount(Handle:query);
dvander@868:
dvander@868: /**
dvander@869: * Retrieves the number of fields in the last result set.
dvander@869: *
dvander@869: * @param query A query (or statement) Handle.
dvander@869: * @return Number of fields in the current result set.
dvander@869: * @error Invalid query Handle.
dvander@869: */
dvander@869: native SQL_GetFieldCount(Handle:query);
dvander@869:
dvander@869: /**
dvander@868: * Retrieves the name of a field by index.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field Field number (starting from 0).
dvander@868: * @param name Name buffer.
dvander@868: * @param maxlength Maximum length of the name buffer.
dvander@868: * @noreturn
dvander@868: * @error Invalid query Handle, invalid field index, or
dvander@868: * no current result set.
dvander@868: */
dvander@868: native SQL_FieldNumToName(Handle:query, field, String:name[], maxlength);
dvander@868:
dvander@868: /**
dvander@868: * Retrieves a field index by name.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param name Name of the field (case sensitive).
dvander@868: * @param field Variable to store field index in.
dvander@868: * @return True if found, false if not found.
dvander@868: * @error Invalid query Handle or no current result set.
dvander@868: */
dvander@868: native bool:SQL_FieldNameToNum(Handle:query, const String:name[], &field);
dvander@868:
dvander@868: /**
dvander@868: * Fetches a row from the current result set. This must be
dvander@868: * successfully called before any results are fetched.
dvander@868: *
dvander@868: * If this function fails, SQL_MoreResults() can be used to
dvander@868: * tell if there was an error or the result set is finished.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @return True if a row was fetched, false otherwise.
dvander@868: * @error Invalid query Handle.
dvander@868: */
dvander@868: native bool:SQL_FetchRow(Handle:query);
dvander@868:
dvander@868: /**
dvander@868: * Returns if there are more rows.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @return True if there are more rows, false otherwise.
dvander@868: * @error Invalid query Handle.
dvander@868: */
dvander@868: native bool:SQL_MoreRows(Handle:query);
dvander@868:
dvander@868: /**
dvander@868: * Rewinds a result set back to the first result.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @return True on success, false otherwise.
dvander@868: * @error Invalid query Handle or no current result set.
dvander@868: */
dvander@868: native bool:SQL_Rewind(Handle:query);
dvander@868:
dvander@868: /**
dvander@868: * Fetches a string from a field in the current row of a result set.
dvander@868: * If the result is NULL, an empty string will be returned. A NULL
dvander@868: * check can be done with the result parameter, or SQL_IsFieldNull().
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field The field index (starting from 0).
dvander@868: * @param buffer String buffer.
dvander@868: * @param maxlength Maximum size of the string buffer.
dvander@868: * @param result Optional variable to store the status of the return value.
dvander@868: * @return Number of bytes written.
dvander@868: * @error Invalid query Handle or field index, invalid
dvander@868: * type conversion requested from the database,
dvander@868: * or no current result set.
dvander@868: */
dvander@868: native SQL_FetchString(Handle:query, field, String:buffer[], maxlength, &DBResult:result=DBVal_Error);
dvander@868:
dvander@868: /**
dvander@868: * Fetches a float from a field in the current row of a result set.
dvander@868: * If the result is NULL, a value of 0.0 will be returned. A NULL
dvander@868: * check can be done with the result parameter, or SQL_IsFieldNull().
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field The field index (starting from 0).
dvander@868: * @param result Optional variable to store the status of the return value.
dvander@868: * @return A float value.
dvander@868: * @error Invalid query Handle or field index, invalid
dvander@868: * type conversion requested from the database,
dvander@868: * or no current result set.
dvander@868: */
dvander@868: native Float:SQL_FetchFloat(Handle:query, field, &DBResult:result=DBVal_Error);
dvander@868:
dvander@868: /**
dvander@868: * Fetches an integer from a field in the current row of a result set.
dvander@868: * If the result is NULL, a value of 0 will be returned. A NULL
dvander@868: * check can be done with the result parameter, or SQL_IsFieldNull().
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field The field index (starting from 0).
dvander@868: * @param result Optional variable to store the status of the return value.
dvander@868: * @return An integer value.
dvander@868: * @error Invalid query Handle or field index, invalid
dvander@868: * type conversion requested from the database,
dvander@868: * or no current result set.
dvander@868: */
dvander@868: native SQL_FetchInt(Handle:query, field, &DBResult:result=DBVal_Error);
dvander@868:
dvander@868: /**
dvander@868: * Returns whether a field's data in the current row of a result set is
dvander@868: * NULL or not. NULL is an SQL type which means "no data."
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field The field index (starting from 0).
dvander@868: * @return True if data is NULL, false otherwise.
dvander@868: * @error Invalid query Handle or field index, or no
dvander@868: * current result set.
dvander@868: */
dvander@868: native bool:SQL_IsFieldNull(Handle:query, field);
dvander@868:
dvander@868: /**
dvander@868: * Returns the length of a field's data in the current row of a result
dvander@868: * set. This only needs to be called for strings to determine how many
dvander@868: * bytes to use. Note that the return value does not include the null
dvander@868: * terminator.
dvander@868: *
dvander@868: * @param query A query (or statement) Handle.
dvander@868: * @param field The field index (starting from 0).
dvander@868: * @return Number of bytes for the field's data size.
dvander@868: * @error Invalid query Handle or field index or no
dvander@868: * current result set.
dvander@868: */
dvander@868: native SQL_FetchSize(Handle:query, field);
dvander@868:
dvander@868: /**
dvander@868: * Binds a parameter in a prepared statement to a given integer value.
dvander@868: *
dvander@868: * @param statement A statement (prepared query) Handle.
dvander@868: * @param param The parameter index (starting from 0).
dvander@868: * @param number The number to bind.
dvander@868: * @param signed True to bind the number as signed, false to
dvander@868: * bind it as unsigned.
dvander@868: * @noreturn
dvander@868: * @error Invalid statement Handle or parameter index, or
dvander@868: * SQL error.
dvander@868: */
dvander@868: native SQL_BindParamInt(Handle:statement, param, number, bool:signed=true);
dvander@868:
dvander@868: /**
dvander@868: * Binds a parameter in a prepared statement to a given float value.
dvander@868: *
dvander@868: * @param statement A statement (prepared query) Handle.
dvander@868: * @param param The parameter index (starting from 0).
dvander@868: * @param float The float number to bind.
dvander@868: * @noreturn
dvander@868: * @error Invalid statement Handle or parameter index, or
dvander@868: * SQL error.
dvander@868: */
dvander@868: native SQL_BindParamFloat(Handle:statement, param, Float:value);
dvander@868:
dvander@868: /**
dvander@868: * Binds a parameter in a prepared statement to a given string value.
dvander@868: *
dvander@868: * @param statement A statement (prepared query) Handle.
dvander@868: * @param param The parameter index (starting from 0).
dvander@868: * @param value The string to bind.
dvander@868: * @param copy Whether or not SourceMod should copy the value
dvander@868: * locally if necessary. If the string contents
dvander@868: * won't change before calling SQL_Execute(), this
dvander@868: * can be set to false for optimization.
dvander@868: * @noreturn
dvander@868: * @error Invalid statement Handle or parameter index, or
dvander@868: * SQL error.
dvander@868: */
dvander@868: native SQL_BindParamString(Handle:statement, param, const String:value[], bool:copy);
dvander@868:
dvander@868: /**
dvander@868: * Executes a prepared statement. All parameters must be bound beforehand.
dvander@868: *
dvander@868: * @param statement A statement (prepared query) Handle.
dvander@868: * @return True on success, false on failure.
dvander@868: * @error Invalid statement Handle.
dvander@868: */
dvander@868: native bool:SQL_Execute(Handle:statement);
dvander@1096:
dvander@1096: /**
dvander@1096: * Locks a database so threading operations will not interrupt.
dvander@1096: *
dvander@1096: * If you are using a database Handle for both threading and non-threading,
dvander@1096: * this MUST be called before doing any set of non-threading DB operations.
dvander@1096: * Otherwise you risk corrupting the database driver's memory or network
dvander@1096: * connection.
dvander@1096: *
dvander@1096: * Leaving a lock on a database and then executing a threaded query results
dvander@1096: * in a dead lock! Make sure to call SQL_UnlockDatabase()!
dvander@1096: *
dvander@1096: * If the lock cannot be acquired, the main thread will pause until the
dvander@1096: * threaded operation has concluded.
dvander@1096: *
dvander@1096: * @param database A database Handle.
dvander@1096: * @noreturn
dvander@1096: * @error Invalid database Handle.
dvander@1096: */
dvander@1096: native SQL_LockDatabase(Handle:database);
dvander@1096:
dvander@1096: /**
dvander@1096: * Unlocks a database so threading operations may continue.
dvander@1096: *
dvander@1096: * @param database A database Handle.
dvander@1096: * @noreturn
dvander@1096: * @error Invalid database Handle.
dvander@1096: */
dvander@1096: native SQL_UnlockDatabase(Handle:database);
dvander@1096:
dvander@1096: /**
dvander@1096: * General callback for threaded SQL stuff.
dvander@1096: *
dvander@1096: * @param db Parent object of the Handle (or INVALID_HANDLE if none).
dvander@1096: * @param hndl Handle to the child object (or INVALID_HANDLE if none).
dvander@1449: * @param error Error string if there was an error. The error could be
dvander@1449: * empty even if an error condition exists, so it is important
dvander@1449: * to check the actual Handle value instead.
dvander@1449: * @param data Data passed in via the original threaded invocation.
dvander@1096: * @param
dvander@1096: */
dvander@2317: functag public SQLTCallback(Handle:owner, Handle:hndl, const String:error[], any:data);
dvander@1096:
dvander@1096: /**
dvander@1096: * Tells whether two database handles both point to the same database
dvander@1096: * connection.
dvander@1096: *
dvander@1096: * @param hndl1 First database Handle.
dvander@1096: * @param hndl2 Second database Handle.
dvander@1096: * @return True if the Handles point to the same
dvander@1096: * connection, false otherwise.
dvander@1096: * @error Invalid Handle.
dvander@1096: */
dvander@1096: native bool:SQL_IsSameConnection(Handle:hndl1, Handle:hndl2);
dvander@1096:
dvander@1096: /**
dvander@1096: * Connects to a database via a thread. This can be used instead of
dvander@1096: * SQL_Connect() if you wish for non-blocking functionality.
dvander@1096: *
dvander@1096: * It is not necessary to use this to use threaded queries. However, if you
dvander@1096: * don't (or you mix threaded/non-threaded queries), you should see
dvander@1096: * SQL_LockDatabase().
dvander@1096: *
dvander@1096: * @param callback Callback; new Handle will be in hndl, owner is the driver.
dvander@1096: * If no driver was found, the owner is INVALID_HANDLE.
dvander@1096: * @param name Database name.
dvander@1096: * @noreturn
dvander@1096: */
dvander@1317: native SQL_TConnect(SQLTCallback:callback, const String:name[]="default", any:data=0);
dvander@1096:
dvander@1096: /**
dvander@1096: * Executes a simple query via a thread. The query Handle is passed through
dvander@1096: * the callback.
dvander@1096: *
dvander@1096: * The database Handle returned through the callback is always a new Handle,
dvander@1096: * and if necessary, SQL_IsSameConnection() should be used to test against
dvander@1096: * other conenctions.
dvander@1096: *
dvander@1096: * The query Handle returned through the callback is temporary and destroyed
dvander@1096: * at the end of the callback. If you need to hold onto it, use CloneHandle().
dvander@1096: *
dvander@1096: * @param database A database Handle.
dvander@1096: * @param callback Callback; database is in "owner" and the query Handle
dvander@1096: * is passed in "hndl".
dvander@1096: * @param query Query string.
dvander@1096: * @param data Extra data value to pass to the callback.
dvander@1096: * @param prio Priority queue to use.
dvander@1096: * @noreturn
dvander@1096: * @error Invalid database Handle.
dvander@1096: */
dvander@1096: native SQL_TQuery(Handle:database, SQLTCallback:callback, const String:query[], any:data=0, DBPriority:prio=DBPrio_Normal);