Function DllInfo() | Xbase++

Functions and Directives Functions and Directives

Retrieves runtime information about loaded DLLs.

DllInfo( [<cDllName>|<nDllHandle>], <nDllInfo> ) --> xValue

<cDllName> is a character string containing the file name of a DLL without path information. DllInfo() does not automatically load this DLL, so to obtain some information (e.g. DLL_INFO_FUNCLIST) the DLL needs to be loaded with DllLoad() in advance.

Instead of a DLL's file name, it's numeric handle can be passed as first parameter. The Dll handle is returned by the function DllLoad() or can be obtained by passing DLL_INFO_HANDLE as second parameter.

If the first parameter is omitted, DLL_INFO_LIST should be passed as the second parameter to obtain an array holding the numeric handles of all loaded DLLs which are created with Xbase++.

A #define constant listed in DLL.CH must be used as second parameter. It starts with the prefix DLL_INFO_* and determines the return value of the function (see below).

The return value of DllInfo() depends on the second parameter and yields various information about a DLL. The following #define constants can be used for <nDllInfo>:

<nDllInfo>	Return value
DLL_INFO_CLASSFUNCLIST	One dimensional array holding the symbols of exported class functions as character strings
DLL_INFO_FUNCLIST	One dimensional array holding the symbols of exported functions as character strings
DLL_INFO_HANDLE	Numeric handle of a DLL
DLL_INFO_IMPORTS	One dimensional array holding the handles of DLLs which are imported (linked statically) by the DLL as numerics
DLL_INFO_LIST	One dimensional array holding the numeric handles of loaded DLLs created with Xbase++
DLL_INFO_LOADED	.T. (true) if DLL is loaded, otherwise .F. (false)
DLL_INFO_NAME	Character string containing the DLL file name without path information
DLL_INFO_PATHNAME	Character string containing the full qualified file name of DLL
DLL_INFO_PREFIX	Function prefix of dynamically loaded DLL (see DllLoad(), second parameter)
DLL_INFO_TYPE	Numeric corresponding to DLL_TYPE_* constants:
	- DLL_TYPE_UNKNOWN = unknown type
	- DLL_TYPE_GENERAL = DLL not created with Xbase++
	- DLL_TYPE_XPP_STATIC = statically linked DLL
	- DLL_TYPE_XPP_DYNAMIC = DLL loaded with DllLoad()
	- DLL_TYPE_XPP_DYNAMIC_NOUNLOAD = DLL loaded by DllLoad() but cannot be unloaded
DLL_INFO_UNLOADABLE	.T. (true) if no function implemented in the DLL is currently being executed, otherwise .F. (false)
DLL_INFO_USAGELIST	One dimensional array holding the symbols of currently executed functions as character strings

The function is used to obtain various information about one or more DLL(s) created with Xbase++. This is especially useful when a program loads and unloads DLLs dynamically at runtime. The function can determine whether or not a DLL is loaded, the directory where the DLL is located or a list of exported functions contained in a DLL.

To obtain the handles of all loaded DLLs, the function is called without the first parameter and with DLL_INFO_LIST as the second parameter. The returned array contains the numeric handles of the DLLs currently being loaded. If a DLL handle is passed as first parameter along with DLL_INFO_LIST as the second parameter, DllInfo() includes into the array only the handles of this DLL and the DLLs loaded afterwards.

Determining exported functions of a DLL

// The example demonstrates a basic usage scenario for DllInfo(), 
// how to obtain the list of exported functions of a DLL and 
// how to call a function dynamically. 

#include "Dll.ch" 

PROCEDURE Main 
   LOCAL nDllHandle, aFunctions, cPrefix 

   // Make sure DLL is loaded 
   IF DllInfo( "Funcs.dll", DLL_INFO_LOADED ) 
      nDllHandle := DllInfo( "Funcs.dll", DLL_INFO_HANDLE ) 
   ELSE 
      nDllHandle := DllLoad( "Funcs.dll", "My" ) 
   ENDIF 

   // Retrieve function list and prefix 
   aFunctions := DllInfo( nDllHandle, DLL_INFO_FUNCLIST ) 
   cPrefix    := DllInfo( nDllHandle, DLL_INFO_PREFIX ) 

   IF AScan( aFunctions, "DOSOMETHING" ) > 0 
      // Call function dynamically 
      &( cPrefix + "DoSomething" )() 
   ENDIF 

   IF DllInfo( nDllHandle, DLL_INFO_UNLOADABLE ) 
      // Function has terminated. DLL can be unloaded. 
      DllUnload( nDllHandle ) 
   ENDIF 
RETURN

Function DllInfo() Foundation