xHarbour Reference Documentation > Function Reference

DllPrepareCall()

Creates a call template for an external DLL function.

Syntax

DllPrepareCall( <cDllFile>|<nDllHandle>, ;
               [<nCallingConvention>]  , ;
               <cFuncName>|<nOrdinal>    ) --> pCallTemplate

Arguments

<cDllFile>

A character string holding the name of the DLL file where the function is located. This is an external DLL, not created by xHarbour. If a character string is passed for <cDllFile>, it must contain complete path information, unless the file is located in the current directory, or in the list of directories held in the SET PATH environment variable of the operating system.

<nDllHandle>

Alternatively, the first parameter can be a numeric DLL handle as returned by function LoadLibrary().

<nCallingConvention>

The calling convention to use for the DLL function can optionally be specified. Constants are available for this parameter.

Calling conventions

Constant	Value	Description
DC_CALL_CDECL	0x0010	C calling convention (__cdecl)
DC_CALL_STD *)	0x0020	Standard convention for WinAPI (__stdcall)
*) default

<cFuncName>

This is a character string holding the symbolic name of the function to call. Unlike regular xHarbour functions, this function name is case sensitive.

<nOrdinal>

Instead of the symbolic function name, the numeric ordinal position of the function inside the DLL file can be passed. This is, however, not recommended, since ordinal positions of functions may change between DLL versions.

Return

The function returns a pointer to the call template for the specified DLL function.

Description

Function DllPrepareCall() prepares a call template which contains all information required to invoke a DLL function, except for the parameters to pass. The call template is then passed along with the parameters to function DllExecuteCall() which executes the DLL function (see DllExecuteCall() for a complete example).

The preparation of a call template is advantageous when a DLL function must be called many times, since the information assembled in the call template is the same for multiple DLL function calls. If a DLL function needs to be called only once or a few times, it can be executed via DllCall() since the extra overhead of the call template preparation is not justified in such case.

Important:  the call template must not be changed.

Info

See also:	DllExecuteCall(), FreeLibrary(), GetProcAddress(), GetLastError(), LoadLibrary()
Category:	DLL functions , xHarbour extensions
Source:	rtl\dllcall.c
LIB:	xhb.lib
DLL:	xhbdll.dll