Declare Command

Purpose

Declares a function in a DLL.

Syntax

Declare Function Name [CDecl] [Lib "libname"] [Alias "aliasname"] ([paramlist]) [As RetType = Long]

Declare Sub Name [CDecl] [Lib "libname"] [Alias "aliasname"] ([paramlist])

Declare SubA Name [CDecl] [Lib "libname"] ([paramlist])

Declare FunctionA Name [CDecl] [Lib "libname"] ([paramlist]) [As RetType = Long]

Declare LIB "libname"

Declare Function name BuiltIn "aliasname"

Description

The Declare command is used to declare references to external procedures or functions in a dynamic-link library. The Declare statement syntax has these parts:

Sub	Optional (either Sub or Function must appear). Indicates that the procedure doesn't return a value.
Function	Optional (either Sub or Function must appear). Indicates that the procedure returns a value that can be used in an expression.
CDecl	Optional. Required when the DLL function is a C/C++ function (see CCall). Default is "StdCall".
Name	Any valid procedure name. Note that DLL entry points are case sensitive.
Lib	Optional. Indicates that a DLL or code resource contains the procedure being declared. The Lib clause must be included or set before using Declare LIB "libname".
libname	Name of the DLL or code resource that contains the declared procedure.
Alias	Optional. Indicates that the procedure being called has another name in the DLL. This is useful when the external procedure name is the same as a keyword. You can also use Alias when a DLL procedure has the same name as a variable, constant, or any other procedure. Alias is also useful if any characters in the DLL procedure name aren't allowed by the DLL naming convention.
aliasname	Optional. Name of the procedure in the DLL or code resource. If the first character is not a number sign (#), aliasname is the name of the procedure's entry point in the DLL. If (#) is the first character, all characters that follow must indicate the ordinal number of the procedure's entry point.
paramlist	Optional. List of variables representing arguments that are passed to the procedure when it is called.
RetType	Optional. Data type of the value returned by a Function procedure; may be Byte, Boolean, Integer, Long (default), Large, Currency, Single, Double, Date, String (variable length only), or Variant, a user-defined type, or an object type.

The paramlist argument has the following syntax and parts:

[ByVal | ByRef] varname [As type = Long]

ByVal	Optional. Indicates that the argument is passed by value. Mandatory with dynamic String parameters, even when they must receive a return value. (ByRef would pass the address of the string descriptor.) A fixed String may be passed as ByRef.
ByRef	Indicates that the argument is passed by reference. ByRef is the default.
varname	Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions. The name is informational only.
type	Data type of the argument passed to the procedure; may be Byte, Boolean, Integer, Long (default), Currency, Single, Double, Date, String (variable length only), Object, Variant, a user-defined type, or an object type. When the 'As type' is omitted, Long is assumed.

The paramlist can not contain an array or a ParamArray declaration. A user-defined type is to be passed as ByRef. A String parameter has to be declared as ByVal.

SubA and FunctionA exclude the Alias clause; they are used to use the ANSI version of the declared DLL procedure. GFA-BASIC 32 generates the alias by itself by appending the 'A' to the DLL procedure name.

Using all default settings a DLL function can be declared as:

Declare LIB "version"

Declare FunctionA GetFileVersionInfo(ByVal Filename$, ByVal dwhandle, ByVal dwlen, ByVal lpData)

The BuiltIn variant doesn't seem to work.

Example

Declare Function GetUserName Lib "advapi32.dll" Alias "GetUserNameA" (ByVal lpBuffer As String, nSize As Long) As Long

Declare FunctionA GetUserName Lib "advapi32.dll" (ByVal lpBuffer As String, nSize As Long) As Long

Dim uname As String = String(30, 0)

GetUserName(uname, 30)

Print ZTrim(uname)

Remarks

A Declare'd DLL function is loaded when the function is used the first time. In the background the API functions LoadLibrary() and GetProcAddress() are invoked. A missing DLL isn't noticed before the function is called, therefore.

FreeDll explicitly releases a DLL from memory. The argument filename$ should be exactly the same as the DLL name specified in the Declare statement. Filename$ may contain a path.

The ~ (void operator) is no longer necessary to void the return value of a DLL function. In addition, DLL functions are no longer called using @@ or ^^, but simply by their name as if they were common functions.

Note ~ is still necessary for built-in API functions.

Built in API functions

GFA-BASIC 32 supports more than 1000 API functions, functions that can be used as any other GFA-BASIC 32 function. Only the standard API functions from User, Kernel and GDI are implemented, other not often used API functions like for instance WinSock functions are to be declared explicitly.

The type of the parameters of the built-in API-Functions is not checked upon compiling. Each parameter is assumed to be a 32-bit integer. A string can be passed to an API function, but is always copied to one of the 32 internal 1030-Byte buffer BEFORE the address of the buffer is passed. See String Data type.

A user defined Type (As type) is always passed by reference, so that its address is passed (automatically V: ).

Note - These rules don’t apply to DLL functions introduced with the Declare statement. Here GFA-BASIC 32 behaves like VB and the rules for calling such APIs must be respected.

Some API function names are already in use by GFA-BASIC 32 and are therefore renamed. GetObject() becomes GetGdiObject(), LoadCursor becomes LoadResCursor. Obsolete functions are not implemented, obviously.

The winapi32.inc.g32 contains the declarations that are not included in GFA-BASIC 32 itself. This file also describes VB to GB32 conversion tips. The often used "As Any" type clause in VB is used to declare a void pointer, a pointer to anything, a typeless parameter. The "As Any" type is not supported in GFA-BASIC 32 (with reasons) and should be replaced by ByVal … As Long. You then pass the address of the variable to the DLL function.