3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _dbi_included
24 * Contains information about an SQL driver.
30 * Contains information about a database connection.
36 * Contains information about an active query and its
41 * @handle Statement : Query
43 * Extends a Query Handle and can be used as a Query Handle.
44 * Statement Handles are for prepared queries and contain
45 * their own function for binding parameters. Statement
46 * Handles can be used instead of database Handles in a few
51 * Describes a database field fetch status.
55 DBVal_Error = 0, /**< Column number/field is invalid. */
56 DBVal_TypeMismatch = 1, /**< You cannot retrieve this data with this type. */
57 DBVal_Null = 2, /**< Field has no data (NULL) */
58 DBVal_Data = 3, /**< Field has data */
62 * Creates an SQL connection from a named configuration.
64 * @param confname Named configuration.
65 * @param persistent True to re-use a previous persistent connection if
66 * possible, false otherwise.
67 * @param error Error buffer.
68 * @param maxlength Maximum length of the error buffer.
69 * @return A database connection Handle, or INVALID_HANDLE on failure.
71 native Handle:SQL_Connect(const String:confname[], bool:persistent, String:error[], maxlength);
74 * Creates a default SQL connection.
76 * @param error Error buffer.
77 * @param maxlength Maximum length of the error buffer.
78 * @param persistent True to re-use a previous persistent connection
79 * if possible, false otherwise.
80 * @return A database connection Handle, or INVALID_HANDLE on failure.
82 stock Handle:SQL_DefConnect(String:error[], maxlength, bool:persistent=true)
84 return SQL_Connect("default", persistent, error, maxlength);
88 * Creates an SQL connection from specific parameters.
90 * @param driver Driver Handle, or INVALID_HANDLE for default.
91 * @param host Host name.
92 * @param user User name.
93 * @param pass User password.
94 * @param database Database name.
95 * @param error Error buffer.
96 * @param maxlength Maximum length of the error buffer.
97 * @param persistent True to re-use a previous persistent connection
98 * if possible, false otherwise.
99 * @param port Optional port to specify.
100 * @param maxTimeout Maximum timeout in seconds if applicable.
101 * @return A database connection Handle, or INVALID_HANDLE on failure.
102 * @error Invalid driver Handle other than INVALID_HANDLE.
104 native Handle:SQL_ConnectEx(Handle:driver,
108 const String:database[],
111 bool:persistent=true,
116 * Returns a driver Handle from a name string.
118 * If the driver is not found, SourceMod will attempt
119 * to load an extension named dbi.<name>.ext.[dll|so].
121 * @param name Driver identification string, or an empty
122 * string to return the default driver.
123 * @return Driver Handle, or INVALID_HANDLE on failure.
125 native Handle:SQL_GetDriver(const String:name[]="");
128 * Retrieves a driver's identification string.
130 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
131 * @param ident Identification string buffer.
132 * @param maxlength Maximum length of the buffer.
134 * @error Invalid Handle other than INVALID_HANDLE.
136 native SQL_GetDriverIdent(Handle:driver, String:ident[], maxlength);
139 * Retrieves a driver's product string.
141 * @param driver Driver Handle, or INVALID_HANDLE for the default driver.
142 * @param product Product string buffer.
143 * @param maxlength Maximum length of the buffer.
145 * @error Invalid Handle other than INVALID_HANDLE.
147 native SQL_GetDriverProduct(Handle:driver, String:product[], maxlength);
150 * Returns the number of affected rows from the last query.
152 * @param hndl A database OR statement Handle.
153 * @return Number of rows affected by the last query.
154 * @error Invalid database or statement Handle.
156 native SQL_GetAffectedRows(Handle:hndl);
159 * Returns the last query's insertion id.
161 * @param hndl A database OR statement Handle.
162 * @return Last query's insertion id.
163 * @error Invalid database or statement Handle.
165 native SQL_GetInsertId(Handle:hndl);
168 * Returns the error reported by the last query.
170 * @param hndl A database OR statement Handle.
171 * @param error Error buffer.
172 * @param maxlength Maximum length of the buffer.
173 * @return True if there was an error, false otherwise.
174 * @error Invalid database or statement Handle.
176 native bool:SQL_GetError(Handle:hndl, String:error[], maxlength);
179 * Quotes a database string for literal insertion. This is not needed
180 * for binding strings in prepared statements.
182 * @param hndl A database Handle.
183 * @param string String to quote.
184 * @param buffer Buffer to store quoted string in.
185 * @param maxlength Maximum length of the buffer.
186 * @param written Optionally returns the number of bytes written.
187 * @return True on success, false if buffer is not big enough.
188 * The buffer must be at least 2*strlen(string)+1.
189 * @error Invalid database or statement Handle.
191 native bool:SQL_QuoteString(Handle:database, const String:string[], String:buffer[], maxlength, &written=0);
194 * Executes a query and ignores the result set.
196 * @param database A database Handle.
197 * @param query Query string.
198 * @return True if query succeeded, false otherwise. Use
199 * SQL_GetError to find the last error.
200 * @error Invalid database Handle.
202 native bool:SQL_FastQuery(Handle:database, const String:query[]);
205 * Executes a simple query and returns a new query Handle for
206 * receiving the results.
208 * @param database A database Handle.
209 * @param query Query string.
210 * @return A new Query Handle on success, INVALID_HANDLE
211 * otherwise. The Handle must be freed with CloseHandle().
212 * @error Invalid database Handle.
214 native Handle:SQL_Query(Handle:database, const String:query[]);
217 * Creates a new prepared statement query. Prepared statements can
218 * be executed any number of times. They can also have placeholder
219 * parameters, similar to variables, which can be bound safely and
220 * securely (for example, you do not need to quote bound strings).
222 * Statement handles will work in any function that accepts a Query handle.
224 * @param database A database Handle.
225 * @param query Query string.
226 * @param error Error buffer.
227 * @param maxlength Maximum size of the error buffer.
228 * @return A new statement Handle on success, INVALID_HANDLE
229 * otherwise. The Handle must be freed with CloseHandle().
230 * @error Invalid database Handle.
232 native Handle:SQL_PrepareQuery(Handle:database, const String:query[], String:error[], maxlength);
235 * Advances to the next set of results.
237 * In some SQL implementations, multiple result sets can exist on one query.
238 * This is possible in MySQL with simple queries when executing a CALL
239 * query. If this is the case, all result sets must be processed before
240 * another query is made.
242 * @param query A query Handle.
243 * @return True if there was another result set, false otherwise.
244 * @error Invalid query Handle.
246 native bool:SQL_FetchMoreResults(Handle:query);
249 * Returns whether or not a result set exists. This will
250 * return true even if 0 results were returned, but false
251 * on queries like UPDATE, INSERT, or DELETE.
253 * @param query A query (or statement) Handle.
254 * @return True if there is a result set, false otherwise.
255 * @error Invalid query Handle.
257 native bool:SQL_HasResultSet(Handle:query);
260 * Retrieves the number of rows in the last result set.
262 * @param query A query (or statement) Handle.
263 * @return Number of rows in the current result set.
264 * @error Invalid query Handle.
266 native SQL_GetRowCount(Handle:query);
269 * Retrieves the number of fields in the last result set.
271 * @param query A query (or statement) Handle.
272 * @return Number of fields in the current result set.
273 * @error Invalid query Handle.
275 native SQL_GetFieldCount(Handle:query);
278 * Retrieves the name of a field by index.
280 * @param query A query (or statement) Handle.
281 * @param field Field number (starting from 0).
282 * @param name Name buffer.
283 * @param maxlength Maximum length of the name buffer.
285 * @error Invalid query Handle, invalid field index, or
286 * no current result set.
288 native SQL_FieldNumToName(Handle:query, field, String:name[], maxlength);
291 * Retrieves a field index by name.
293 * @param query A query (or statement) Handle.
294 * @param name Name of the field (case sensitive).
295 * @param field Variable to store field index in.
296 * @return True if found, false if not found.
297 * @error Invalid query Handle or no current result set.
299 native bool:SQL_FieldNameToNum(Handle:query, const String:name[], &field);
302 * Fetches a row from the current result set. This must be
303 * successfully called before any results are fetched.
305 * If this function fails, SQL_MoreResults() can be used to
306 * tell if there was an error or the result set is finished.
308 * @param query A query (or statement) Handle.
309 * @return True if a row was fetched, false otherwise.
310 * @error Invalid query Handle.
312 native bool:SQL_FetchRow(Handle:query);
315 * Returns if there are more rows.
317 * @param query A query (or statement) Handle.
318 * @return True if there are more rows, false otherwise.
319 * @error Invalid query Handle.
321 native bool:SQL_MoreRows(Handle:query);
324 * Rewinds a result set back to the first result.
326 * @param query A query (or statement) Handle.
327 * @return True on success, false otherwise.
328 * @error Invalid query Handle or no current result set.
330 native bool:SQL_Rewind(Handle:query);
333 * Fetches a string from a field in the current row of a result set.
334 * If the result is NULL, an empty string will be returned. A NULL
335 * check can be done with the result parameter, or SQL_IsFieldNull().
337 * @param query A query (or statement) Handle.
338 * @param field The field index (starting from 0).
339 * @param buffer String buffer.
340 * @param maxlength Maximum size of the string buffer.
341 * @param result Optional variable to store the status of the return value.
342 * @return Number of bytes written.
343 * @error Invalid query Handle or field index, invalid
344 * type conversion requested from the database,
345 * or no current result set.
347 native SQL_FetchString(Handle:query, field, String:buffer[], maxlength, &DBResult:result=DBVal_Error);
350 * Fetches a float from a field in the current row of a result set.
351 * If the result is NULL, a value of 0.0 will be returned. A NULL
352 * check can be done with the result parameter, or SQL_IsFieldNull().
354 * @param query A query (or statement) Handle.
355 * @param field The field index (starting from 0).
356 * @param result Optional variable to store the status of the return value.
357 * @return A float value.
358 * @error Invalid query Handle or field index, invalid
359 * type conversion requested from the database,
360 * or no current result set.
362 native Float:SQL_FetchFloat(Handle:query, field, &DBResult:result=DBVal_Error);
365 * Fetches an integer from a field in the current row of a result set.
366 * If the result is NULL, a value of 0 will be returned. A NULL
367 * check can be done with the result parameter, or SQL_IsFieldNull().
369 * @param query A query (or statement) Handle.
370 * @param field The field index (starting from 0).
371 * @param result Optional variable to store the status of the return value.
372 * @return An integer value.
373 * @error Invalid query Handle or field index, invalid
374 * type conversion requested from the database,
375 * or no current result set.
377 native SQL_FetchInt(Handle:query, field, &DBResult:result=DBVal_Error);
380 * Returns whether a field's data in the current row of a result set is
381 * NULL or not. NULL is an SQL type which means "no data."
383 * @param query A query (or statement) Handle.
384 * @param field The field index (starting from 0).
385 * @return True if data is NULL, false otherwise.
386 * @error Invalid query Handle or field index, or no
387 * current result set.
389 native bool:SQL_IsFieldNull(Handle:query, field);
392 * Returns the length of a field's data in the current row of a result
393 * set. This only needs to be called for strings to determine how many
394 * bytes to use. Note that the return value does not include the null
397 * @param query A query (or statement) Handle.
398 * @param field The field index (starting from 0).
399 * @return Number of bytes for the field's data size.
400 * @error Invalid query Handle or field index or no
401 * current result set.
403 native SQL_FetchSize(Handle:query, field);
406 * Binds a parameter in a prepared statement to a given integer value.
408 * @param statement A statement (prepared query) Handle.
409 * @param param The parameter index (starting from 0).
410 * @param number The number to bind.
411 * @param signed True to bind the number as signed, false to
412 * bind it as unsigned.
414 * @error Invalid statement Handle or parameter index, or
417 native SQL_BindParamInt(Handle:statement, param, number, bool:signed=true);
420 * Binds a parameter in a prepared statement to a given float value.
422 * @param statement A statement (prepared query) Handle.
423 * @param param The parameter index (starting from 0).
424 * @param float The float number to bind.
426 * @error Invalid statement Handle or parameter index, or
429 native SQL_BindParamFloat(Handle:statement, param, Float:value);
432 * Binds a parameter in a prepared statement to a given string value.
434 * @param statement A statement (prepared query) Handle.
435 * @param param The parameter index (starting from 0).
436 * @param value The string to bind.
437 * @param copy Whether or not SourceMod should copy the value
438 * locally if necessary. If the string contents
439 * won't change before calling SQL_Execute(), this
440 * can be set to false for optimization.
442 * @error Invalid statement Handle or parameter index, or
445 native SQL_BindParamString(Handle:statement, param, const String:value[], bool:copy);
448 * Executes a prepared statement. All parameters must be bound beforehand.
450 * @param statement A statement (prepared query) Handle.
451 * @return True on success, false on failure.
452 * @error Invalid statement Handle.
454 native bool:SQL_Execute(Handle:statement);
