Using DLLs in RAD Studio (C++)

From RAD Studio
Jump to: navigation, search

Go Up to Creating Packages and DLLs

RAD Studio provides support for Dynamic-Link Libraries for both Windows (DLL files) and macOS (dylib files).

In order to create a dynamic library select File > New > Other. From the C++Builder Projects node, select Dynamic-link Library.

The following code will be automatically generated in the main file of the newly created project:

//   Important note about DLL memory management when your DLL uses the
//   static version of the RunTime Library:
//   If your DLL exports any functions that pass String objects (or structs/
//   classes containing nested Strings) as parameter or function results,
//   you will need to add the library MEMMGR.LIB to both the DLL project and
//   any other projects that use the DLL.  You will also need to use MEMMGR.LIB
//   if any other projects which use the DLL will be performing new or delete
//   operations on any non-TObject-derived classes which are exported from the
//   DLL. Adding MEMMGR.LIB to your project will change the DLL and its calling
//   EXE's to use the BORLNDMM.DLL as their memory manager.  In these cases,
//   the file BORLNDMM.DLL should be deployed along with your DLL.
//   To avoid using BORLNDMM.DLL, pass string information using "char *" or
//   ShortString parameters.
//   If your DLL uses the dynamic version of the RTL, you do not need to
//   explicitly add MEMMGR.LIB as this will be done implicitly for you

#pragma hdrstop
#pragma argsused

extern "C" int _libmain(unsigned long reason)
	return 1;

The _libmain function is the entry point into the dynamic library. When the dynamic library is loaded, the _libmain function is called. This function usually holds initialization code.

Exporting functions

Functions defined in the dynamic library must be exported in order to be visible outside the dynamic library. This is the syntax for exporting functions:

extern "C" __declspec(dllexport) <return_type> <function_name>(<function_parameters>);

Importing functions

In order to use functions that are defined in a dynamic library, you must declare the function as an imported function, load the library in which the function is defined, then access the function. This is the syntax for importing functions:

extern "C" __declspec(dllimport) <return_type> <function_name>(<function_parameters>);
Note: The imported function prototype must match the function's definition inside the dynamic library.

Using a dynamic-link library

In order to invoke the functions exported by a dynamic-link library, the library must be loaded into memory, and the function must be declared as imported function. There are two ways of loading the library: statically (at link time) and dynamically (at run time).

Loading the library statically

When targeting Win32 and Win64, you can add the import library to your project from the code, by inserting the following pragma directive in a source file of the project:

#pragma comment(lib, "TestDLL")
Note: Notice the file name does not include the extension.

When targeting Win32, the procedure requires binding the dynamic-link library via an import library with the .lib extension. When targeting Win64, the procedure requires binding the dynamic-link library via an import library with the .a extension. The import library is automatically generated by the dynamic-link library project.

If you are targeting only WIN32 or only WIN64, instead of the pragma you may instead add the import library to your project by right-clicking the project in Projects Window, and selecting Add.... After the import library has been added to your project, make sure that the functions have been imported (use the import syntax described above). Now these functions can be used in your project.

Note: Make sure that the dynamic-link library project has the Generate import library option set to True, so that the import library (.lib file) is generated when the project is built. For more information, see C++ Linker.

Loading the library dynamically

After the imported functions are declared, the dynamic library must be loaded at run time. This operation is done by using the LoadLibrary function. When the library is loaded into memory, use GetProcAddress function to retrieve a pointer to a certain function.

Here is a full example of using dynamic libraries in C++Builder Applications: Tutorial: Using Dynamic Linked Libraries in C++Builder Applications.

See Also