Unstandard

Bitbucket Page

Unstandard

Stuff for working with dynamic libraries.

License
Boost License 1.0.
Authors
Denis Shelomovskij

alias  DynamicLibHandle = void*;

Native dynamic library handle.

It is HMODULE on Windows and void* on Posix.

struct  DynamicLib;

This struct encapsulates functionality for working with dynamic libraries.

This struct is neither default constructable nor copyable. Pass it by ref to functions or use std.typecons.RefCounted.

pure nothrow @safe this(DynamicLibHandle handle, in bool own);

Construct a DynamicLib from a manually obtained DynamicLibHandle.

Parameters
DynamicLibHandle handle A valid DynamicLibHandle.
bool own Whether or not to close handle on destruction.
Preconditions:
handle is a valid DynamicLibHandle.

@trusted this(in char[] name, in bool search = false);

Construct a DynamicLib with the library name.

Parameters
char[] name A name of the dynamic library to open.
bool search Whether system will search for dynamic library. If false name is expected to be a path for the dynamic library file.
Preconditions:
!name.empty
Throws
Exception on opening error.
Note:
Be careful with search = true as it can lead to security vulnerability if used careless.

const pure nothrow @property @safe bool  associated();

Returns whether this is associated with a dynamic library handle. It is asserted that no member functions are called for an unassociated DynamicLib struct.

Examples
assert(!DynamicLib.init.associated);
auto h = DynamicLib.init.handle; // assertion failure

const pure nothrow @property @safe bool  ownHandle();

Returns whether handle of the associated dynamic library will be closed on destruction.

inout pure nothrow @property @safe inout(DynamicLibHandle)  handle();

Gets native handle of the associated dynamic library.

@trusted void*  opBinaryRight(string op : "in")(in char[] symbolName);

Returns the address of a symbol named symbolName or null if it is not found.

Note:
null return doesn't mean the symbol is not found as the address of a symbol may be null.

@trusted void*  opIndex(in char[] symbolName);

Returns the address of a symbol named symbolName.

Throws
Exception if the symbol is not found or has null address.

ref @system auto  call(T)(in char[] functionName, auto ref ParameterTypeTuple!T params);

Calls the function named functionName from this dynamic library.

Throws
Exception if the function is not found or has null address.
Examples
extern(C) alias F = int function(int) nothrow;
const int res = dynLib.call!F("f", 5);

@system T  var(T)(in char[] varName);

Returns the reference to the variable named varName from this dynamic library.

Throws
Exception if the variable is not found or has null address.
Examples
dynLib.var!int("i") = 3;
int* j = &dynLib.var!int("j")

@trusted void  close();

Closes native handle and makes the struct unassociated.

Throws
Exception on closing error.

@system bool  tryBind(alias sym)(auto ref DynamicLib lib, in char[] symbolName = sym.stringof);

Tries to set sym to point to a symbol named symbolName in dynamic library lib.

Examples
extern(C) alias F = void function(int) nothrow;
F f;
if(dynLib.tryBind!f())
	f(5);

@system void  bind(alias sym)(auto ref DynamicLib lib, in char[] symbolName = sym.stringof) if (!is(sym));

Sets sym to point to a symbol named symbolName in dynamic library lib.

Throws
Exception if the symbol is not found or has null address.
Examples
extern(C) alias F = void function(int) nothrow;
F f;
dynLib.bind!f();
f(5);

@system T  bind(T)(auto ref DynamicLib lib) if (is(T == struct));

Returns an instance of struct T with all fields pointing to corresponding symbols in dynamic library lib.

Throws
Exception if any corresponding symbol is not found or has null address.
Examples
version(Windows):

struct Kernel32
{
extern(Windows) nothrow:
	alias DWORD = uint;
	DWORD function() GetVersion, GetTickCount;
}
const kernel32 = DynamicLib("Kernel32.dll", true).bind!Kernel32();

import std.stdio;
writefln("GetVersion: %X", kernel32.GetVersion());
writefln("GetTickCount: %s", kernel32.GetTickCount());