Castle Game Engine

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:

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

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;
Public property SymbolErrorBehaviour: TDynLibSymbolError read FSymbolError write FSymbolError default seRaise; deprecated 'use SymbolError';

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;
 
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.

Public property SymbolErrorBehaviour: TDynLibSymbolError read FSymbolError write FSymbolError default seRaise; deprecated 'use SymbolError';

Warning: this symbol is deprecated: use SymbolError

 
Generated by PasDoc 0.16.0.