C# Class ALFA.Database

This class encapsulates database access for ALFA CLR scripts. Unlike the ad-hoc ALFA.MySQLDatabase class, this class supports a single, "canonical" standard default database connection with the following properties: - There is only one underlying connection so queries are completed in order. - The combined query queue ("ACR_AsyncSQLQuery[Ex]") is synchronized with queries issued on an ALFA.Database object. - All instances of ALFA.Database are synchronized with one another. Generally, "state changing" queries that have to synchronize with the updates performed via NWScript must go through this query. Queries that may be processed independently, e.g. the GameWorldManager in the ACR_ServerCommunicator, may use a standalone connection instead for better performance if they do not require synchronization with the canonical database connection.

Inheritance: IALFADatabase

Show file Open project: ALandFarAway/ALFA-Base-Resources Class Usage Examples

Public Methods

Method	Description
ACR_AsyncSQLQuery ( string Query ) : void	Perform an asynchronous database query. The query is added to the module object's query queue.
ACR_AsyncSQLQueryEx ( string Query, UInt32 QueueTo, ACR_QUERY_FLAGS Flags = ACR_QUERY_FLAGS.None ) : void	Perform an asynchronous database query. The query is added to a specific object's query queue (must be a PC or the module).
ACR_ConvertDatabaseStringToBoolean ( string Str ) : bool	Convert a database string to a Boolean value.
ACR_DeletePersistentVariable ( UInt32 Object, string VarName ) : void	Delete a persistent record.
ACR_FlushAllQueryQueues ( ) : void	Flush all query queues in the system out to the database.
ACR_FlushQueryQueue ( uint ObjectToFlush ) : void	This routine flushes the query queue for an object. It is useful, for example, in server portal scenarios. Normally, the query queue is flushed automatically.
ACR_GetBuildDate ( ) : string	Get the build date of the module OnLoad script (i.e. the time at which the module had its scripts nominally compiled).
ACR_GetCharacterID ( UInt32 PCObject ) : int	This routine returns the database character ID for a player given their PC object id.
ACR_GetHAKBuildDate ( ) : string	Get the build date of the HAK version check script (i.e. the time at which the ACR HAK had its scripts nominally compiled).
ACR_GetHAKVersion ( ) : string	Get the version string of the ACR release that the HAK corresponds to. For example, "1.84".
ACR_GetIsMember ( UInt32 PCObject ) : bool	Returns whether a PC is a fully approved ALFA member (vs. a new account that might be a throw-away, etc.).
ACR_GetIsPCQuarantined ( UInt32 PCObject ) : bool	Return whether a PC is quarantined.
ACR_GetPCLocalFlags ( UInt32 PCObject ) : int	Return the current PC local flags value for a PC.
ACR_GetPersistentFloat ( UInt32 Object, string VarName ) : float	Retrieve a float from the persistent store.
ACR_GetPersistentInt ( UInt32 Object, string VarName ) : int	Retrieve an int from the persistent store.
ACR_GetPersistentLocation ( UInt32 Object, string VarName ) : NWScript.NWScriptEngineStructure2	Retrieve a location from the persistent store.
ACR_GetPersistentString ( UInt32 Object, string VarName ) : string	Retrieve a string from the persistent store.
ACR_GetPersistentVector ( UInt32 Object, string VarName ) : System.Vector3	Retrieve a vector from the persistent store.
ACR_GetPlayerID ( UInt32 PCObject ) : int	This routine returns the database player ID for a player given their PC object id.
ACR_GetServerAddressFromDatabase ( ) : string	This routine queries the database in order to return the public IP address of the game server host.
ACR_GetServerID ( ) : int	This routine returns the database server ID of the current server.
ACR_GetVersion ( ) : string	Get the version string of the ACR release that the module was compiled against. For example, "1.84".
ACR_IncrementStatistic ( string Statistic ) : void	Increment a global tracking statistic counter stored in the database (if statistic tracking was enabled).
ACR_IsServerAdmin ( UInt32 PCObject ) : bool	This routine determines whether a player is a server admin for the current server.
ACR_LocationToString ( NWScript.NWScriptEngineStructure2 Location ) : string	This routine packages a location object into a string.
ACR_LogEvent ( uint Character, string EventName, string EventDescription, uint DM ) : void	Log an event to the database log.
ACR_PCSave ( uint PCToSave, bool Export, bool SaveLocation ) : void	This routine performs a character save.
ACR_PCUpdateStatus ( uint PCToUpdate, bool UpdateLocation ) : void	This method updates regularly-saved persistent information.
ACR_PPSValidatePC ( uint PCToValidate ) : void	This routine validates a character from quarantine.
ACR_RestOnClientEnter ( uint PCToRest ) : void	This method calculates offline resting for a PC after logging in.
ACR_RunScriptOnServer ( int DestinationServerID, string ScriptName, string ScriptArgument ) : bool	Run a script on a remote server. The script must exist on the server. If acknowledgement is desired, it must be implemented in the form of a reply IPC request initiated by the script invoked. A script executed by this function must follow this prototype: void main(int SourceServerID, string Argument);
ACR_SQLEncodeSpecialChars ( string s ) : string	This routine escapes characters for a SQL query.
ACR_SQLExecute ( string SQL ) : void	This routine performs a synchronous SQL query. If there were pending asynchronous queries in the queue, the pending queries are drained first. The query must not return any results.
ACR_SQLFetch ( ) : bool	This routine fetches the next rowset from the database.
ACR_SQLGetAffectedRows ( ) : int	This routine returns the number of rows affected by a query.
ACR_SQLGetData ( ) : string	This routine returns the first column of data from the current SQL rowset.
ACR_SQLGetData ( int ColumnIndex ) : string	This routine returns the specified column of data from the current SQL rowset.
ACR_SQLQuery ( string SQL ) : void	This routine performs a synchronous SQL query. If there were pending asynchronous queries in the queue, the pending queries are drained first.
ACR_SetPCLocalFlags ( UInt32 PCObject, int Flags ) : void	Assigns the current PC local flags value for a PC.
ACR_SetPersistentFloat ( UInt32 Object, string VarName, float Value ) : void	Set a floating point value in the persistent store.
ACR_SetPersistentInt ( UInt32 Object, string VarName, int Value ) : void	Set an integer value in the persistent store.
ACR_SetPersistentLocation ( UInt32 Object, string VarName, NWScript.NWScriptEngineStructure2 Value ) : void	Set a vector value in the persistent store.
ACR_SetPersistentString ( UInt32 Object, string VarName, string Value ) : void	Set a string value in the persistent store.
ACR_SetPersistentVector ( UInt32 Object, string VarName, System.Vector3 Value ) : void	Set a vector value in the persistent store.
ACR_StringToLocation ( string sLocation ) : NWScript.NWScriptEngineStructure2	This routine converts a string to a location.
ACR_StringToLocationData ( string sLocation ) : LOCATION_DATA	This routine converts a string to its component location data fields.
ACR_StringToVector ( string sVector ) : System.Vector3	Convert a string to a vector.
ACR_VectorToString ( System.Vector3 v ) : string	This routine packages a vector into a string.
ACR_XPOnClientLoaded ( uint PCToXP ) : void	This method calculates RPXP for the last playing session.
Database ( CLRScriptBase ScriptBase ) : System	Create a new database object (which can be shared by multiple script objects).

Private Methods

Method	Description
DemandInitialize ( ) : void	This method performs demand initialization of the database system on the first database call.
RegisterScriptSituationDelegate ( IGeneratedScriptProgram DelegateScript ) : void	This method sets the user's script object to delegate unrecognized script situations to the NWScript library script, allowing a delay continuation started by called NWScript code to function properly.

Method Details

ACR_AsyncSQLQuery() public method

Perform an asynchronous database query. The query is added to the module object's query queue.

public ACR_AsyncSQLQuery ( string Query ) : void
Query	string	Supplies the query string.
return	void

ACR_AsyncSQLQueryEx() public method

Perform an asynchronous database query. The query is added to a specific object's query queue (must be a PC or the module).

public ACR_AsyncSQLQueryEx ( string Query, UInt32 QueueTo, ACR_QUERY_FLAGS Flags = ACR_QUERY_FLAGS.None ) : void
Query	string	Supplies the query string.
QueueTo	System.UInt32	Supplies the object to queue the query to, /// which should be a PC or the module object.
Flags	ACR_QUERY_FLAGS	Supplies query flags.
return	void

ACR_ConvertDatabaseStringToBoolean() public static method

Convert a database string to a Boolean value.

public static ACR_ConvertDatabaseStringToBoolean ( string Str ) : bool
Str	string	Supplies the database string.
return	bool

ACR_DeletePersistentVariable() public method

Delete a persistent record.

public ACR_DeletePersistentVariable ( UInt32 Object, string VarName ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to remove. ///
return	void

ACR_FlushAllQueryQueues() public method

Flush all query queues in the system out to the database.

public ACR_FlushAllQueryQueues ( ) : void
return	void

ACR_FlushQueryQueue() public method

This routine flushes the query queue for an object. It is useful, for example, in server portal scenarios. Normally, the query queue is flushed automatically.

public ACR_FlushQueryQueue ( uint ObjectToFlush ) : void
ObjectToFlush	uint	Supplies the object whose query queue /// should be flushed.
return	void

ACR_GetBuildDate() public method

Get the build date of the module OnLoad script (i.e. the time at which the module had its scripts nominally compiled).

public ACR_GetBuildDate ( ) : string
return	string

ACR_GetCharacterID() public method

This routine returns the database character ID for a player given their PC object id.

public ACR_GetCharacterID ( UInt32 PCObject ) : int
PCObject	System.UInt32	Supplies the object ID of the player to /// query.
return	int

ACR_GetHAKBuildDate() public method

Get the build date of the HAK version check script (i.e. the time at which the ACR HAK had its scripts nominally compiled).

public ACR_GetHAKBuildDate ( ) : string
return	string

ACR_GetHAKVersion() public method

Get the version string of the ACR release that the HAK corresponds to. For example, "1.84".

public ACR_GetHAKVersion ( ) : string
return	string

ACR_GetIsMember() public method

Returns whether a PC is a fully approved ALFA member (vs. a new account that might be a throw-away, etc.).

public ACR_GetIsMember ( UInt32 PCObject ) : bool
PCObject	System.UInt32	Supplies the PC object.
return	bool

ACR_GetIsPCQuarantined() public method

Return whether a PC is quarantined.

public ACR_GetIsPCQuarantined ( UInt32 PCObject ) : bool
PCObject	System.UInt32	Supplies the PC object.
return	bool

ACR_GetPCLocalFlags() public method

Return the current PC local flags value for a PC.

public ACR_GetPCLocalFlags ( UInt32 PCObject ) : int
PCObject	System.UInt32	Supplies the PC object.
return	int

ACR_GetPersistentFloat() public method

Retrieve a float from the persistent store.

public ACR_GetPersistentFloat ( UInt32 Object, string VarName ) : float
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to query.
return	float

ACR_GetPersistentInt() public method

Retrieve an int from the persistent store.

public ACR_GetPersistentInt ( UInt32 Object, string VarName ) : int
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to query.
return	int

ACR_GetPersistentLocation() public method

Retrieve a location from the persistent store.

public ACR_GetPersistentLocation ( UInt32 Object, string VarName ) : NWScript.NWScriptEngineStructure2
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to query.
return	NWScript.NWScriptEngineStructure2

ACR_GetPersistentString() public method

Retrieve a string from the persistent store.

public ACR_GetPersistentString ( UInt32 Object, string VarName ) : string
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to query.
return	string

ACR_GetPersistentVector() public method

Retrieve a vector from the persistent store.

public ACR_GetPersistentVector ( UInt32 Object, string VarName ) : System.Vector3
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to query.
return	System.Vector3

ACR_GetPlayerID() public method

This routine returns the database player ID for a player given their PC object id.

public ACR_GetPlayerID ( UInt32 PCObject ) : int
PCObject	System.UInt32	Supplies the object ID of the player to /// query.
return	int

ACR_GetServerAddressFromDatabase() public method

This routine queries the database in order to return the public IP address of the game server host.

public ACR_GetServerAddressFromDatabase ( ) : string
return	string

ACR_GetServerID() public method

This routine returns the database server ID of the current server.

public ACR_GetServerID ( ) : int
return	int

ACR_GetVersion() public method

Get the version string of the ACR release that the module was compiled against. For example, "1.84".

public ACR_GetVersion ( ) : string
return	string

ACR_IncrementStatistic() public method

Increment a global tracking statistic counter stored in the database (if statistic tracking was enabled).

public ACR_IncrementStatistic ( string Statistic ) : void
Statistic	string	Supplies the counter name.
return	void

ACR_IsServerAdmin() public method

This routine determines whether a player is a server admin for the current server.

public ACR_IsServerAdmin ( UInt32 PCObject ) : bool
PCObject	System.UInt32	Supplies the object ID of the player to /// query.
return	bool

ACR_LocationToString() public method

This routine packages a location object into a string.

public ACR_LocationToString ( NWScript.NWScriptEngineStructure2 Location ) : string
Location	NWScript.NWScriptEngineStructure2	Supplies the location to convert.
return	string

ACR_LogEvent() public method

Log an event to the database log.

public ACR_LogEvent ( uint Character, string EventName, string EventDescription, uint DM ) : void
Character	uint	Supplies an optional character that is /// associated with the log event, else OBJECT_INVALID if none.
EventName	string	Supplies the log event name.
EventDescription	string	Supplies the log event description. ///
DM	uint	Supplies an optional DM character that is /// associated with the log event, else OBJECT_INVALID if none.
return	void

ACR_PCSave() public method

This routine performs a character save.

public ACR_PCSave ( uint PCToSave, bool Export, bool SaveLocation ) : void
PCToSave	uint	Supplies the object id of the player to /// save.
Export	bool	If true, save the character file to disk too. ///
SaveLocation	bool	If true, update the location of the /// player in the database.
return	void

ACR_PCUpdateStatus() public method

This method updates regularly-saved persistent information.

public ACR_PCUpdateStatus ( uint PCToUpdate, bool UpdateLocation ) : void
PCToUpdate	uint	the PC to be updated
UpdateLocation	bool	whether or not to also update location
return	void

ACR_PPSValidatePC() public method

This routine validates a character from quarantine.

public ACR_PPSValidatePC ( uint PCToValidate ) : void
PCToValidate	uint
return	void

ACR_RestOnClientEnter() public method

This method calculates offline resting for a PC after logging in.

public ACR_RestOnClientEnter ( uint PCToRest ) : void
PCToRest	uint	the PC to be rested
return	void

ACR_RunScriptOnServer() public method

Run a script on a remote server. The script must exist on the server. If acknowledgement is desired, it must be implemented in the form of a reply IPC request initiated by the script invoked. A script executed by this function must follow this prototype: void main(int SourceServerID, string Argument);

public ACR_RunScriptOnServer ( int DestinationServerID, string ScriptName, string ScriptArgument ) : bool
DestinationServerID	int	Supplies the destination server /// ID.
ScriptName	string	Supplies the name of the script.
ScriptArgument	string	Supplies an optional argument to pass /// to the script.
return	bool

ACR_SQLEncodeSpecialChars() public method

This routine escapes characters for a SQL query.

public ACR_SQLEncodeSpecialChars ( string s ) : string
s	string	Supplies the string to escape.
return	string

ACR_SQLExecute() public method

This routine performs a synchronous SQL query. If there were pending asynchronous queries in the queue, the pending queries are drained first. The query must not return any results.

public ACR_SQLExecute ( string SQL ) : void
SQL	string	Supplies the SQL query text to execute.
return	void

ACR_SQLFetch() public method

This routine fetches the next rowset from the database.

public ACR_SQLFetch ( ) : bool
return	bool

ACR_SQLGetAffectedRows() public method

This routine returns the number of rows affected by a query.

public ACR_SQLGetAffectedRows ( ) : int
return	int

ACR_SQLGetData() public method

This routine returns the first column of data from the current SQL rowset.

public ACR_SQLGetData ( ) : string
return	string

ACR_SQLGetData() public method

This routine returns the specified column of data from the current SQL rowset.

public ACR_SQLGetData ( int ColumnIndex ) : string
ColumnIndex	int	Supplies the zero-based column index to /// retrieve.
return	string

ACR_SQLQuery() public method

This routine performs a synchronous SQL query. If there were pending asynchronous queries in the queue, the pending queries are drained first.

public ACR_SQLQuery ( string SQL ) : void
SQL	string	Supplies the SQL query text to execute.
return	void

ACR_SetPCLocalFlags() public method

Assigns the current PC local flags value for a PC.

public ACR_SetPCLocalFlags ( UInt32 PCObject, int Flags ) : void
PCObject	System.UInt32	Supplies the PC object.
Flags	int	Supplies the new Local Flags value.
return	void

ACR_SetPersistentFloat() public method

Set a floating point value in the persistent store.

public ACR_SetPersistentFloat ( UInt32 Object, string VarName, float Value ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to set.
Value	float	Supplies the variable data.
return	void

ACR_SetPersistentInt() public method

Set an integer value in the persistent store.

public ACR_SetPersistentInt ( UInt32 Object, string VarName, int Value ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to set.
Value	int	Supplies the variable data.
return	void

ACR_SetPersistentLocation() public method

Set a vector value in the persistent store.

public ACR_SetPersistentLocation ( UInt32 Object, string VarName, NWScript.NWScriptEngineStructure2 Value ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to set.
Value	NWScript.NWScriptEngineStructure2	Supplies the variable data.
return	void

ACR_SetPersistentString() public method

Set a string value in the persistent store.

public ACR_SetPersistentString ( UInt32 Object, string VarName, string Value ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to set.
Value	string	Supplies the variable data.
return	void

ACR_SetPersistentVector() public method

Set a vector value in the persistent store.

public ACR_SetPersistentVector ( UInt32 Object, string VarName, System.Vector3 Value ) : void
Object	System.UInt32	Supplies the object whose persistent store is /// to be accessed.
VarName	string	Supplies the variable keyword to set.
Value	System.Vector3	Supplies the variable data.
return	void

ACR_StringToLocation() public method

This routine converts a string to a location.

public ACR_StringToLocation ( string sLocation ) : NWScript.NWScriptEngineStructure2
sLocation	string	Supplies the string to convert.
return	NWScript.NWScriptEngineStructure2

ACR_StringToLocationData() public method

This routine converts a string to its component location data fields.

public ACR_StringToLocationData ( string sLocation ) : LOCATION_DATA
sLocation	string	Supplies the string to convert.
return	LOCATION_DATA

ACR_StringToVector() public method

Convert a string to a vector.

public ACR_StringToVector ( string sVector ) : System.Vector3
sVector	string	Supplies the string to convert.
return	System.Vector3

ACR_VectorToString() public method

This routine packages a vector into a string.

public ACR_VectorToString ( System.Vector3 v ) : string
v	System.Vector3	Supplies the vector to convert.
return	string

ACR_XPOnClientLoaded() public method

This method calculates RPXP for the last playing session.

public ACR_XPOnClientLoaded ( uint PCToXP ) : void
PCToXP	uint	the PC to XP
return	void

Database() public method

Create a new database object (which can be shared by multiple script objects).

public Database ( CLRScriptBase ScriptBase ) : System
ScriptBase	CLRScriptFramework.CLRScriptBase	Supplies the associated script base class /// object, used to access script APIs.
return	System