Hamster-Scripts: Functions (built-in)

Dynamic link libraries

DllLoad( <filename> )

DllFree( <handle> )

Loads/unloads the given dynamic link library file (*.dll) into memory.
To use Windows API functions (e.g. "kernel32.dll"), such pre-loading is not necessary.

Returns: <>0: Handle of DLL, =0: Error (check DllLastError for reason)

$hdl = DllLoad( "my.dll" )
DllFree( $hdl )

DllLastError

'GetLastError' value of last call to DllLoad or DllCall.

Returns: Error value of last Dll-call.

$hdl = DllLoad( "my.dll" )
DllFree( $hdl )

DllCall( <declaration>, <parameter1>, <parameter2>, ... )

Invokes a function of a dynamic link library with up to 11 parameters. If the library was (pre-) loaded with DllLoad, this instance is automatically used when calling one of its functions. If a function is called without such pre-loading, the library is loaded temporarily for each call.

The function called has to be described in <declaration>. It consists of four parts separated by a "|" character, e. g. "user32.dll|GetWindowTextA|n|nnn".

First part is the name of the library file.

Second part is the name of the function within that library.

Third part is the result type of the function, which can be either "v" (void) for no result or "n" (number) for a 32 bit value (DWORD, Pointer etc.).

Fourth part describes the types of each function parameter, either a single "v" (void) for no parameters or a single character for each parameter. Like in third part, a "n" (number) marks any 32 bit parameter (DWORD, LPSTR, INT, WORD).

There's also (very limited) support for callback-functions, where the callback-function-parameter has to be set to either "1" (cb receives 1 parameter) or "2" (cb receives 2 parameters). See commented example "sub ApiEnumWindowsList()" in hw_windows.hsm for details on these.

See also: Windows API examples in hw_*.hsm and hw_demo.hsc.

Returns: Result of DLL function called

print( "Thread ID = ", DllCall( "kernel32.dll|GetCurrentThreadId|n|v" ) )

wait( <timeout>, <waitobj1>, <waitobj2>, ... )

'wait' behaves like an API Wait*-function invoked by DllCall, but also returns if the script is stopped for any reason.

Returns: -2=Failed (check DllLastError for reason), -1=Timeout, 0=Script-Stop, 1=WaitableObject1, 2=WaitableObject2, ..., 9=WaitableObject9

$res = wait( 0, $Event )

[www.elbiah.de Hamster Playground Documentation]