xHarbour Reference Documentation > Function Reference

LoadLibrary()

Loads an external DLL file into memory.

Syntax

LoadLibrary( <cDLLFile> ) --> nDllHandle

Arguments

<cDLLFile>

This is a character string holding the name of the DLL file to load into memory. 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.

Return

The function returns a numeric DLL handle > 0. If the DLL file cannot be loaded, or does not exist, the return value is zero.

Description

The LoadLibrary() function loads a DLL file at runtime of an xHarbour application into memory that is not created with xHarbour. Functions residing in this DLL can then be invoked via DllCall() by passing the returned DLL handle.

If the DLL is already in use by other applications, LoadLibrary() does not load the DLL a second time, but increments the load counter of the DLL. This signals the operating system that the xHarbour application requires the DLL in addition to other applications.

When the DLL is no longer required, the DLL handle should be freed with FreeLibrary().

Note:  function LibLoad() is available to load a DLL cerated with xHarbour.

Info

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

Example

// The example shows a recomended use of LoadLibrary() when DLL handles
// are required during the entire lifetime of an xHarbour application.
// The DLL is loaded in an INIT PROCEDURE and the DLL handle is available
// via a GLOBAL variable. This way, the DLL handle can be used in different
// API wrappers that invoke WinAPI functions within the same DLL.
// The example implements two wrappers for converting normal Ansi strings
// to wide character string (Unicode) and vice versa.

   #define DC_CALL_STD            0x0020

   GLOBAL gKernel32DLL

   INIT PROCEDURE InitDlls
      gKernel32DLL := LoadLibrary( "Kernel32.dll" )
   RETURN

   EXIT PROCEDURE FreeDlls
      FreeLibrary( gKernel32DLL )
   RETURN


   PROCEDURE Main
      LOCAL cString, cWideString

      cString     := "Hello World"
      cWideString := AnsiToWide( cString )

      ? Len( cString ), cString
      ? Len( cWideString ), cWideString

      ? WideToAnsi( cWideString )
   RETURN


   FUNCTION AnsiToWide( cString )
      LOCAL nWideLen  := 2 * ( Len( cString ) )
      LOCAL cWideChar := Replicate( Chr(0), nWideLen )
      LOCAL nRet

      nRet := ;
        DllCall( gKernel32DLL          , ;
                 DC_CALL_STD           , ;
                 "MultiByteToWideChar" , ;
                 0                     , ;
                 0                     , ;
                 cString               , ;
                 -1                    , ;
                @cWideChar             , ;
                 nWideLen                )
   RETURN cWideChar


   FUNCTION WideToAnsi( cWideChar )
      LOCAL nLen    := Int( Len( cWideChar ) / 2 )
      LOCAL cString := Replicate( Chr(0), nLen )
      LOCAL nRet

      nRet := ;
        DllCall( gKernel32DLL          , ;
                 DC_CALL_STD           , ;
                 "WideCharToMultiByte" , ;
                 0                     , ;
                 0                     , ;
                 cWideChar             , ;
                 -1                    , ;
                @cstring               , ;
                 nLen                  , ;
                 0                     , ;
                 0                       )
   RETURN cString