Declare dll function

Syntax1 - declare single function

dll[-] dllfile [functype]Function [parameters]

 

Syntax2 - declare several functions from same dll

dll[-] dllfile
(tab)[functype]Function1 [parameters]
[(tab)[functype]Function2 [parameters]
...]

 

Use this syntax to declare different name (alias) than it is in dll:

dll dllfile [TrueName][functype]AnyName [parameters]

 

Use this syntax to find function by its ordinal number:

dll dllfile [ordinal][functype]AnyName [parameters]

 

Parameters

dllfile - dll filename or full path.

functype - return type. If omitted, the return value is undefined (void).

Function - name.

parameters - list of parameters.

 

Options:

- Delay-loading. Also use if you'll explicitly set address with operator & (read below).

 

Remarks

Declares a dll function.

 

By default, loads the dll file and finds the function when compiling (in exe - when starting the program). If the dll or function not found, generates error (in exe - ends process with an error message box). If dll- used (delay-loading), the dll and function will be loaded at run time, when need (called, address queried, etc); will be run-time error (see err) if the dll or function not found.

 

Some functions in dll have two versions: with 'A' and with 'W' suffix. The A version uses ANSI text. The W version uses Unicode UTF-16 text. You can omit 'A' suffix. If QM does not find the specified function, it searches for function with 'A' suffix. To support Unicode, use functions with 'W' suffix. Example.

dll user32 #SetWindowTextW hWnd @*lpString
dll user32 #GetWindowTextW hWnd @*lpString nMaxCount

SetWindowTextW _hwndqm @"unicode text"

str s; BSTR b
GetWindowTextW(_hwndqm b.alloc(300) 300)
s.ansi(b)
out s

 

Supported are __stdcall and __cdecl calling conventions. Don't need to specify it.

 

QM 2.2.1. Can be used optional parameters. They are declared by enclosing into [ ]. The default value is 0. User-defined types passed by value cannot be optional.

 

QM 2.2.1. To declare variable number of parameters, add ... at the end. When calling the function, argument types are not converted, therefore must match expected.

 

Allowed is function declaration without parameters. When calling such function, can be passed any number of arguments; argument types must match expected.

 

QM 2.4.1. You can declare parameters as reference instead of pointer. For example, POINT&p is the same as POINT*p. You can pass variables for reference and pointer parameters with or without operator &. For example, code POINT p; GetCursorPos(p) is the same as POINT p; GetCursorPos(&p).

 

Dll functions also can be declared in reference files and type libraries, which allows you to use them without declaring explicitly. Many declarations are in WINAPI and WINAPIV reference files. Usage example:

 

int hdc=WINAPI.CreateCompatibleDC(0)

 

Some Windows functions are declared by default, in the System\Declarations folder.

 

Usually you don't use full path in dllfile. Then the dll file should be in QM folder or in System32 folder. If used in exe, it should be in exe folder (however when creating exe it also must be in QM folder) or in System32 folder.

 

See also: Functions reference files type libraries declarations scope

 

Examples

dll user32 #SendMessage hWnd wMsg wParam lParam
dll user32 #FindWindow $lpClassName $lpWindowName
dll user32 #GetCursorPos POINT*lpPoint
dll msvcrt
	^pow ^x ^y
	[tolower]#ToLower c
	[795]#ToUpper c
dll "qm.exe" ^Round ^number [cDec] ;;cDec is optional
dll msvcrt #sprintf $buffer $format ... ;;2 or more parameters

 

Explicitly set function address with operator & (QM 2.4.1)

 

Syntax

&Function=address

 

Parameters

Function - function name previously declared with dll-. You can declare any names.

address - any function address. The function can be a dll function, a user-defined function, a function compiled at run time with __Tcc class (C compiler), etc.

 

Remarks

Sets a function address to be used to call a function previously declared with dll-.

 

When you declare a dll function with dll-, by default QM automatically loads the dll and finds function at run time when the function is actually used first time. But sometimes you may want to just declare the function, and at run time explicitly get function address (eg with GetProcAddress) and bind it to the declaration. Then use operator &. Also it allows you to declare any functions with dll-, not just dll functions. The purpose is to be able to call the function as easily and safely as any declared dll function. You could instead use call, but then calling is not so easy and safe, because function parameters are not defined.

 

In function declaration (dll-), dllfile can be "". Operator & does not use it anyway.

 

Examples

 declare a user-defined function as a dll function
dll- "" DlTest x ;;declare
&DlTest=&Function274 ;;set address
DlTest 100 ;;call

 declare a dll function
dll- "" #MessageBox2 hWnd $lpText $lpCaption uType
&MessageBox2=GetProcAddress(GetModuleHandle("user32") "MessageBoxA")
MessageBox2 0 "text" "caption" 0

 declare C functions compiled at run time
dll- ""
	test_add a b
	test_sub a b
__Tcc+ g_test_tcc
if !g_test_tcc.f
	int* p=g_test_tcc.Compile("" "add[]sub")
	&test_add=p[0]
	&test_sub=p[1]
out test_add(4 5)
out test_sub(4 5)
#ret
int add(int a, int b){return a+b;}
int sub(int a, int b){return a-b;}