Calling The Windows API

Detailed information on how developers can access the Windows API (Application Programmer Interface) from within XpertRule is beyond the scope of this documentation. However, this can very effectively be achieved by using XpertRule DLL commands. In many instances, specific API functions can be utilised by calling an existing Windows DLL directly. For more advanced API calls, you will need to produce a custom DLL to include the API call.

General information on API functions can be found in the MICROSOFT SYSTEM DEVELOPERS KIT (SDK). While this documents the API functions in great detail, using the functions from within your own DLL, or finding out where a specific API function call is already available via an existing Windows DLL, is not so easy.

Some popular programming languages include source files that will help use API calls, and will also identify existing DLL's that contain API calls.

When trying to use Windows API calls the following tips may be useful:

·Make sure the dll can be located via the Path environment variable, or provide a full path location for the dll or even place a copy of the dll in the same directory as the xra.

·If a parameter is passed by reference use the * to indicate a pointer, otherwise omit the * when passed by value.

·Make sure the data types are correct in the parameter list.

·Make sure the calling convention of S (stdCall) is used in the DLLopen command.

·Evaluate constants and pass their value instead of the constant text, for example pass 63 instead of 'KEY_ALL_ACCESS'.

Examples of Windows API calls:

--------------ReadINIkey--------------
Function (inifile:S, inisection:S, iniattribute:S):S
@Rem example call - Debug ReadINIkey('C:\xrkb.ini','MAIN','SERIALNO')
@Dim retstr:S, tmplen:N
@DLLopen 'Kernel32.dll','GetPrivateProfileStringA',S,S,S,S,*L,S;S
@DLLcall 'GetPrivateProfileStringA',inisection,iniattribute,'',retstr,tmplen,inifile
@DLLclose 'GetPrivateProfileStringA'
@Return retstr
--------------ReadRegKey--------------
Function (keypath:S, keyname:S, val_name:S) :S
@Rem example call - Debug ReadRegKey('HKEY_LOCAL_MACHINE','SOFTWARE\Microsoft\Windows\CurrentVersion','ProgramFilesDir')
@Dim type:N, len:N, handle:N, retstr:S
@Dim HKEY_LOCAL_MACHINE:N, KEY_ALL_ACCESS:N
@Assign HKEY_LOCAL_MACHINE = -2147483646
@Assign KEY_ALL_ACCESS = 63
@DLLopen 'Advapi32.dll','RegOpenKeyExA',L,S,L,L,*L;S
@DLLopen 'Advapi32.dll','RegQueryValueExA',L,S,L,*L,S,*L;S
@DLLopen 'Advapi32.dll','RegCloseKey',L;S
@DLLcall 'RegOpenKeyExA',HKEY_LOCAL_MACHINE,keyname,0,KEY_ALL_ACCESS,handle
@Rem query first to get the length and data type
@DLLcall 'RegQueryValueExA',handle,val_name,0,type,0,len
@Rem repeat query to get the value
@DLLcall 'RegQueryValueExA',handle,val_name,0,type,retstr,len
@DLLcall 'RegCloseKey',handle
@DLLclose 'RegCloseKey'
@DLLclose 'RegQueryValueExA'
@DLLclose 'RegOpenKeyExA'
@Return retstr