Linking with the PathEngine DLL

DLL linkage is recommended on platforms where this is supported.
On platforms where DLL style linkage is not supported shared object or static linkage can be used.
(See Dynamic Linking on GCC Based Platforms and Linking with PathEngine Statically for details.)

If you are used to static linkage, or DLL linkage with lib files, then the DLL linkage used for PathEngine may seem a little strange initially, but arranging the linkage in this way has the advantages of encapsulating each SDK release in a single file and ensuring clean and robust operation against changing versions of the SDK.
Explicit LoadLibrary() calls are preferred over lib files because this enables run-time reloading of the DLL and ensures that the client application has full control of the DLL location and loading process.

The DLL linkage setup also makes it possible to do things like switching in an instrumented query logging wrapper dll without recompiling the main application.

Obtaining an entry point

Note that the following instructions only apply to the full version of the SDK.
'TestBed only' versions of the SDK do not contain a standalone version of the PathEngine dll.

Use the Win32 function LoadLibrary() (or LoadLibraryEx()) to load pathengine.dll, and then the Win32 function GetProcAddress() to obtain a pointer to PathEngine's entrypoint.

The entry point is defined as follows:

class iErrorHandler;
extern "C"
{
	__declspec(dllexport) iPathEngine* __stdcall DLLExport_GetIPathEngine(iErrorHandler* error_handler);
}
        

(See, also, DLLExport_GetIPathEngine.)

An error handler must therefore be set up before calling into this entry point.
See Error Handlers for details.

'SDKRoot/samples/shared/LoadPathEngine.cpp', provides working code for loading and calling into the PathEngine dll, as follows:

#include "loadpathengine.h"
#include <windows.h>
#include <stdio.h>

typedef iPathEngine* (__stdcall* tGetInterfaceFunction)(iErrorHandler*);

iPathEngine* LoadPathEngine(const char* fileName, iErrorHandler* handler)
{
    char buffer[500];
    DWORD errorValue;
    HINSTANCE hInstance;
    hInstance = LoadLibrary(fileName);
    if(!hInstance)
    {
        errorValue = GetLastError();
        MessageBox(NULL, fileName, "Error: failed calling LoadLibrary() for", MB_OK);
        sprintf(buffer, "%d", errorValue);
        MessageBox(NULL, buffer, "GetLastError()", MB_OK);
        return 0;
    }
    FARPROC procAddress;
    SetLastError(0);
    procAddress = GetProcAddress(hInstance, (LPCSTR)1);
    if(!procAddress)
    {
        errorValue = GetLastError();
        MessageBox(NULL, fileName, "Error: Failed to obtain the PathEngine root interface query method in", MB_OK);
        sprintf(buffer, "%d", errorValue);
        MessageBox(NULL, buffer, "GetLastError()", MB_OK);
        return 0;
    }

    tGetInterfaceFunction getInterfaceFunction = (tGetInterfaceFunction)procAddress;
    return getInterfaceFunction(handler);
}
	

Shared object linkage

On Linux, FreeBSD, and various other operating systems, the 'shared objects' mechanism provides run-time linkage that is similar in some ways to DLL linkage.