sourcemod/plugins/include/dbi.inc
Scott Ehlert 251cced1f8 Spring Cleaning, Part Ichi (1)
Various minor things done to project files
Updated sample extension project file and updated makefile to the new unified version (more changes likely on the way)
Updated regex project file and makefile

--HG--
extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%401971
2008-03-30 07:00:22 +00:00

634 lines
22 KiB
SourcePawn

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