Tutorial: Loading library and binding functions

2004/08/17, Andreas Jönsson (updated 2007/02/25)

Loading the dynamic library

-- start Windows specific --

Include windows header and declare the global variables.

// windows.h has everything we need for now
#include <windows.h>

// global variable for holding the library handle
HMODULE dll = 0;

Inside some initialization function you need to load the library module.

// load the library
dll = LoadLibrary("angelscript.dll");
if( dll == 0 )
{
  // Failed to load the library, probably not installed or in the wrong location
  ... some error handling
}

-- end Windows specific --

Binding the global functions

Declare some function pointers that will be used to call the library functions.

// typedef the function interfaces
typedef asIScriptEngine  * AS_API t_asCreateScriptEngine(int);
typedef const char       * AS_API t_asGetLibraryVersion();
typedef asIScriptContext * AS_API t_asGetActiveContext();

// declare the function pointers
t_asCreateScriptEngine *asCreateScriptEngine = 0;
t_asGetLibraryVersion  *asGetLibraryVersion  = 0;
... the same for the bstr functions if you intend to use them

When you include angelscript.h don't forget to define the key ANGELSCRIPT_DLL_MANUAL_IMPORT so that the function declarations will not compete with yours.

Inside some initialization function you acquire the address for the functions you intend to use.

-- start Windows specific --

// bind the functions
asCreateScriptEngine = (t_asCreateScriptEngine*)GetProcAddress(dll, "asCreateScriptEngine");
if( asCreateScriptEngine == 0 )
{
  // Failed to find the function address,
  // probably because of wrong dll version
  ... some error handling
}

... the same for the other functions

-- end Windows specific --

Free the loaded library

Freeing the library unloads all the code, and it would be an error to try to call any of the library functions after that.

-- start Windows specific --

if( dll )
{
  FreeLibrary(dll);
  dll = 0;
}

-- end Windows specific --

Sample header file lib.h

#ifndef LIB_H
#define LIB_H

#define ANGELSCRIPT_DLL_MANUAL_IMPORT
#include "angelscript.h"

int  LoadScriptLibrary();
void UnloadScriptLibrary();

// typedef the function interfaces
typedef asIScriptEngine  * AS_API t_asCreateScriptEngine(int);
typedef const char       * AS_API t_asGetLibraryVersion();
typedef asIScriptContext * AS_API t_asGetActiveContext();

extern t_asCreateScriptEngine *asCreateScriptEngine;
extern t_asGetLibraryVersion  *asGetLibraryVersion;
extern t_asGetActiveContext   *asGetActiveContext;

#endif

Sample program file lib.cpp

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

HMODULE dll = 0;

// declare the function pointers
t_asCreateScriptEngine *asCreateScriptEngine = 0;
t_asGetLibraryVersion  *asGetLibraryVersion  = 0;
t_asGetActiveContext   *asGetActiveContext   = 0;

int LoadScriptLibrary()
{
  // Load library
  dll = LoadLibrary("angelscript.dll");
  if( dll == 0 )
  {
    printf("Failed to load angelscript.dll\n");
    return -1;
  }

  // bind the functions
  asCreateScriptEngine = (t_asCreateScriptEngine*)GetProcAddress(dll, "asCreateScriptEngine");
  asGetLibraryVersion  = (t_asGetLibraryVersion*)GetProcAddress(dll, "asGetLibraryVersion");
  asGetActiveContext   = (t_asGetActiveContext*)GetProcAddress(dll, "asGetActiveContext");

  if( asCreateScriptEngine == 0 || asGetLibraryVersion == 0 ||
      asBStrAlloc == 0 || asBStrFree == 0 || asBStrLength == 0 ||
      asGetActiveContext == 0 )
  {
    printf("Failed to locate a function in angelscript.dll\n");
    printf("- Expecting library version %s", ANGELSCRIPT_VERSION_STRING);
    if( asGetLibraryVersion == 0 )
      printf(", couldn't determine library version\n");
    else
      printf(", found %s\n", asGetLibraryVersion());
    return -1;
  }

  // Successfully loaded the library and bound the functions
  return 0;
}

void UnloadScriptLibrary()
{
  if( dll )
  {
    FreeLibrary(dll);
    dll = 0;
  }

  asCreateScriptEngine = 0;
  asGetLibraryVersion  = 0;
  asGetActiveContext   = 0;
}