API Reference

Class TDynLib

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleDynLib

Declaration

type TDynLib = class(TObject)

Description

Load functions from dynamic libraries.

This class allows to load functions from dynamic libraries (.dll on Windows, .so on most Unix platforms, .dylib on macOS and iOS).

Features:

  • The Load and Symbol functions by default do error checking (and raise necessary exceptions).

  • The field SymbolError allows to specify once for all subsequent Symbol calls what error checking we want. Default is to check errors and raise exceptions. There is also a very usefull value reWarnAndContinue: it allows you to run program once and see all symbols that are missing from dynamic library.

  • The interface of this is OS-independent and works for both FPC and Delphi.

  • macOS-specific extra feature: when loading a library, we also look for it inside the bundle. This allows to distribute macOS dynamic libraries (libxxx.dylib) simply inside the application bundle, in Contents/MacOS/ directory (alongside executable). This is useful to distribute libraries like libpng, libvorbisfile, libsteam_api with your application.

Typical usage: 

var
  ALLibrary: TDynLib = nil;
initialization
  ALLibrary := TDynLib.Load('libopenal.so.1');
  { ... some calls to ALLibrary.Symbol() ... }
finalization
  FreeAndNil(ALLibrary);
end.

It is important that ALLibrary is initialized to nil and that in finalization you use FreeAndNil. This allows you to exit gracefully if library does not exist on the system and Load will raise an exception: ALLibrary will stay then as nil.

Hierarchy

  • TObject
  • TDynLib

Overview

Methods

Public constructor Create(const AName: string; AHandle: TDynLibHandle);
Public destructor Destroy; override;
Public class function Load(const AName: string; RaiseExceptionOnError: boolean = true): TDynLib;
Public function Symbol(const SymbolName: PChar): Pointer;

Properties

Public property Name: string read FName;
Public property SymbolError: TDynLibSymbolError read FSymbolError write FSymbolError default seRaise;

Description

Methods

Public constructor Create(const AName: string; AHandle: TDynLibHandle);

Standard constructor, requires a valid TDynLibHandle already. Usually you will prefer to use Load method instead of directly calling this constructor.

Exceptions raised
ECheckFailed
if you supply invalid handle.
Public destructor Destroy; override;

This item has no description.

Public class function Load(const AName: string; RaiseExceptionOnError: boolean = true): TDynLib;

Link to a dynamic library specified by Name. Returns created TDynLib instance.

If the library is not found and RaiseExceptionOnError is False, Nil will be returned. If RaiseExceptionOnError is True then EDynLibError will be raised in case library is not found. So if RaiseExceptionOnError is True, Nil is never returned.

Note that the default situation prevents from unintentionally ignoring an error and that's good.

Exceptions raised
EDynLibError
If library not found and RaiseExceptionOnError is True.
Public function Symbol(const SymbolName: PChar): Pointer;

Return address of given symbol (function name etc.) from loaded dynamic library. If the symbol doesn't exist, then SymbolError says what happens:

  • seRaise (default), then EDynLibError will be raised.

  • seReturnNil, then return Nil (and continue, ignoring error).

  • seWarnAndReturnNil, then write warning (using WarningWrite) and return Nil (and continue, ignoring error).

    This is useful for debugging : you can easily open the library and after one run of the program you can see what symbols (that you requested) were missing from the library. This is useful when you have a library but you are not sure whether it is compatible and contains all the symbols that you want.

Exceptions raised
EDynLibError
If SymbolName doesn't exist and SymbolError is seRaise.

Properties

Public property Name: string read FName;

Name of the library to link to. In practice, file name of the *.so or *.dylib or *.dll file.

A precise strategy where this library is searched is specific to a platform, see the semantics of SysUtils.LoadLibrary (DynLibs for FPC) call on given OS.

Public property SymbolError: TDynLibSymbolError read FSymbolError write FSymbolError default seRaise;

What happens when Symbol fails.

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.