{* UltraStar Deluxe - Karaoke Game
*
* UltraStar Deluxe is the legal property of its developers, whose names
* are too numerous to list here. Please refer to the COPYRIGHT
* file distributed with this source distribution.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; see the file COPYING. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*
* $URL: https://ultrastardx.svn.sourceforge.net/svnroot/ultrastardx/trunk/src/base/UMain.pas $
* $Id: UMain.pas 1485 2008-10-28 20:16:05Z tobigun $
*}
{*
some defines that are used by usdx and plugins
*}
unit UPluginDefines;
interface
{$IFDEF FPC}
{$MODE Delphi}
{$ENDIF}
{$I switches.inc}
const
SDK_Version = 0001000000000000; //< identifies the used SDK version (1.0.0.0)
type
{ this type is used for all version ints in this SDK }
TUS_Version = LongInt;
{ this type is used for all plugin handles in this SDK }
TUS_Handle = LongInt;
const
US_HANDLE_CORE = 137; //handle of core, also first defined handle
US_HANDLE_UNDEFINED = 0; //undefined handle, used to indicate errors
{ this type is used for all id strings in this SDK }
const
MaxLength_TUS_Identifier = 32; //max length of identifier strings, has to be multiply of 4
type
TUS_Identifier = String[MaxLength_TUS_Identifier];
{ this record is used to offer some information about this plugin to the core }
TUS_PluginInfo = packed record
Name : Array [1..32] of Char; //name of the plugin
Author : Array [1..32] of Char; //plugins author
PluginDesc : Array [1..64] of Char; //some further explentation
Version : TUS_Version;
end;
PUS_PluginInfo = ^TUS_PluginInfo;
{ this function reads the plugins information from a TUS_PluginInfo record,
and saves it. Can be called onced per plugin.
Version is the SDK_Version used by the plugin
BufferLength is the size of buffer in bytes }
TUS_Func_Identify = function (Handle: TUS_Handle; Version: TUS_Version; Buffer: PUS_PluginInfo; BufferLength: LongInt): LongInt; stdcall;
{ this plugin is used for selfshutdown by the plugin on an error
case.
Reason should be used to describe the reason for the shutdown
OnChangeStatus(psDeInited) is called when old status was psInited }
TUS_Func_Error = function (Handle: TUS_Handle; Reason: PWideChar): LongInt; stdcall;
{ this function writes the plugins filename including its path ,
to buffer. A call with Buffer=nil or Len<=0 returns the actual
length of the path.
BufferLength is the size of buffer in bytes
Filename is used to identify duplicate load of one plugin
so it should even set when plugin is not loaded from file}
TUS_Func_GetFilename = function (Handle: TUS_Handle; Version: TUS_Version; Buffer: PWideChar; BufferLength: LongInt): LongInt; stdcall;
{ this function writes an interface, identified by 'ID', to the
buffer.
Version is the version of the interface that is used
BufferLength is the size of buffer in bytes}
TUS_Func_GetInterface = function (ID: TUS_Identifier; Version: TUS_Version; Buffer: Pointer; BufferLength: LongInt): LongInt; stdcall;
{ this function reads an interface, identified by 'ID', from the
buffer, to offer it to calls of GetInterface.
version is the version of the interface
BufferLength is the size of buffer in bytes }
TUS_Func_SetInterface = function (ID: TUS_Identifier; Version: TUS_Version; Buffer: Pointer; BufferLength: LongInt): LongInt; stdcall;
{ this function writes a record or some other data,
identified by 'ID', to the buffer.
Version is the version of the data that is used
BufferLength is the size of buffer in bytes}
TUS_Func_GetData = function (ID: TUS_Identifier; Version: TUS_Version; Buffer: Pointer; BufferLength: LongInt): LongInt; stdcall;
{ this function reads a record or some other data,
identified by 'ID', from the buffer, to offer it
to calls of GetData.
version is the version of the record
BufferLength is the size of buffer in bytes }
TUS_Func_SetData = function (ID: TUS_Identifier; Version: TUS_Version; Buffer: Pointer; BufferLength: LongInt): LongInt; stdcall;
{ a record w/ some useful methods for plugins }
TUS_PluginInterface = packed record
Version : TUS_Version; //SDK_Version
Handle : LongInt; //the plugins handle
Identify : TUS_Func_Identify;
Error : TUS_Func_Error;
GetFilename : TUS_Func_GetFilename;
GetInterface: TUS_Func_GetInterface;
SetInterface: TUS_Func_SetInterface;
GetData : TUS_Func_GetData;
SetData : TUS_Func_SetData;
end;
PUS_PluginInterface = ^TUS_PluginInterface;
{ this function writes the PluginInterface to the buffer }
TUS_Func_InitInterface = function (Handle: TUS_Handle; Version: TUS_Version; Buffer: PUS_PluginInterface; BufferSize: LongInt): LongInt;
{$IFDEF MSWINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
{ this function is called by core, in the WaitingInit status
it offers the plugin the possibility to load its plugininterface
and to check it's sdk version against the cores.
It has to be implemented by plugins loaded as library }
TUS_Plugin_Proc_Init = procedure (Handle: TUS_Handle; CoreVersion: TUS_Version; InitInterface: TUS_Func_InitInterface);
{$IFDEF MSWINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
TUS_PluginStatus = (psNone, psWaitingInit, psWaitingIdentify, psInited, psDeInited, psError);
{ this function is called everytime tbe plugins status changes
status is the new status.
it has to be implemented by plugins loaded as library }
TUS_Plugin_OnChangeStatus = procedure (Handle: TUS_Handle; Status: TUS_PluginStatus);
{$IFDEF MSWINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
{ this interface represents a loaded plugin, it eitber has to
be implemented by the pluginloader, e.g. for libs or by the
plugin itself in the case of integrated plugins }
IUS_Plugin = Interface
['{23F7B722-D979-4402-9953-C6B229A6E888}']
function GetStatus: TUS_PluginStatus;
procedure SetStatus(status: TUS_PluginStatus);
function GetHandle: TUS_Handle;
function GetUniqueID: TUS_Handle; //< This ID is unique for the given plugin it may be a hash of the plugins code or s/t like that. used to identify plugins laoded twice
function GetFilename: WideString;
Procedure Init;
Procedure DeInit;
Procedure SetError(Reason: WideString);
Function GetErrorReason: WideString;
end;
{ this function will be called when a hookable event is spawn
data is a pointer to a struct that can contain any data
defined by the event creator. if there is no data this should
be nil.
breakable is true if the hook chain can be interupted by
returning US_HOOK_BREAK or US_HOOK_UNHOOKME_BREAK
by returning US_HOOK_UNHOOKME the callback will immediately
be removed from the chain }
TUS_Func_OnEvent = function(data: pointer; breakable: boolean): integer;
TUS_cFunc_OnEvent = function(data: pointer; breakable: boolean): integer of object;
{ this interface represents an event that can be hooked by
e.g. the core or other}
IUS_HookableEvent = Interface
// this GID has to be changed if we change this interface
['{FFC6F09D-EC0B-41E2-87F6-70EC6F055C0E}']
function GetIdentifier: TUS_Identifier;
function GetHash: LongInt;
//adds the callback to the top of the events hook chain
//proc is the callback function
//parent is the plugins handle, or US_HANDLE_CORE if called by core
//returns hook-handle on succes or US_HANDLE_UNDEFINED on failure
function Hook(proc: TUS_Func_OnEvent; Parent: TUS_Handle): TUS_Handle;
function cHook(proc: TUS_cFunc_OnEvent; Parent: TUS_Handle): TUS_Handle;
//removes a callback from the chain using the handle returned
//by the hook function
//returns an US_ERROR code
function UnHook(Handle: TUS_Handle): byte;
//removes all callbacks of a specified parent (plugin)
procedure UnHookbyParent(Parent: TUS_Handle);
end;
const
{ some errorcodes that are returned by functions using this SDK }
US_ERROR_None = 0; //< indicates success ;)
US_ERROR_VersionMismatch = 1; //< returned when the version the plugin wants to use is not supported
US_ERROR_SizeMismatch = 2; //< returned when the wanted data does not fit the buffersize
US_ERROR_WrongHandle = 3; //< returned when the given handle is not
US_ERROR_WrongID = 4; //< returned when the given id does not exist
US_ERROR_NameExists = 5; //< returned when the given name already exists
US_ERROR_Unknown = 255; //< returned when an unknown error occured
{ return values for hook function }
US_HOOK_BREAK = High(integer); //this will break the hook chain
US_HOOK_UNHOOKME = High(integer) - 2; //this will remove the callback from the hooks chain
US_HOOK_UNHOOKME_BREAK = High(integer) - 1; //this will do both explained above
{ this function converts an errorcode to its textual expression }
function USErrortoString(Code: LongInt): String;
{ this funtion creates a hash for an TUS_Identifier
the hash is not guaranteed to be unique, it is just
for a fast search of an identifier }
function CalculateUSHash(Identifier: TUS_Identifier): LongInt;
implementation
{ this function converts an errorcode to its textual expression }
Function USErrortoString(Code: LongInt): String;
begin
Case Code of
US_Error_None: Result := 'success, no error occured';
US_Error_VersionMismatch: Result := 'version mismatch';
US_Error_SizeMismatch: Result := 'size mismatch';
US_Error_WrongHandle: Result := 'handle does not exist';
US_Error_WrongID: Result := 'id does not exist';
US_Error_NameExists: Result := 'another item with this name does already exist';
Else Result := 'unknown error';
end;
end;
{ this funtion creates a hash for an TUS_Identifier
the hash is not guaranteed to be unique, it is just
for a fast search of an identifier }
function CalculateUSHash(Identifier: TUS_Identifier): LongInt;
var
L: Integer;
I: Integer;
const
StartHash = -1337456101;
begin
// fill the unused chars of the identifier w/ zeros
L := Length(Identifier);
if (L < MaxLength_TUS_Identifier) then
FillChar(Identifier[L+1], MaxLength_TUS_Identifier - L, 0);
// calculate the hash
// this is done by just adding respectively 4 bytes of the string
// to the hash (longint)
Result := StartHash;
for I := 1 to (MaxLength_TUS_Identifier div 4) do
Result := Result + LongInt(Identifier[I*4]);
end;
end.
