External_Function

See Also: Array Types, Structured Types, Field, Function, GetBuff, Put, Type

Purpose

To import an external function defined in a Dynamic Link Library (DLL) file. This command allows a DataFlex program to directly access functions of the Windows operating system and many of its extensions.

Syntax

The syntax is the same as the Function command, except that the parameter list is preceded by a case-sensitive name (as defined in the Dynamic Link Library) and the name of the DLL.

External_Function {function-name}  {lib-function}  {library-name} ;

                                   [{type} {param} ...]

                                   Returns {return-type}

Argument Explanation

What It Does

The External_Function command creates a global function that allows the DataFlex program to invoke an imported function of a DLL. The function is used like any other DataFlex function.

Example

The following example creates a global function named PlaySound that invokes the PlaySoundA function of the DLL, WinMM.DLL (a Multimedia DLL). Note that while it is a good idea to make the {function-name} parameter as close as possible to {lib-function}, it is not necessary.

External_Function PlaySound "PlaySoundA" WinMM.dll String sFileName Handle hmod DWORD fdwSound Returns Integer

PlaySound returns an integer and takes 3 parameters, a string, a handle, and a DWORD. This function may be invoked as follows:

// Define wave sound constants.

Enum_List 

    Define SND_SYNC SND_ASYNC SND_NODEFAULT

    Define SND_LOOP FOR 9

End_Enum_List

 

Function WaveLooping String sWaveFile Returns Integer

    Function_Return (PlaySound( sWaveFile, 0, SND_LOOP ))

End_Function

Example

This example wraps the Windows ShellExecute function. Read more about ShellExecute in the runprogram topic.

External_Function ShellExecute "ShellExecuteA" Shell32.Dll ;

    Handle hwnd String sOperation String sFile String sParameters String sDirectory Integer nShowCmd ;

        Returns VOID_TYPE

This function can then be called like this:

// this will perform an operation on a file with the application

// registered in the Windows Registry to print that type of file (via its extension)

// sOperation would be "print" (it could also be "edit" etc).

Procedure DoStartDocument GLOBAL String sOperation String sDocument

    Handle hInstance hWnd

    Get Window_Handle to hWnd

    Move (ShellExecute (hWnd, sOperation, (Trim (sDocument)), '', '', 1)) to hInstance

End_Procedure

Example

This example wraps the Windows GetLogicalDriveStringsA function, which allows enumeration of logical drives.

The string variable passed to the function must be pre-filled with null (ASCII zero) characters using ZeroString, then a pointer to the string variable passed using AddressOf.

External_Function WinAPI_GetLogicalDriveStrings "GetLogicalDriveStringsA" Kernel32.Dll Dword nBufferLength Pointer lpBuffer ;

    Returns Integer

Procedure Test
    String sLogicalDrivesString
    Integer iLength iPos

    ZeroString 255 to sLogicalDrivesString

    Move (WinAPI_GetLogicalDriveStrings (255, AddressOf (sLogicalDrivesString))) to iLength
    Showln "iLength: " iLength
    For iPos From 1 To iLength
       Showln (Mid (sLogicalDrivesString, 3, iPos))
       Move (iPos + 3) to iPos
    Loop
End_Procedure

If you want to use a string returned by a DLL function in it's entirety after it has been returned using AddressOf, for example sLogicalDrivesString in the sample code above, you must convert it from a C-Style string to a DataFlex string using CString.

Move (CString(sLogicalDrivesString)) to sLogicalDrivesString