File content in sqlx.inc // 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 // // SQLX - Newer SQL Database API // #if defined _sqlx_included #endinput #endif #define _sqlx_included //eh.. #define SQL_NumRows SQL_NumResults #pragma reqclass sqlx #if !defined AMXMODX_NOAUTOLOAD #pragma defclasslib sqlx mysql #endif enum Handle { Empty_Handle }; /** * Creates a connection information tuple. This tuple must be passed * into connection routines. * * @note Freeing the tuple is not necessary, but is a good idea if you create * many of them. You can cache these handles globally. * @note This does not connect to the DB; it only caches the connection information. * * @param host Database host * @param user Database user * @param pass Database password * @param db Database name to use * @param timeout Specifies how long connections should wait before giving up. * If <= 0, the default of 60s is used. * * @return A newly created tuple handle to be used in connection routines. */ native Handle:SQL_MakeDbTuple(const host[], const user[], const pass[], const db[], timeout=0); /** * Frees an SQL handle. * * @note The handle can be to anything (tuple, connection, query, results, etc). * @note If you free the database connection handle, it closes the connection as well. * * @param h Handle to be freed. * * @noreturn */ native SQL_FreeHandle(Handle:h); /** * Opens a database connection. * * @param cn_tuple Tuple handle, returned from SQL_MakeDbTuple(). * @param errcode An error code set by reference. * @param error String where error string will be stored. * @param maxlength Maximum length of the error buffer. * * @return Returns an SQL connection handle, which must be freed. * Returns Empty_Handle on failure. * @error Invalid info tuple handle. */ native Handle:SQL_Connect(Handle:cn_tuple, &errcode, error[], maxlength); /** * Sets the character set of the current connection. * Like SET NAMES .. in mysql, but stays after connection problems. * * @note If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery. * @note The change will remain until you call this function with another value. * @note This native does nothing in SQLite. * * Example: "utf8", "latin1" * * @param h Database or connection tuple Handle. * @param charset The character set string to change to. * * @return True, if character set was changed, false otherwise. */ native bool:SQL_SetCharset(Handle:h, const charset[]); /** * Prepares a query. * * @note This does not actually do a query! * * @param db Connection handle, returned from SQL_Connect(). * @param fmt Query string. Can be formated with format specifiers. * @param ... Additional format specifiers used to format the query. * * @return Returns an SQL query handle, which must always be freed. * Returns Empty_Handle on failure. */ native Handle:SQL_PrepareQuery(Handle:db, const fmt[], any:...); /** * Back-quotes characters in a string for database querying. * * @note The buffer's maximum size should be 2*strlen(string) to catch all scenarios. * * @param db Database handle for localization, or Empty_Handle * for when a handle is not available. * @param buffer Buffer to copy to. * @param buflen Maximum size of the buffer. * @param string String to backquote (should not overlap buffer). * * @return Length of new string, or -1 on failure. * @error Invalid database handle. */ native SQL_QuoteString(Handle:db, buffer[], buflen, const string[]); /** * Back-quotes characters in a string for database querying. * Note: The buffer's maximum size should be 2*strlen(string) to catch * all scenarios. * * @param db Database handle for localization, or Empty_Handle * for when a handle is not available. * @param buffer Buffer to copy to. * @param buflen Maximum size of the buffer. * @param fmt Format of string to backquote (should not overlap buffer). * @param ... Format arguments. * * @return Length of new string, or -1 on failure. */ native SQL_QuoteStringFmt(Handle:db, buffer[], buflen, const fmt[], any:...); /** * Threaded query states. Used to check the state of a complete threaded query. */ #define TQUERY_CONNECT_FAILED -2 #define TQUERY_QUERY_FAILED -1 #define TQUERY_SUCCESS 0 /** * Prepares and executes a threaded query. * @note The handler should look like: * public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime) * failstate - One of the three TQUERY_ defines. * query - Handle to the query, do not free it. * error - An error message, if any. * errnum - An error code, if any. * data - Data array you passed in. * size - Size of the data array you passed in. * queuetime - Amount of gametime that passed while the query was resolving. * @note This will not interrupt gameplay in the event of a poor/lossed * connection, however, the interface is more complicated and * asynchronous. Furthermore, a new connection/disconnection is * made for each query to simplify driver support. * @note The handle does not need to be freed. * * @param db_tuple Tuple handle, returned from SQL_MakeDbTuple(). * @param handler A function to be called when the query finishes. It has to be public. * @param query The query string. * @param data Additional data array that will be passed to the handler function. * @param dataSize The size of the additional data array. * * @noreturn * @error Thread worker was unable to start. * Invalid info tuple handle. * Handler function not found. */ native SQL_ThreadQuery(Handle:db_tuple, const handler[], const query[], const data[]="", dataSize=0); /** * Executes an already prepared query. * * @note You can call this multiple times as long as its parent connection is kept open. * Each time the result set from the previous call will be freed. * * @param query Handle of a prepared query to be executed. * * @return 1 if the query succeeded, 0 if the query failed. * @error Invalid query handle. */ native SQL_Execute(Handle:query); /** * Gets information about a failed query error. * * @param query Handle of a query to extract the error from. * @param error Buffer where to store the error string. * @param maxlength The maximum length of the output buffer. * * @return The error code. */ native SQL_QueryError(Handle:query, error[], maxlength); /** * Checks whether there are more results to be read. * * @param query Handle of a query to check. * * @return 1 if there are more results, 0 otherwise. * @error Invalid query handle. */ native SQL_MoreResults(Handle:query); /** * Tells whether a specific column in the current row is NULL or not. * * @param query Handle of a query to check. * @param column Which column to check for NULL. * * @return 1 if the column is NULL, 0 otherwise. * @error Invalid query handle. * No result set in this query. * Invalid column. */ native SQL_IsNull(Handle:query, column); /** * Retrieves the current result. * * @note A successful query starts at the first result, so you should not call * SQL_NextRow() first. * * @note Example how to get different types of values: * new num = SQL_ReadResult(query, 0) * new Float:num2 * new string[32] * SQL_ReadResult(query, 1, num2) * SQL_ReadResult(query, 2, string, charsmax(string)) * * @param query Handle of a query to read results from. * @param column Which column to get the value from. * @param ... Passing no extra arguments - returns an integer. * Passing one extra argument - returns a float in the first extra argument * Passing two extra params - returns a string in the first argument * with a maximum string length in the second argument. * * @return If no extra arguments are passed, returns an integer value. * @error Invalid query handle. */ native SQL_ReadResult(Handle:query, column, any:...); /** * Advances to the next result (row). * * @param query Handle of a query. * * @noreturn * @error Invalid query handle. * No result set in this query. */ native SQL_NextRow(Handle:query); /** * Returns the number of affected rows by a query. * * @param query Handle of a query to check. * * @return The number of affected rows. * @error Invalid query handle. */ native SQL_AffectedRows(Handle:query); /** * The number of retrieved rows (results) after a query. * * @param query Handle of a query to check. * * @return The number of retrieved rows by the query. * @error Invalid query handle. */ native SQL_NumResults(Handle:query); /** * Returns the total number of columns. * * @param query Handle of a query to check. * * @return The number of retrieved columns by the query. * @error Invalid query handle. * No result set in this query. */ native SQL_NumColumns(Handle:query); /** * Retrieves the name of a column by its index. * * @param query Handle of a query. * @param num The number (index) of a column to retrieve the name from. * @param name Buffer where to store the column's name. * @param maxlength Maximum length of the output buffer. * * @noreturn * @error Invalid query handle. * No result set in this query. * Invalid column index. */ native SQL_FieldNumToName(Handle:query, num, name[], maxlength); /** * Retrieves the number of a named column. * * @param query Handle of a query. * @param name Name to search for. * * @return Column index if found (>= 0); -1 otherwise. * @error Invalid query handle. * No result set in this query. */ native SQL_FieldNameToNum(Handle:query, const name[]); /** * Rewinds a result set to the first row. * * @param query Handle of a query to rewind the result set of. * * @noreturn * @error Invalid query handle. * No result set in this query. */ native SQL_Rewind(Handle:query); /** * Retrieves the instert ID of the latest INSERT query. * * @param query Handle of a query. * * @return The insert ID of the latest INSERT query. * @error Invalid query handle. */ native SQL_GetInsertId(Handle:query); /** * Retrieves which driver is this plugin currently bound to. * * @param driver Buffer to store the driver name in. * @param maxlen Maximum length of the output buffer. * * @noreturn */ native SQL_GetAffinity(driver[], maxlen); /** * Sets driver affinity. You can use this to force a particular driver implementation. * This will automatically change all SQL natives in your plugin to be "bound" to * the module in question. * * @note Using this while you have open handles to another database type will * cause problems. I.e., you cannot open a handle, switch affinity, * then close the handle with a different driver. * @note Switching affinity is an O(n * m) operation, where n is the number of * SQL natives and m is the number of used natives in total. * @note Intuitive programmers will note that this causes problems for * threaded queries. You will have to either force your script to work * under one affinity, or to pack the affinity type into the query data, * check it against the current, then set the new affinity if necessary. * Then, restore the old one for safety. * * @param driver The name of a driver to use. * * @return If no module with the given name is found, returns 0. * Unless your plugin is bult to handle different driver * types at once, you should let this error pass. */ native SQL_SetAffinity(const driver[]); /** * Returns the original query string that a query handle used. * * @param query Handle of a query. * @param buffer Buffer where to put the query string in. * @param maxlength The maximum length of the output buffer. * * @noreturn * @error Invalid query handle. */ native SQL_GetQueryString(Handle:query, buffer[], maxlength); /** * For queries which return multiple result sets, this advances to the next * result set if one is available. Otherwise, the current result set is * destroyed and will no longer be accessible. * * @note This function will always return false on SQLite, and when using threaded * queries in MySQL. Nonetheless, it has the same effect of removing the last * result set. * * @param query Query Handle. * * @return True on success, false on failure. * @error Invalid query handle. * No result set in this query. */ native bool:SQL_NextResultSet(Handle:query); /** * This function can be used to find out if a table in a SQLite database exists. * * @param db Connection handle returned from SQL_Connect(). * @param table The table name to check for. * * @return True if it exists, false otherwise. */ stock bool:sqlite_TableExists(Handle:db, const table[]) { new Handle:query = SQL_PrepareQuery( db, "SELECT name FROM sqlite_master WHERE type='table' AND name='%s' LIMIT 1;", table); if (!SQL_Execute(query) || !SQL_NumResults(query)) { SQL_FreeHandle(query); return false; } SQL_FreeHandle(query); return true; } /** * Use this for executing a query where you don't care about the result. * * @param db Connection handle returned from SQL_Connect(). * @param query The query string. * @param error If an error occurs, it will be placed into this buffer. * @param maxlength Maximum length of the error buffer. * @param rows Optional. If put, retrieves the number of rows the query returned. * * @return 1 on success, 0 on failure. */ stock SQL_SimpleQuery(Handle:db, const query[], error[]="", maxlength=0, &rows=0) { new Handle:hQuery = SQL_PrepareQuery(db, "%s", query); if (!SQL_Execute(hQuery)) { SQL_QueryError(hQuery, error, maxlength); SQL_FreeHandle(hQuery); return 0; } rows = SQL_NumResults(hQuery); SQL_FreeHandle(hQuery); return 1; } /** * Use this for executing a query where you don't care about the result. * * @note Differs from SQL_SimpleQuery() because the query can be formated. * * @param db Connection handle returned from SQL_Connect(). * @param error If an error occurs, it will be placed into this buffer. * @param maxlength The maximum length of the error buffer. * @param rows Optional. If put, retrieves the number of rows the query returned. * @param fmt The query string that can be formated with format specifiers. * @param ... Additional arguments for formating the query. * * @return 1 on success, 0 on failure. */ stock SQL_SimpleQueryFmt(Handle:db, error[]="", maxlength=0, &rows=0, const fmt[], any:...) { static query_buf[2048]; vformat(query_buf, 2047, fmt, 6); new Handle:hQuery = SQL_PrepareQuery(db, "%s", query_buf); if (!SQL_Execute(hQuery)) { SQL_QueryError(hQuery, error, maxlength); SQL_FreeHandle(hQuery); return 0; } rows = SQL_NumResults(hQuery); SQL_FreeHandle(hQuery); return 1; } /** * Use this for executing a query and not caring about the error. * * @param db A connection handle returned from SQL_Connect(). * @param queryfmt The query string that can be formated with format specifiers. * @pram ... Additional arguments for formating the query. * * @return -1 on error. * >= 0 on success (with the number of affected rows). */ stock SQL_QueryAndIgnore(Handle:db, const queryfmt[], any:...) { static query[4096]; new Handle:hQuery; new ret; vformat(query, sizeof(query)-1, queryfmt, 3); hQuery = SQL_PrepareQuery(db, "%s", query); if (SQL_Execute(hQuery)) { ret = SQL_AffectedRows(hQuery); } else { ret = -1; } SQL_FreeHandle(hQuery); return ret; } /** * Use this for making a standard DB Tuple, using AMXX's database info cvars. * * @param timeout Specifies how long connections should wait before giving up. * If 0, the value is read from "amx_sql_timeout" cvar. * * @return A newly created tuple handle to be used in connection routines. */ stock Handle:SQL_MakeStdTuple(timeout = 0) { static host[64], user[32], pass[32], db[128]; static get_type[12], set_type[12]; get_cvar_string("amx_sql_host", host, 63); get_cvar_string("amx_sql_user", user, 31); get_cvar_string("amx_sql_pass", pass, 31); get_cvar_string("amx_sql_type", set_type, 11); get_cvar_string("amx_sql_db", db, 127); if (timeout <= 0) { timeout = get_cvar_num("amx_sql_timeout"); } SQL_GetAffinity(get_type, 12); if (!equali(get_type, set_type)) { if (!SQL_SetAffinity(set_type)) { log_amx("Failed to set affinity from %s to %s.", get_type, set_type); } } return SQL_MakeDbTuple(host, user, pass, db, timeout); }