NativeLibrary

Description

abstract class Tinman.Core.System.NativeLibrary

Derived from

Disposable abstract

Extended by

GLBase abstract
MG sealed

Wraps a native library.

When trying to use a native library that has not been loaded, a FailedAssertionException will be thrown (see AssertLoaded).

See also

NativeLibrary.Initialize

Public / Methods

Add​Search​Path

public static method AddSearchPath → (3)

path in : Path

[not-null]
The directory that contains native dynamic link libraries.

platform opt : bool = true

Extend search path with additional directories, based on path in (see remarks)?

remove opt : PredicateDelegate<Path> = null

Optional predicate to use for deciding whether to remove existing search path entries. If null, no existing entries will be removed.

Extends the search path of the calling process for finding native dynamic link libraries, if allowed by TinmanCorePrivileges.EnvironmentVariableGet and TinmanCorePrivileges.EnvironmentVariableSet.

The search path is augmented by appending the following directories (only if they exist):

  • '{path in}'

  • '{path in}/x32' (only if LowLevel.Is64Bit returns false and platform opt is true)

  • '{path in}/x64' (only if LowLevel.Is64Bit returns true and platform opt is true)

Native libraries should be put into the x32 resp. x64 subdirectories only if they have the same name.

IOException

If an I/O error has occurred while validating path in.

Initialize

public method Initialize → ()

returns → bool

true if the object has been initialized,
false if the object has already been initialized before.

Initializes the object, if necessary.

During initialization, function pointers are retrieved from the loaded native library.

See also

TinmanCorePrivileges.LibraryLoad

Reload

public virtual method Reload → ()

Reloads the function pointers from the loaded native library.

For some native libraries, the result of function pointer loading may depend on some state outside of the scope of this NativeLibrary object (for example, the current OpenGL render context of the calling thread). In these cases, the Reload method may be used to reload all function pointers.

Public / Attributes

Is​Library​Loaded

public attribute IsLibraryLoaded → (get)

value : bool

true if the native library has been loaded successfully during Initialize,
false if the native library has failed to load or Initialize has not been called yet or if IDisposable.Dispose has already been called.

Has the native library been loaded successfully?

The native library is loaded when the Initialize method is called.

Name

public attribute Name → (get)

value : string

[not-empty]
The library name.

The human-readable name of this native library.

Protected / Constructors

Native​Library

protected constructor NativeLibrary → (1)

name in : string

[not-empty]
Human-readable name for this native library.

Creates a new instance of NativeLibrary.

Protected / Methods

Assert​Loaded

protected method AssertLoaded → (1)

source in : string

The error source tag.

Asserts that IsLibraryLoaded returns true.

Get​Function​Name

protected virtual method GetFunctionName → (2)

name in : string

[not-empty]
The function name.

cleanup in : int32

[>=-1]
Number of bytes the callee is cleaning from the stack when running in 32-bit mode, or -1 if not specified.

returns → string

The mangled function name.

Returns the mangled function name for lookup in the native library (only for stdcall on 32-bit).

See also

NativeLibrary.GetFunctionPointer

Get​Function​Pointer

protected method GetFunctionPointer → (2)

functionName in : string

[not-empty]
The (mangled) function name.

required opt : bool = true

true if the function is required, false if it is optional. If one or more required functions have not been found, the IsLibraryLoaded property will return false.

returns → IntPtr

The function pointer or IntPtr.Zero if not found.

Returns the pointer to an exported library function.

This method calls LookupFunctionPointer to find the pointer of the function in the loaded native library.

See also

NativeLibrary.GetFunctionName

Initialize​Function​Pointers

[EmptyBody]
protected virtual method InitializeFunctionPointers → ()

Initializes all function pointers that are required by the native library wrapper, by calling the GetFunctionPointer method.

Library​Names

protected abstract method LibraryNames → (1)

names in : ICollector<string>

The names to use for loading this library (without filename extension), in the same order as the have been added to this list.

Returns the name of the native library.

Lookup​Function​Pointer

protected virtual method LookupFunctionPointer → (1)

functionName in : string

The function name.

returns → IntPtr

The function pointer or IntPtr.Zero

Performs a lookup for the given function in the loaded native library.

Not​Loaded

protected method NotLoaded → ()

Marks this NativeLibrary instance as not loaded, i.e. the IsLibraryLoaded will return false.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.

Log​Message_​Add​Search​Path

public static readonly attribute LogMessage_AddSearchPath → (ILogMessage)

A directory path has been added (if necessary) to the search PATH of this process.

Label parameters:

#0:
Canonical path of directory that has been added to search path.

See also

LogVerbosity.Common