1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/dbi.inc Fri Jun 01 02:30:29 2007 +0000
1.3 @@ -0,0 +1,445 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * ===============================================================
1.7 + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
1.8 + * ===============================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
1.11 + * or modified under the Terms and Conditions of its License Agreement, which is found
1.12 + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
1.13 + * may change at any time. To view the latest information, see:
1.14 + * http://www.sourcemod.net/license.php
1.15 + *
1.16 + * Version: $Id$
1.17 + */
1.18 +
1.19 +#if defined _dbi_included
1.20 + #endinput
1.21 +#endif
1.22 +#define _dbi_included
1.23 +
1.24 +/**
1.25 + * @handle Driver
1.26 + *
1.27 + * Contains information about an SQL driver.
1.28 + */
1.29 +
1.30 +/**
1.31 + * @handle Database
1.32 + *
1.33 + * Contains information about a database connection.
1.34 + */
1.35 +
1.36 +/**
1.37 + * @handle Query
1.38 + *
1.39 + * Contains information about an active query and its
1.40 + * result sets.
1.41 + */
1.42 +
1.43 +/**
1.44 + * @handle Statement : Query
1.45 + *
1.46 + * Extends a Query Handle and can be used as a Query Handle.
1.47 + * Statement Handles are for prepared queries and contain
1.48 + * their own function for binding parameters. Statement
1.49 + * Handles can be used instead of database Handles in a few
1.50 + * select functions.
1.51 + */
1.52 +
1.53 +/**
1.54 + * Describes a database field fetch status.
1.55 + */
1.56 +enum DBResult
1.57 +{
1.58 + DBVal_Error = 0, /**< Column number/field is invalid. */
1.59 + DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type. */
1.60 + DBVal_Null = 2, /**< Field has no data (NULL) */
1.61 + DBVal_Data = 3, /**< Field has data */
1.62 +}
1.63 +
1.64 +/**
1.65 + * Creates an SQL connection from a named configuration.
1.66 + *
1.67 + * @param confname Named configuration.
1.68 + * @param persistent True to re-use a previous persistent connection if
1.69 + * possible, false otherwise.
1.70 + * @param error Error buffer.
1.71 + * @param maxlength Maximum length of the error buffer.
1.72 + * @return A database connection Handle, or INVALID_HANDLE on failure.
1.73 + */
1.74 +native Handle:SQL_Connect(const String:confname[], bool:persistent, String:error[], maxlength);
1.75 +
1.76 +/**
1.77 + * Creates a default SQL connection.
1.78 + *
1.79 + * @param error Error buffer.
1.80 + * @param maxlength Maximum length of the error buffer.
1.81 + * @param persistent True to re-use a previous persistent connection
1.82 + * if possible, false otherwise.
1.83 + * @return A database connection Handle, or INVALID_HANDLE on failure.
1.84 + */
1.85 +stock Handle:SQL_DefConnect(String:error[], maxlength, bool:persistent=true)
1.86 +{
1.87 + return SQL_Connect("default", persistent, error, maxlength);
1.88 +}
1.89 +
1.90 +/**
1.91 + * Creates an SQL connection from specific parameters.
1.92 + *
1.93 + * @param driver Driver Handle, or INVALID_HANDLE for default.
1.94 + * @param host Host name.
1.95 + * @param user User name.
1.96 + * @param pass User password.
1.97 + * @param database Database name.
1.98 + * @param error Error buffer.
1.99 + * @param maxlength Maximum length of the error buffer.
1.100 + * @param persistent True to re-use a previous persistent connection
1.101 + * if possible, false otherwise.
1.102 + * @param port Optional port to specify.
1.103 + * @param maxTimeout Maximum timeout in seconds if applicable.
1.104 + * @return A database connection Handle, or INVALID_HANDLE on failure.
1.105 + * @error Invalid driver Handle other than INVALID_HANDLE.
1.106 + */
1.107 +native Handle:SQL_ConnectEx(Handle:driver,
1.108 + const String:host[],
1.109 + const String:user[],
1.110 + const String:pass[],
1.111 + const String:database[],
1.112 + String:error[],
1.113 + maxlength,
1.114 + bool:persistent=true,
1.115 + port=0,
1.116 + maxTimeout=0);
1.117 +
1.118 +/**
1.119 + * Returns a driver Handle from a name string.
1.120 + *
1.121 + * If the driver is not found, SourceMod will attempt
1.122 + * to load an extension named dbi.<name>.ext.[dll|so].
1.123 + *
1.124 + * @param name Driver identification string, or an empty
1.125 + * string to return the default driver.
1.126 + * @return Driver Handle, or INVALID_HANDLE on failure.
1.127 + */
1.128 +native Handle:SQL_GetDriver(const String:name[]="");
1.129 +
1.130 +/**
1.131 + * Retrieves a driver's identification string.
1.132 + *
1.133 + * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
1.134 + * @param ident Identification string buffer.
1.135 + * @param maxlength Maximum length of the buffer.
1.136 + * @noreturn
1.137 + * @error Invalid Handle other than INVALID_HANDLE.
1.138 + */
1.139 +native SQL_GetDriverIdent(Handle:driver, String:ident[], maxlength);
1.140 +
1.141 +/**
1.142 + * Retrieves a driver's product string.
1.143 + *
1.144 + * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
1.145 + * @param product Product string buffer.
1.146 + * @param maxlength Maximum length of the buffer.
1.147 + * @noreturn
1.148 + * @error Invalid Handle other than INVALID_HANDLE.
1.149 + */
1.150 +native SQL_GetDriverProduct(Handle:driver, String:product[], maxlength);
1.151 +
1.152 +/**
1.153 + * Returns the number of affected rows from the last query.
1.154 + *
1.155 + * @param hndl A database OR statement Handle.
1.156 + * @return Number of rows affected by the last query.
1.157 + * @error Invalid database or statement Handle.
1.158 + */
1.159 +native SQL_GetAffectedRows(Handle:hndl);
1.160 +
1.161 +/**
1.162 + * Returns the last query's insertion id.
1.163 + *
1.164 + * @param hndl A database OR statement Handle.
1.165 + * @return Last query's insertion id.
1.166 + * @error Invalid database or statement Handle.
1.167 + */
1.168 +native SQL_GetInsertId(Handle:hndl);
1.169 +
1.170 +/**
1.171 + * Returns the error reported by the last query.
1.172 + *
1.173 + * @param hndl A database OR statement Handle.
1.174 + * @param error Error buffer.
1.175 + * @param maxlength Maximum length of the buffer.
1.176 + * @return True if there was an error, false otherwise.
1.177 + * @error Invalid database or statement Handle.
1.178 + */
1.179 +native bool:SQL_GetError(Handle:hndl, String:error[], maxlength);
1.180 +
1.181 +/**
1.182 + * Quotes a database string for literal insertion. This is not needed
1.183 + * for binding strings in prepared statements.
1.184 + *
1.185 + * @param hndl A database Handle.
1.186 + * @param string String to quote.
1.187 + * @param buffer Buffer to store quoted string in.
1.188 + * @param maxlength Maximum length of the buffer.
1.189 + * @param written Optionally returns the number of bytes written.
1.190 + * @return True on success, false if buffer is not big enough.
1.191 + * The buffer must be at least 2*strlen(string)+1.
1.192 + * @error Invalid database or statement Handle.
1.193 + */
1.194 +native bool:SQL_QuoteString(Handle:database, const String:string[], String:buffer[], maxlength, &written=0);
1.195 +
1.196 +/**
1.197 + * Executes a query and ignores the result set.
1.198 + *
1.199 + * @param database A database Handle.
1.200 + * @param query Query string.
1.201 + * @return True if query succeeded, false otherwise. Use
1.202 + * SQL_GetError to find the last error.
1.203 + * @error Invalid database Handle.
1.204 + */
1.205 +native bool:SQL_FastQuery(Handle:database, const String:query[]);
1.206 +
1.207 +/**
1.208 + * Executes a simple query and returns a new query Handle for
1.209 + * receiving the results.
1.210 + *
1.211 + * @param database A database Handle.
1.212 + * @param query Query string.
1.213 + * @return A new Query Handle on success, INVALID_HANDLE
1.214 + * otherwise. The Handle must be freed with CloseHandle().
1.215 + * @error Invalid database Handle.
1.216 + */
1.217 +native Handle:SQL_Query(Handle:database, const String:query[]);
1.218 +
1.219 +/**
1.220 + * Creates a new prepared statement query. Prepared statements can
1.221 + * be executed any number of times. They can also have placeholder
1.222 + * parameters, similar to variables, which can be bound safely and
1.223 + * securely (for example, you do not need to quote bound strings).
1.224 + *
1.225 + * Statement handles will work in any function that accepts a Query handle.
1.226 + *
1.227 + * @param database A database Handle.
1.228 + * @param query Query string.
1.229 + * @param error Error buffer.
1.230 + * @param maxlength Maximum size of the error buffer.
1.231 + * @return A new statement Handle on success, INVALID_HANDLE
1.232 + * otherwise. The Handle must be freed with CloseHandle().
1.233 + * @error Invalid database Handle.
1.234 + */
1.235 +native Handle:SQL_PrepareQuery(Handle:database, const String:query[], String:error[], maxlength);
1.236 +
1.237 +/**
1.238 + * Advances to the next set of results.
1.239 + *
1.240 + * In some SQL implementations, multiple result sets can exist on one query.
1.241 + * This is possible in MySQL with simple queries when executing a CALL
1.242 + * query. If this is the case, all result sets must be processed before
1.243 + * another query is made.
1.244 + *
1.245 + * @param query A query Handle.
1.246 + * @return True if there was another result set, false otherwise.
1.247 + * @error Invalid query Handle.
1.248 + */
1.249 +native bool:SQL_FetchMoreResults(Handle:query);
1.250 +
1.251 +/**
1.252 + * Returns whether or not a result set exists. This will
1.253 + * return true even if 0 results were returned, but false
1.254 + * on queries like UPDATE, INSERT, or DELETE.
1.255 + *
1.256 + * @param query A query (or statement) Handle.
1.257 + * @return True if there is a result set, false otherwise.
1.258 + * @error Invalid query Handle.
1.259 + */
1.260 +native bool:SQL_HasResultSet(Handle:query);
1.261 +
1.262 +/**
1.263 + * Retrieves the number of rows in the last result set.
1.264 + *
1.265 + * @param query A query (or statement) Handle.
1.266 + * @error Invalid query Handle.
1.267 + */
1.268 +native SQL_GetRowCount(Handle:query);
1.269 +
1.270 +/**
1.271 + * Retrieves the name of a field by index.
1.272 + *
1.273 + * @param query A query (or statement) Handle.
1.274 + * @param field Field number (starting from 0).
1.275 + * @param name Name buffer.
1.276 + * @param maxlength Maximum length of the name buffer.
1.277 + * @noreturn
1.278 + * @error Invalid query Handle, invalid field index, or
1.279 + * no current result set.
1.280 + */
1.281 +native SQL_FieldNumToName(Handle:query, field, String:name[], maxlength);
1.282 +
1.283 +/**
1.284 + * Retrieves a field index by name.
1.285 + *
1.286 + * @param query A query (or statement) Handle.
1.287 + * @param name Name of the field (case sensitive).
1.288 + * @param field Variable to store field index in.
1.289 + * @return True if found, false if not found.
1.290 + * @error Invalid query Handle or no current result set.
1.291 + */
1.292 +native bool:SQL_FieldNameToNum(Handle:query, const String:name[], &field);
1.293 +
1.294 +/**
1.295 + * Fetches a row from the current result set. This must be
1.296 + * successfully called before any results are fetched.
1.297 + *
1.298 + * If this function fails, SQL_MoreResults() can be used to
1.299 + * tell if there was an error or the result set is finished.
1.300 + *
1.301 + * @param query A query (or statement) Handle.
1.302 + * @return True if a row was fetched, false otherwise.
1.303 + * @error Invalid query Handle.
1.304 + */
1.305 +native bool:SQL_FetchRow(Handle:query);
1.306 +
1.307 +/**
1.308 + * Returns if there are more rows.
1.309 + *
1.310 + * @param query A query (or statement) Handle.
1.311 + * @return True if there are more rows, false otherwise.
1.312 + * @error Invalid query Handle.
1.313 + */
1.314 +native bool:SQL_MoreRows(Handle:query);
1.315 +
1.316 +/**
1.317 + * Rewinds a result set back to the first result.
1.318 + *
1.319 + * @param query A query (or statement) Handle.
1.320 + * @return True on success, false otherwise.
1.321 + * @error Invalid query Handle or no current result set.
1.322 + */
1.323 +native bool:SQL_Rewind(Handle:query);
1.324 +
1.325 +/**
1.326 + * Fetches a string from a field in the current row of a result set.
1.327 + * If the result is NULL, an empty string will be returned. A NULL
1.328 + * check can be done with the result parameter, or SQL_IsFieldNull().
1.329 + *
1.330 + * @param query A query (or statement) Handle.
1.331 + * @param field The field index (starting from 0).
1.332 + * @param buffer String buffer.
1.333 + * @param maxlength Maximum size of the string buffer.
1.334 + * @param result Optional variable to store the status of the return value.
1.335 + * @return Number of bytes written.
1.336 + * @error Invalid query Handle or field index, invalid
1.337 + * type conversion requested from the database,
1.338 + * or no current result set.
1.339 + */
1.340 +native SQL_FetchString(Handle:query, field, String:buffer[], maxlength, &DBResult:result=DBVal_Error);
1.341 +
1.342 +/**
1.343 + * Fetches a float from a field in the current row of a result set.
1.344 + * If the result is NULL, a value of 0.0 will be returned. A NULL
1.345 + * check can be done with the result parameter, or SQL_IsFieldNull().
1.346 + *
1.347 + * @param query A query (or statement) Handle.
1.348 + * @param field The field index (starting from 0).
1.349 + * @param result Optional variable to store the status of the return value.
1.350 + * @return A float value.
1.351 + * @error Invalid query Handle or field index, invalid
1.352 + * type conversion requested from the database,
1.353 + * or no current result set.
1.354 + */
1.355 +native Float:SQL_FetchFloat(Handle:query, field, &DBResult:result=DBVal_Error);
1.356 +
1.357 +/**
1.358 + * Fetches an integer from a field in the current row of a result set.
1.359 + * If the result is NULL, a value of 0 will be returned. A NULL
1.360 + * check can be done with the result parameter, or SQL_IsFieldNull().
1.361 + *
1.362 + * @param query A query (or statement) Handle.
1.363 + * @param field The field index (starting from 0).
1.364 + * @param result Optional variable to store the status of the return value.
1.365 + * @return An integer value.
1.366 + * @error Invalid query Handle or field index, invalid
1.367 + * type conversion requested from the database,
1.368 + * or no current result set.
1.369 + */
1.370 +native SQL_FetchInt(Handle:query, field, &DBResult:result=DBVal_Error);
1.371 +
1.372 +/**
1.373 + * Returns whether a field's data in the current row of a result set is
1.374 + * NULL or not. NULL is an SQL type which means "no data."
1.375 + *
1.376 + * @param query A query (or statement) Handle.
1.377 + * @param field The field index (starting from 0).
1.378 + * @return True if data is NULL, false otherwise.
1.379 + * @error Invalid query Handle or field index, or no
1.380 + * current result set.
1.381 + */
1.382 +native bool:SQL_IsFieldNull(Handle:query, field);
1.383 +
1.384 +/**
1.385 + * Returns the length of a field's data in the current row of a result
1.386 + * set. This only needs to be called for strings to determine how many
1.387 + * bytes to use. Note that the return value does not include the null
1.388 + * terminator.
1.389 + *
1.390 + * @param query A query (or statement) Handle.
1.391 + * @param field The field index (starting from 0).
1.392 + * @return Number of bytes for the field's data size.
1.393 + * @error Invalid query Handle or field index or no
1.394 + * current result set.
1.395 + */
1.396 +native SQL_FetchSize(Handle:query, field);
1.397 +
1.398 +/**
1.399 + * Binds a parameter in a prepared statement to a given integer value.
1.400 + *
1.401 + * @param statement A statement (prepared query) Handle.
1.402 + * @param param The parameter index (starting from 0).
1.403 + * @param number The number to bind.
1.404 + * @param signed True to bind the number as signed, false to
1.405 + * bind it as unsigned.
1.406 + * @noreturn
1.407 + * @error Invalid statement Handle or parameter index, or
1.408 + * SQL error.
1.409 + */
1.410 +native SQL_BindParamInt(Handle:statement, param, number, bool:signed=true);
1.411 +
1.412 +/**
1.413 + * Binds a parameter in a prepared statement to a given float value.
1.414 + *
1.415 + * @param statement A statement (prepared query) Handle.
1.416 + * @param param The parameter index (starting from 0).
1.417 + * @param float The float number to bind.
1.418 + * @noreturn
1.419 + * @error Invalid statement Handle or parameter index, or
1.420 + * SQL error.
1.421 + */
1.422 +native SQL_BindParamFloat(Handle:statement, param, Float:value);
1.423 +
1.424 +/**
1.425 + * Binds a parameter in a prepared statement to a given string value.
1.426 + *
1.427 + * @param statement A statement (prepared query) Handle.
1.428 + * @param param The parameter index (starting from 0).
1.429 + * @param value The string to bind.
1.430 + * @param copy Whether or not SourceMod should copy the value
1.431 + * locally if necessary. If the string contents
1.432 + * won't change before calling SQL_Execute(), this
1.433 + * can be set to false for optimization.
1.434 + * @noreturn
1.435 + * @error Invalid statement Handle or parameter index, or
1.436 + * SQL error.
1.437 + */
1.438 +native SQL_BindParamString(Handle:statement, param, const String:value[], bool:copy);
1.439 +
1.440 +/**
1.441 + * Executes a prepared statement. All parameters must be bound beforehand.
1.442 + *
1.443 + * @param statement A statement (prepared query) Handle.
1.444 + * @return True on success, false on failure.
1.445 + * @error Invalid statement Handle.
1.446 + */
1.447 +native bool:SQL_Execute(Handle:statement);
1.448 +
