Partager via

DECLARE - DLL Command

  • Article

Registers a function in an external shared library. Libraries are 32-bit dynamic link library (.DLL) files.

DECLARE [cFunctionType] FunctionName IN LibraryName [AS AliasName]
   [cParamType1 [@] ParamName1, cParamType2 [@] ParamName2, ...]

Parameters

  • cFunctionType
    Indicates the data type of the return value from the shared library, if any. If the function does not return a value, omit cFunctionType.

    cFunctionType can assume the following values:

    cFunctionType Description
    SHORT 16-bit integer
    INTEGER 32-bit integer
    SINGLE 32-bit floating point
    DOUBLE 64-bit floating point
    LONG 32-bit long integer
    STRING Character string
    OBJECT IDispatch object type

  • FunctionName
    Specifies the name of the shared library function to register in Visual FoxPro. Function names passed in this parameter are case-sensitive.

    Note   A DLL function name may not be the same as stated in the Win32 API manual. For example, the MessageBox function should be named MessageBoxA (for single-byte character), and MessageBoxW (for UNICODE). If Visual FoxPro cannot locate the DLL function you specify with FunctionName, the letter A is appended to the end of the function name and Visual FoxPro searches again for the function with the new name.

    If the shared library function you specify has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name, use the AS clause to assign an alias to the function when you register it, as described later in this topic.

    You can also use OBJECT as a return value, such as "DECLARE OBJECT myfunc IN some DLL ..." although COM conventionally doesn't have any APIs of this form. For example:

    DECLARE INTEGER AccessibleObjectFromWindow IN oleacc.dll ;
integer, integer, string , object @

  • IN LibraryName
    Specifies the name of the external shared library containing the function specified with FunctionName.

    If you specify WIN32API for the LibraryName, Visual FoxPro searches for the 32-bit Windows .dll function in Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll, and Advapi32.dll.

  • AS AliasName
    Specifies an alias name for a shared library function name that has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name. AliasName should not be a Visual FoxPro reserved word or the name of a shared library function already registered with Visual FoxPro.

    If you assign alias to the function, use the alias when calling the shared library function. AliasName is not case-sensitive.

  • cParameterType1 [@] ParamName1, cParameterType2 [@] ParamName2, ...
    Specifies the parameter types passed to the shared library function.

    cParameterType is required and specifies the data type of any parameters that the shared library function expects to have passed to it. cParameterType may be one of the following:

    cParameterType Description
    INTEGER 32-bit integer
    SINGLE 32-bit floating point
    DOUBLE 64-bit floating point
    LONG 32-bit long integer
    STRING Character string

    Visual FoxPro generates an error if the parameters are not of the type the shared library function expects. Null values can be passed as empty character strings.

    To pass a parameter by reference when you call the function, you must include @ after the parameter cParameterType in this command, and before the corresponding variable in the calling function. If you don't include @ in DECLARE, in the calling function, or in both, the parameter is passed by value. For information about shared library functions that require @ to pass parameters by reference, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on passing parameters to Windows DLLs).

    Note   The parameter names ParamName1, ParamName2, and so on, are optional, and are not used by Visual FoxPro or the shared library function. You can include them as a reminder of the names and types of parameters the function receives.

Remarks

Before you can call a shared library function from within Visual FoxPro, you must issue DECLARE with the name of the function, the name of the shared library containing the function, and the parameter types the function expects to receive.

For backward compatibility, Visual FoxPro allows calls to external API libraries using the SET LIBRARY command. (Using SET LIBRARY, you can access functions in Foxtools.fll.) However, using DECLARE is the preferred method to register shared library functions.

Though Visual FoxPro adds the OBJECT cFunctionType to this command primarily to support some ActiveX Accessibility API routines, you can use it generically with other Windows API routines.

For further information about calling shared library functions, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on calling DLLs).

Issue DISPLAY STATUS or LIST STATUS to display the names of registered functions. Issue CLEAR ALL or CLEAR DLLS to remove registered functions from memory.

Example

This example for Windows returns the window handle for Visual FoxPro or zero if you switch to another Windows application. When the WAIT window is displayed, you have 5 seconds to press ALT+TAB to switch to a different Windows application, or you can leave Visual FoxPro as the active application.

CLEAR
DECLARE INTEGER GetActiveWindow IN win32api
WAIT WINDOW "You can switch to another application now" TIMEOUT 5
? GetActiveWindow( )

See Also

CALL | CLEAR | DISPLAY DLLS | DISPLAY STATUS | LIST DLLS | LOAD | SET LIBRARY