SourceMod SDK  1.7
IDBDriver.h
Go to the documentation of this file.
1 
32 #ifndef _INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_
33 #define _INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_
34 
35 #include <IShareSys.h>
36 #include <IHandleSys.h>
37 #include <string.h>
38 
44 #define SMINTERFACE_DBI_NAME "IDBI"
45 #define SMINTERFACE_DBI_VERSION 9
46 
47 namespace SourceMod
48 {
52  enum DBResult
53  {
54  DBVal_Error = 0,
55  DBVal_TypeMismatch = 1,
56  DBVal_Null = 2,
57  DBVal_Data = 3,
58  };
59 
63  enum DBType
64  {
65  DBType_Unknown = 0,
66  DBType_String,
67  DBType_Blob,
68  DBType_Integer,
69  DBType_Float,
70  DBType_NULL,
71  /* --------- */
72  DBTypes_TOTAL,
73  };
74 
85  class IResultRow
86  {
87  public:
100  virtual DBResult GetString(unsigned int columnId, const char **pString, size_t *length) =0;
101 
114  virtual DBResult CopyString(unsigned int columnId,
115  char *buffer,
116  size_t maxlength,
117  size_t *written) =0;
118 
128  virtual DBResult GetFloat(unsigned int columnId, float *pFloat) =0;
129 
139  virtual DBResult GetInt(unsigned int columnId, int *pInt) =0;
140 
147  virtual bool IsNull(unsigned int columnId) =0;
148 
164  virtual size_t GetDataSize(unsigned int columnId) =0;
165 
176  virtual DBResult GetBlob(unsigned int columnId, const void **pData, size_t *length) =0;
177 
189  virtual DBResult CopyBlob(unsigned int columnId, void *buffer, size_t maxlength, size_t *written) =0;
190  };
191 
196  {
197  public:
203  virtual unsigned int GetRowCount() =0;
204 
210  virtual unsigned int GetFieldCount() =0;
211 
218  virtual const char *FieldNumToName(unsigned int columnId) =0;
219 
229  virtual bool FieldNameToNum(const char *name, unsigned int *columnId) =0;
230 
237  virtual bool MoreRows() =0;
238 
246  virtual IResultRow *FetchRow() =0;
247 
254  virtual IResultRow *CurrentRow() =0;
255 
261  virtual bool Rewind() =0;
262 
270  virtual DBType GetFieldType(unsigned int field) =0;
271 
281  virtual DBType GetFieldDataType(unsigned int field) =0;
282  };
283 
284  class IDBDriver;
285 
286  class IQuery
287  {
288  public:
295  virtual IResultSet *GetResultSet() =0;
296 
322  virtual bool FetchMoreResults() =0;
323 
327  virtual void Destroy() =0;
328  };
329 
330  class IPreparedQuery : public IQuery
331  {
332  public:
342  virtual bool BindParamInt(unsigned int param, int num, bool signd=true) =0;
343 
351  virtual bool BindParamFloat(unsigned int param, float f) =0;
352 
359  virtual bool BindParamNull(unsigned int param) =0;
360 
371  virtual bool BindParamString(unsigned int param, const char *text, bool copy) =0;
372 
384  virtual bool BindParamBlob(unsigned int param,
385  const void *data,
386  size_t length,
387  bool copy) =0;
388 
394  virtual bool Execute() =0;
395 
403  virtual const char *GetError(int *errCode=NULL) =0;
404 
410  virtual unsigned int GetAffectedRows() =0;
411 
417  virtual unsigned int GetInsertID() =0;
418  };
419 
420  class IDBDriver;
421 
425  class IDatabase
426  {
427  public:
441  virtual bool Close() =0;
442 
452  virtual const char *GetError(int *errorCode=NULL) =0;
453 
463  virtual bool DoSimpleQuery(const char *query) =0;
464 
477  virtual IQuery *DoQuery(const char *query) =0;
478 
492  virtual IPreparedQuery *PrepareQuery(const char *query, char *error, size_t maxlength, int *errCode=NULL) =0;
493 
505  virtual bool QuoteString(const char *str, char buffer[], size_t maxlen, size_t *newSize) =0;
506 
514  virtual unsigned int GetAffectedRows() =0;
515 
523  virtual unsigned int GetInsertID() =0;
524 
530  virtual bool LockForFullAtomicOperation() =0;
531 
535  virtual void UnlockFromFullAtomicOperation() =0;
536 
542  virtual void IncReferenceCount() =0;
543 
549  virtual IDBDriver *GetDriver() =0;
550 
561  virtual bool DoSimpleQueryEx(const char *query, size_t len) =0;
562 
575  virtual IQuery *DoQueryEx(const char *query, size_t len) =0;
576 
589  virtual unsigned int GetAffectedRowsForQuery(IQuery *query) =0;
590 
602  virtual unsigned int GetInsertIDForQuery(IQuery *query) =0;
603 
609  virtual bool SetCharacterSet(const char *characterset) =0;
610 
611 #if !defined(SOURCEMOD_SQL_DRIVER_CODE)
612 
615  void AddRef() {
617  }
618 
622  void Release() {
623  Close();
624  }
625 #endif
626  };
627 
632  {
633  DatabaseInfo()
634  {
635  dbiVersion = SMINTERFACE_DBI_VERSION;
636  port = 0;
637  maxTimeout = 0;
638  }
639  unsigned int dbiVersion;
640  const char *host;
641  const char *database;
642  const char *user;
643  const char *pass;
644  const char *driver;
645  unsigned int port;
646  unsigned int maxTimeout;
647  };
648 
652  class IDBDriver
653  {
654  public:
655  virtual unsigned int GetDBIVersion()
656  {
657  return SMINTERFACE_DBI_VERSION;
658  }
659  public:
672  virtual IDatabase *Connect(const DatabaseInfo *info, bool persistent, char *error, size_t maxlength) =0;
673 
679  virtual const char *GetIdentifier() =0;
680 
686  virtual const char *GetProductName() =0;
687 
693  virtual Handle_t GetHandle() =0;
694 
701  virtual IdentityToken_t *GetIdentity() =0;
702 
708  virtual bool IsThreadSafe() =0;
709 
715  virtual bool InitializeThreadSafety() =0;
716 
720  virtual void ShutdownThreadSafety() =0;
721  };
722 
726  enum PrioQueueLevel
727  {
728  PrioQueue_High,
729  PrioQueue_Normal,
730  PrioQueue_Low
731  };
732 
737  {
738  public:
746  virtual IDBDriver *GetDriver() =0;
747 
754  virtual IdentityToken_t *GetOwner() =0;
755 
760  virtual void RunThreadPart() =0;
761 
768  virtual void RunThinkPart() =0;
769 
776  virtual void CancelThinkPart() =0;
777 
782  virtual void Destroy() =0;
783  };
784 
788  enum DBHandleType
789  {
790  DBHandle_Driver = 0,
791  DBHandle_Database = 1,
792  };
793 
797  class IDBManager : public SMInterface
798  {
799  public:
800  virtual const char *GetInterfaceName() =0;
801  virtual unsigned int GetInterfaceVersion() =0;
802  public:
808  virtual void AddDriver(IDBDriver *pDriver) =0;
809 
815  virtual void RemoveDriver(IDBDriver *pDriver) =0;
816 
824  virtual const DatabaseInfo *FindDatabaseConf(const char *name) =0;
825 
840  virtual bool Connect(const char *name,
841  IDBDriver **pdr,
842  IDatabase **pdb,
843  bool persistent,
844  char *error,
845  size_t maxlength) =0;
846 
852  virtual unsigned int GetDriverCount() =0;
853 
860  virtual IDBDriver *GetDriver(unsigned int index) =0;
861 
871  virtual Handle_t CreateHandle(DBHandleType type, void *ptr, IdentityToken_t *pToken) =0;
872 
882  virtual HandleError ReadHandle(Handle_t hndl, DBHandleType type, void **ptr) =0;
883 
892  virtual HandleError ReleaseHandle(Handle_t hndl, DBHandleType type, IdentityToken_t *token) =0;
893 
901  virtual IDBDriver *FindOrLoadDriver(const char *driver) =0;
902 
909  virtual IDBDriver *GetDefaultDriver() =0;
910 
919  virtual bool AddToThreadQueue(IDBThreadOperation *op, PrioQueueLevel prio) =0;
920 
927  virtual void AddDependency(IExtension *myself, IDBDriver *driver) =0;
928  };
929 }
930 
931 #endif //_INCLUDE_SOURCEMOD_INTERFACE_DBDRIVER_H_
932 
virtual unsigned int GetInsertID()=0
Retrieves the last insert ID on this database connection.
virtual HandleError ReadHandle(Handle_t hndl, DBHandleType type, void **ptr)=0
Reads an IDBDriver pointer from an IDBDriver handle. Not thread safe.
virtual void RemoveDriver(IDBDriver *pDriver)=0
Removes a driver from the DBI system. Not thread safe.
virtual void AddDriver(IDBDriver *pDriver)=0
Adds a driver to the DBI system. Not thread safe.
virtual DBResult GetString(unsigned int columnId, const char **pString, size_t *length)=0
Retrieves a database field result as a string.
virtual unsigned int GetInsertIDForQuery(IQuery *query)=0
Retrieves the last insert id of the given query.
virtual bool LockForFullAtomicOperation()=0
Locks the database for an atomic query+retrieval operation.
virtual bool FieldNameToNum(const char *name, unsigned int *columnId)=0
Converts a column name to a column id.
Defines the interface for creating, reading, and removing Handles.
virtual DBResult CopyBlob(unsigned int columnId, void *buffer, size_t maxlength, size_t *written)=0
Copies field data as a raw bitstream.
Describes database connection info.
Definition: IDBDriver.h:631
unsigned int port
Definition: IDBDriver.h:645
virtual IResultRow * FetchRow()=0
Returns a pointer to the current row and advances the internal row pointer/counter to the next row av...
virtual const char * GetInterfaceName()=0
Must return a string defining the interface's unique name.
virtual void ShutdownThreadSafety()=0
Shuts down thread safety for the calling thread.
virtual unsigned int GetInsertID()=0
Retrieves the last insert ID on this database connection.
Represents a one database result row.
Definition: IDBDriver.h:85
virtual unsigned int GetDriverCount()=0
Returns the number of drivers loaded. Not thread safe.
virtual void IncReferenceCount()=0
Increases the reference count on the database.
virtual const char * GetIdentifier()=0
Returns a case insensitive database identifier string.
virtual IQuery * DoQuery(const char *query)=0
Prepares and executes a query in one step, and returns the resultant data set.
Defines the Share System, responsible for shared resources and dependencies.
virtual IDatabase * Connect(const DatabaseInfo *info, bool persistent, char *error, size_t maxlength)=0
Initiates a database connection.
virtual Handle_t GetHandle()=0
Retrieves a Handle_t handle of the IDBDriver type.
const char * driver
Definition: IDBDriver.h:644
virtual unsigned int GetRowCount()=0
Returns the number of rows in the set.
virtual void Destroy()=0
Called when the operation is finalized and any resources can be released.
virtual unsigned int GetInterfaceVersion()=0
Must return an integer defining the interface's version.
virtual IResultSet * GetResultSet()=0
Returns a pointer to the current result set, if any.
Defines the base functionality required by a shared interface.
Definition: IShareSys.h:92
virtual IResultRow * CurrentRow()=0
Returns a pointer to the current row.
virtual bool BindParamString(unsigned int param, const char *text, bool copy)=0
Binds a string as a parameter.
virtual HandleError ReleaseHandle(Handle_t hndl, DBHandleType type, IdentityToken_t *token)=0
Releases an IDBDriver handle.
Encapsulates a database connection.
Definition: IDBDriver.h:425
Definition: IDBDriver.h:286
virtual bool BindParamBlob(unsigned int param, const void *data, size_t length, bool copy)=0
Binds a blob of raw data as a parameter.
virtual void Destroy()=0
Frees resources created by this query.
const char * database
Definition: IDBDriver.h:641
virtual IDBDriver * FindOrLoadDriver(const char *driver)=0
Given a driver name, attempts to find it. If it is not found, SourceMod will attempt to load it...
virtual unsigned int GetAffectedRows()=0
Number of rows affected by the last execute.
virtual IdentityToken_t * GetOwner()=0
Must return the object owning this threaded operation. This is never called inside the thread...
virtual DBType GetFieldDataType(unsigned int field)=0
Returns a field's type as it will be interpreted by the GetDataSize() function. For example...
virtual IPreparedQuery * PrepareQuery(const char *query, char *error, size_t maxlength, int *errCode=NULL)=0
Prepares a query statement for multiple executions and/or binding marked parameters (...
virtual bool BindParamFloat(unsigned int param, float f)=0
Binds a float parameter.
virtual bool SetCharacterSet(const char *characterset)=0
Sets the character set of the current connection.
void Release()
Wrapper around Close(), for ke::Ref.
Definition: IDBDriver.h:622
virtual bool AddToThreadQueue(IDBThreadOperation *op, PrioQueueLevel prio)=0
Adds a threaded database operation to the priority queue. This function is not thread safe...
virtual bool MoreRows()=0
Returns if there is still data in the result set.
virtual bool Connect(const char *name, IDBDriver **pdr, IDatabase **pdb, bool persistent, char *error, size_t maxlength)=0
Tries to connect to a named database. Not thread safe.
unsigned int maxTimeout
Definition: IDBDriver.h:646
virtual void RunThinkPart()=0
Called in a server frame after the thread operation has completed. This is the non-threaded completio...
virtual const char * FieldNumToName(unsigned int columnId)=0
Converts a column number to a column name.
void AddRef()
Wrapper around IncReferenceCount(), for ke::Ref.
Definition: IDBDriver.h:615
virtual DBResult GetFloat(unsigned int columnId, float *pFloat)=0
Retrieves a database field result as a float.
virtual size_t GetDataSize(unsigned int columnId)=0
Returns the size of a field (text/raw/blob) in bytes. For strings, this returned size will not includ...
virtual void UnlockFromFullAtomicOperation()=0
Unlocks a locked atomic fetch.
const char * host
Definition: IDBDriver.h:640
virtual bool QuoteString(const char *str, char buffer[], size_t maxlen, size_t *newSize)=0
virtual Handle_t CreateHandle(DBHandleType type, void *ptr, IdentityToken_t *pToken)=0
Creates a Handle_t of the IDBDriver type. Not thread safe.
virtual void RunThreadPart()=0
Called inside the thread; this is where any blocking or threaded operations must occur.
Describes the DBI manager.
Definition: IDBDriver.h:797
Describes an SQL driver.
Definition: IDBDriver.h:652
virtual bool DoSimpleQueryEx(const char *query, size_t len)=0
Prepares and executes a binary query in one step, and discards any return data.
virtual bool IsThreadSafe()=0
Returns whether the driver is thread safe.
Definition: IDBDriver.h:330
virtual bool Rewind()=0
Rewinds back to the beginning of the row iteration.
const char * user
Definition: IDBDriver.h:642
virtual DBResult CopyString(unsigned int columnId, char *buffer, size_t maxlength, size_t *written)=0
Retrieves a database field result as a string, using a user-supplied buffer. If the field is NULL...
IExtension * myself
Definition: smsdk_ext.cpp:41
virtual unsigned int GetAffectedRowsForQuery(IQuery *query)=0
Retrieves the number of affected rows from the last execute of the given query.
virtual unsigned int GetAffectedRows()=0
Number of rows affected by the last execute.
Definition: IAdminSystem.h:63
unsigned int dbiVersion
Definition: IDBDriver.h:639
virtual bool DoSimpleQuery(const char *query)=0
Prepares and executes a query in one step, and discards any return data.
Encapsulates an IExtensionInterface and its dependencies.
Definition: IExtensionSys.h:53
virtual IQuery * DoQueryEx(const char *query, size_t len)=0
Prepares and executes a binary query in one step, and returns the resultant data set.
virtual DBResult GetBlob(unsigned int columnId, const void **pData, size_t *length)=0
Retrieves field data as a raw bitstream. The pointer returned will become invalid after advancing to ...
virtual bool BindParamNull(unsigned int param)=0
Binds an SQL NULL type as a parameter.
virtual bool Close()=0
Disconnects the database and frees its associated memory. Note that the actual object will not be fre...
Describes a set of database results.
Definition: IDBDriver.h:195
virtual const char * GetError(int *errCode=NULL)=0
Returns the last error message from this statement.
virtual const char * GetProductName()=0
Returns a case sensitive implementation name.
virtual bool Execute()=0
Executes the query with the currently bound parameters.
virtual IDBDriver * GetDefaultDriver()=0
Returns the default driver, or NULL if none is set. This function is not thread safe.
virtual bool IsNull(unsigned int columnId)=0
Returns whether or not a field is NULL.
virtual DBResult GetInt(unsigned int columnId, int *pInt)=0
Retrieves a database field result as an integer.
virtual DBType GetFieldType(unsigned int field)=0
Returns a field's type as it should be interpreted by the user.
virtual IDBDriver * GetDriver()=0
Must return the driver this operation is using, or NULL if not using any driver. This is not never in...
virtual IDBDriver * GetDriver(unsigned int index)=0
Returns a driver by index. Not thread safe.
virtual const DatabaseInfo * FindDatabaseConf(const char *name)=0
Searches for database info by name. Both the return pointer and all pointers contained therein should...
virtual IdentityToken_t * GetIdentity()=0
Returns the driver's controlling identity (must be the same as from IExtension::GetIdentity).
virtual bool InitializeThreadSafety()=0
Initializes thread safety for the calling thread.
virtual void AddDependency(IExtension *myself, IDBDriver *driver)=0
Adds a dependency from one extension to the owner of a driver.
virtual bool BindParamInt(unsigned int param, int num, bool signd=true)=0
Binds an integer parameter.
virtual unsigned int GetFieldCount()=0
Returns the number of fields in the set.
virtual bool FetchMoreResults()=0
Advances to the next result set if one exists. This is for checking for MORE result sets...
virtual const char * GetError(int *errorCode=NULL)=0
Error code and string returned by the last operation on this connection.
Definition: IDBDriver.h:736
const char * pass
Definition: IDBDriver.h:643
virtual void CancelThinkPart()=0
If RunThinkPart() is not called, this will be called instead. Note that RunThreadPart() is ALWAYS cal...
virtual IDBDriver * GetDriver()=0
Returns the parent driver.