Leonardo's blog

It's a well known fact that there are many excelent libraries written in C++, and we, as Object Pascal programmers can take advantage of them.

Many times, I have found in forums or mailing lists, questions such as "How can I translate XYZ library to ObjectPascal?", or "How can I use a C++ from Object Pascal?". Well, it's not necessary to translate a library from C++, we can use it just by creating a C wrapper around it.

Why I need to wrap the C++ library to C?

Because of name mangling, if you look inside the library (using TDump included in Delphi, or by using "nm" on linux), you'll get something like this:

000DB314  794 0319 _ZN12DcmAgeStringC1ERKS_
000DB274  795 031A _ZN12DcmAgeStringC2ERK6DcmTagm
000DB2F0  796 031B _ZN12DcmAgeStringC2ERKS_
000DB398  797 031C _ZN12DcmAgeStringD0Ev
000DB368  798 031D _ZN12DcmAgeStringD1Ev
000DB338  799 031E _ZN12DcmAgeStringD2Ev
000DB3C8  800 031F _ZN12DcmAgeStringaSERKS_

In the snippet from above, you can see names like _ZN12DcmAgeStringaSERKS. Those names may reffer to functions, methods, constants or variables we can call from Object Pascal by using GetProcAddress. The name in the example, is the "mangled" version of DcmAgeStringa.

If the C++ doesn't expose classes, but functions, you can call the functions just by passing the mangled name to GetProcAddress, but what about working with classes?.

There's no way to directly use a C++ class from Object Pascal, before using it is mandatory to create a "C" wrapper around it.

Let's start by defining a simple C++ class with only one method:

#include 
using namespace std;

class Test
{
  public:
    Test();
    void getHello(char * &AString); 
};

Test::Test()
{
}

void Test::getHello(char * &AString)
{
  const char * str = "Hello World from C++";
  strcpy(AString, str);
}

The class above, can be used with something like this:

int main(){
  Test * t  = new Test();
  char * str;
  t->getHello(str);
  cout << str;
}

It just gets change the value of the string "str" and print its contents.

As I mentioned earlier, there's no way to create an instance of a C++ class from Object Pascal, but there's a workaround, to create a "C" wrapper around it, and export it from the library.

Creating our first "C" wrapper around a C++ class

The idea is to create plain C functions in charge of creating an instance of the Test class, then return a pointer to that instance, then create another function that receive the pointer as param, and use its getHello function.

Here's the code:

#include 
#include 
using namespace std;

class Test
{
  public:
    Test();
    void getHello(char * &AString); 
};

Test::Test()
{
}

void Test::getHello(char * &AString)
{
  const char * str = "Hello World from C++";
  strcpy(AString, str);
}

extern "C"{
  void createTestInstance(void * &instance)
  {
    instance = new Test();
  }

  void doHello(void * instance, char * &AString)
  {
    Test * lInstance = (Test *) instance;
    lInstance->getHello(AString);
  }
  
  void deleteTestInstance(void  * instance)
  {
    delete (Test *)instance;
    instance = NULL;
  }
}

If you look at the snippet above, you can see I added code inside an extern "C" block, there will reside the exported functions. I added three functions to create an instance of our class, to use the method getHello, and one to delete the instance.

To create a dll from this code, just do this (I'm using Linux here, but you can use MinGW from Windows using the same command):

g++ -fPIC -shared test.cpp -o test.so

That command compiles our code and creates a shared object file, in Windows you must replace "-o test.so" with "-o test.dll".

Now you can check the contents of the library by using nm or tdump. The result should be something like this:

...
0000000000000c08 T _fini
00000000000008b0 T _init
0000000000000990 t call_gmon_start
0000000000201068 b completed.7424
0000000000000ac5 T createTestInstance
0000000000000b4e T deleteTestInstance
0000000000000b21 T doHello
0000000000201070 b dtor_idx.7426
0000000000000a30 t frame_dummy
                 U strcpy@@GLIBC_2.2.5
                 U strlen@@GLIBC_2.2.5
...

You can see, that createTestInstance, deleteTestInstance and doHello now aren't mangled as in the plain C++ library.

Now the fun part!

The last step of this journey, is to create an Object Pascal program that loads and use the shared library. The program should do this:

1) Load the library and store a reference to its handler.
2) Execute the method createTestInstance and store a reference to the pointer it returns.
3) Execute the method doHello by passing the pointer stored in point 2 as parameter.
4) Delete the instance by executing deleteTestInstance and passing the same pointer.

Here's the code:

program Test;

{$mode objfpc}{$H+}

uses
  dynlibs;

type
  TCreateInstance = procedure (var AInstance: Pointer); cdecl;
  TdoHello = procedure (AInstance: Pointer; var AString: PAnsiChar); cdecl;
  TDeleteInstance = procedure (AInstance: Pointer); cdecl;

var
  lCreateInstance: TCreateInstance;
  ldoHello: TdoHello;
  lDeleteInstance: TDeleteInstance; 
  lHandle: TLibHandle;
  lInstance: Pointer;
  lStr: PAnsiChar;

begin
  lHandle := LoadLibrary('./test.so');
  if lHandle <> NILHandle then
  begin
    writeln('Library loaded successfully!.');
    lInstance := nil;
    // First, create the instance
    Pointer(lCreateInstance) := GetProcAddress(lHandle, 'createTestInstance');
    if @lCreateInstance <> nil then
      lCreateInstance(lInstance);
    // Second, use the instance
    Pointer(ldoHello) := GetProcAddress(lHandle, 'doHello');
    if @ldoHello <> nil then
    begin
      GetMem(lStr, 255);
      ldoHello(lInstance, lStr);
      writeln(lStr);
      FreeMem(lStr);
    end;
    // Third, delete the instance and unload the library
    Pointer(lDeleteInstance) := GetProcAddress(lHandle, 'deleteTestInstance');
    if @lDeleteInstance <> nil then
    begin
      lDeleteInstance(lInstance);
      UnloadLibrary(lHandle);
    end;
    writeln('Done.');
  end
  else
    writeln('Cannot load library.');
end.

That's all. Now you can use all your loved C++ libraries from Object Pascal!.