class NativeLibrary in Tinman.Core.System

Wraps a native library.

abstract class

NativeLibrary

extends

Initializable

Public / Attributes

IsLibraryLoaded

Has the native library been loaded successfully?

public property	IsLibraryLoaded { get }
type	bool
value		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.

Remarks:

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

LifecycleState

Returns the lifecycle state of this object.

public override property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Initializable.LifecycleState

Name

The human-readable name of this native library.

public property	Name { get }
type	string
value	[not-empty]	The library name.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

AddSearchPath

Extends the search path of the calling process for finding native dynamic link libraries.

public static method	AddSearchPath (Path path, bool platform = true)
params	path	[not-null]	The directory that contains native dynamic link libraries.
	platform		Extend search path with additional directories, based on path (see remarks)? Defaults to true.

Remarks:

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

• '{path}'
• '{path}/x32' (only if Is64Bit returns false and platform is true)
• '{path}/x64' (only if Is64Bit returns true and platform is true)

Native libraries should be put into the x32 resp. x64 subdirectories only if they have the same name (for example d3dcompiler_47.dll).

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Initialize

Initializes the object, if necessary

public method	Initialize ()
inherited	Initializable.Initialize

Remarks:

The Initialize method returns silently if the object is already in the state Initialized.

Protected / Constructors

NativeLibrary

Creates a new instance of NativeLibrary.

protected constructor	NativeLibrary (string name)
params	name	[not-empty]	Human-readable name for this native library.

Protected / Methods

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected override method	DisposeUnmanaged ()
overrides	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

DoInitialize

Performs initialization.

protected override method	DoInitialize ()
overrides	Initializable.DoInitialize

Remarks:

Overriding methods must call the DoInitialize method of their base class. The base call should be the first statement.

GetFunctionName

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

protected virtual method	GetFunctionName (string name, int32 cleanup)
type	string
params	name	[not-empty]	The function name.
	cleanup	[>=-1]	Number of bytes the callee is cleaning from the stack when running in 32-bit mode, or -1 if not specified.
returns		[not-empty]	The mangled function name.

See also:

GetFunctionPointer

GetFunctionPointer

Returns the pointer to an exported library function.

protected method	GetFunctionPointer (string functionName, bool required = true)
type	IntPtr
params	functionName	[not-empty]	The (mangled) function name.
	required		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			The function pointer or Zero if not found.

See also:

GetFunctionName

Initialized

This method is called when this object has been initialized completely, i.e. after the DoInitialize call and just before returning from Initialize.

[EmptyBody]
protected virtual method	Initialized ()
inherited	Initializable.Initialized

InitializeFunctionPointers

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

[EmptyBody]
protected virtual method	InitializeFunctionPointers ()

LibraryNames

Returns the name of the native library.

protected abstract method	LibraryNames (ICollector<string> names)
params	names		The names to use for loading this library (without filename extension), in the same order as the have been added to this list.

NotLoaded

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

protected method

NotLoaded ()

ThrowIfNotLoaded

Throws a TinmanException if IsLibraryLoaded returns false.

protected method

ThrowIfNotLoaded ()

Exceptions:

• TinmanException:
  If this library has not been loaded.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger

LogMessage_AddSearchPath

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

public static readonly field	LogMessage_AddSearchPath
type	ILogMessage

Remarks:

Label parameters:

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

See also:

LogSeverity.Common