dvander@868: /**
dvander@868:  * vim: set ts=4 :
dvander@868:  * ===============================================================
dvander@868:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
dvander@868:  * ===============================================================
dvander@868:  *
dvander@868:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
dvander@868:  * or modified under the Terms and Conditions of its License Agreement, which is found 
dvander@868:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
dvander@868:  * may change at any time.  To view the latest information, see:
dvander@868:  *   http://www.sourcemod.net/license.php
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@868: }
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@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@868:  * Creates an SQL connection from specific parameters.
dvander@868:  *
dvander@868:  * @param driver		Driver Handle, or INVALID_HANDLE for default.
dvander@868:  * @param host			Host name.
dvander@868:  * @param user			User name.
dvander@868:  * @param pass			User password.
dvander@868:  * @param database		Database name.
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:  * @param port			Optional port to specify.
dvander@868:  * @param maxTimeout	Maximum timeout in seconds if applicable.
dvander@868:  * @return				A database connection Handle, or INVALID_HANDLE on failure.
dvander@868:  * @error				Invalid driver Handle other than INVALID_HANDLE.
dvander@868:  */
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@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.<name>.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@868:  * Retrieves a driver's identification string.
dvander@868:  *
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@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@868:  * Quotes a database string for literal insertion.  This is not needed
dvander@868:  * for binding strings in prepared statements.
dvander@868:  *
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@868: native bool:SQL_QuoteString(Handle:database, const String:string[], String:buffer[], maxlength, &written=0);
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@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@868: native bool:SQL_FastQuery(Handle:database, const String:query[]);
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@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@868: native Handle:SQL_Query(Handle:database, const String:query[]);
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);