amxmodx/plugins/include/dbi.inc

155 lines
4.2 KiB
SourcePawn
Raw Normal View History

// vim: set ts=4 sw=4 tw=99 noet:
//
// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
// Copyright (C) The AMX Mod X Development Team.
//
// This software is licensed under the GNU General Public License, version 3 or higher.
// Additional exceptions apply. For full license details, see LICENSE.txt or visit:
// https://alliedmods.net/amxmodx-license
//
// SQL Database API
//
//
// Notes - Read the comments! Make sure your plugins use
// nice ANSI SQL and don't use database column names like "key"
// otherwise this API will be a nightmare
//
// Never do error checking with the not operator! This is bad:
// if (!dbi_query())
// You should do:
// ret = dbi_query()
// if (ret < 0)
// This is because DBI functions can and will return negative numbers
// Negative numbers evaluate to "true" in AMX.
//
2004-04-03 03:45:26 +04:00
#if defined _dbi_included
#endinput
2004-04-03 03:45:26 +04:00
#endif
#define _dbi_included
2006-05-10 14:42:49 +04:00
// You can't include SQLX first!
// there's really no reason to anyway.
#assert !defined _sqlx_included
#pragma reqclass dbi
2005-07-15 23:05:31 +04:00
2004-07-19 18:28:42 +04:00
enum Sql
{
SQL_FAILED=0,
SQL_OK
};
2004-07-19 18:28:42 +04:00
enum Result
{
RESULT_FAILED=-1,
RESULT_NONE,
RESULT_OK
};
2004-07-19 18:28:42 +04:00
2004-05-28 13:21:11 +04:00
/* This will return a number equal to or below 0 on failure.
* If it does fail, the error will be mirrored in dbi_error()
* The return value will otherwise be a resource handle, not an
* OK code or cell pointer.
*/
2004-07-18 14:22:55 +04:00
native Sql:dbi_connect(_host[], _user[], _pass[], _dbname[], _error[]="", _maxlength=0);
2004-05-28 13:21:11 +04:00
/* This will do a simple query execution on the SQL server.
2004-05-30 13:58:51 +04:00
* If it fails, it will return a number BELOW ZERO (0)
* If zero, it succeeded with NO RETURN RESULT.
* If greater than zero, make sure to call dbi_free_result() on it!
2004-06-12 01:03:45 +04:00
* The return is a handle to the result set
2004-05-28 13:21:11 +04:00
*/
native Result:dbi_query(Sql:_sql, _query[], any:...);
2004-04-03 03:45:26 +04:00
2005-12-07 03:13:13 +03:00
/* Has the same usage as dbi_query, but this native returns by
* reference the number of rows affected in the query. If the
* query fails rows will be equal to -1.
*/
native Result:dbi_query2(Sql:_sql, &rows, _query[], any:...);
2005-12-07 03:13:13 +03:00
2004-05-28 13:21:11 +04:00
/* Returns 0 on failure or End of Results.
* Advances result pointer by one row.
*/
2004-07-23 22:11:25 +04:00
native dbi_nextrow(Result:_result);
2004-04-03 03:45:26 +04:00
2004-05-28 13:21:11 +04:00
/* Gets a field by number. Returns 0 on failure.
* Although internally fields always start from 0,
* This function takes fieldnum starting from 1.
2004-06-12 01:03:45 +04:00
* No extra params: returns int
* One extra param: returns Float: byref
* Two extra param: Stores string with length
2004-05-28 13:21:11 +04:00
*/
2015-03-11 16:19:27 +03:00
native dbi_field(Result:_result, _fieldnum, any:... );
2004-05-30 13:58:51 +04:00
2004-06-24 10:59:16 +04:00
/* Gets a field by name. Returns 0 on failure.
2004-06-12 01:03:45 +04:00
* One extra param: returns Float: byref
* Two extra param: Stores string with length
2004-05-30 13:58:51 +04:00
*/
2015-03-11 16:19:27 +03:00
native dbi_result(Result:_result, _field[], any:... );
2004-05-30 13:58:51 +04:00
/* Returns the number of rows returned from a query
*/
2004-07-18 14:22:55 +04:00
native dbi_num_rows(Result:_result);
2004-05-30 13:58:51 +04:00
/* Frees memory used by a result handle. Do this or get memory leaks.
*/
native dbi_free_result(&Result:result);
2004-04-03 03:45:26 +04:00
2004-05-28 13:21:11 +04:00
/* Closes a database handle. Internally, it will also
* mark the handle as free, so this particular handle may
* be re-used in the future to save time.
*/
2004-09-02 00:58:03 +04:00
native dbi_close(&Sql:_sql);
2004-04-03 03:45:26 +04:00
2004-05-28 13:21:11 +04:00
/* Returns an error message set. For PGSQL and MySQL,
* this is a direct error return from the database handle/API.
* For MSSQL, it returns the last error message found from a
* thrown exception.
*/
2004-07-18 14:22:55 +04:00
native dbi_error(Sql:_sql, _error[], _len);
2004-04-03 03:45:26 +04:00
2004-05-28 13:21:11 +04:00
/* Returns the type of database being used. So far:
* "mysql", "pgsql", "mssql", "sqlite"
2004-05-28 13:21:11 +04:00
*/
native dbi_type(_type[], _len);
2004-07-18 14:22:55 +04:00
2005-08-31 08:36:25 +04:00
/* Returns the number of fields/colums in a result set.
* Unlike dbi_nextrow, you must pass a valid result handle.
*/
native dbi_num_fields(Result:result);
/* Retrieves the name of a field/column in a result set.
* Requires a valid result handle, and columns are numbered 1 to n.
*/
native dbi_field_name(Result:result, field, name[], maxLength);
/* This function can be used to find out if a table in a Sqlite database exists.
*/
stock bool:sqlite_table_exists(Sql:sql, table[])
{
new bool:exists;
new query[128];
format(query, 127, "SELECT name FROM sqlite_master WHERE type='table' AND name='%s' LIMIT 1;", table);
new Result:result = dbi_query(sql, query);
if (dbi_nextrow(result))
{
exists = true;
}
else
{
exists = false;
}
if (result > RESULT_NONE)
{
dbi_free_result(result);
}
return exists;
2006-05-19 06:04:09 +04:00
}