| 1 |
<html lang="en"> |
|---|
| 2 |
<head> |
|---|
| 3 |
<title>DerelictUtil</title> |
|---|
| 4 |
<link rel="stylesheet" type="text/css" href="styles.css"> |
|---|
| 5 |
</head> |
|---|
| 6 |
<body> |
|---|
| 7 |
<hr> |
|---|
| 8 |
<hr> |
|---|
| 9 |
<h2 align="center">DerelictUtil</h2> |
|---|
| 10 |
<hr> |
|---|
| 11 |
<hr> |
|---|
| 12 |
<h3>Introduction</h3> |
|---|
| 13 |
DerelictUtil contains four modules. Of these, two are intended exlusively for |
|---|
| 14 |
internal use. Of the other two, one, <tt>derelict.util.exception</tt>, provides |
|---|
| 15 |
optional functionality that the client can use to make an application as robust |
|---|
| 16 |
as possible. The other, <tt>derelict.util.loader</tt> is primarily intended for |
|---|
| 17 |
internal use but may be useful for anyone needing to manually load a shared |
|---|
| 18 |
library in their application. Regardless of whether or not the client imports |
|---|
| 19 |
any modules from DerelictUtil, the other Derelict packages all have an implicit |
|---|
| 20 |
dependency upon DerelictUtil. As such, when building an application that uses |
|---|
| 21 |
Derelict, the DerelictUtil library must be linked to the application. |
|---|
| 22 |
|
|---|
| 23 |
<h3>The Exception Module</h3> |
|---|
| 24 |
This is the module that will be of most interest to clients. To use this module, |
|---|
| 25 |
you must import <tt>derelict.util.exception</tt>. It defines three exception types |
|---|
| 26 |
that can be thrown when a shared library fails to load, and also defines the |
|---|
| 27 |
interface for <a href="selective.html">selective symbol loading</a>. |
|---|
| 28 |
|
|---|
| 29 |
<p><hr></p><p> |
|---|
| 30 |
<tt>SharedLibLoadException</tt><br> |
|---|
| 31 |
This exception is thrown when the shared library cannot be loaded. This indicates |
|---|
| 32 |
that the library is not on the user's system, is not on the path, or perhaps has |
|---|
| 33 |
a name that is different than expected. In otherwords, no library could be found |
|---|
| 34 |
that matches the name returned by the <tt>sharedLibName</tt> property of this |
|---|
| 35 |
exception.</p> |
|---|
| 36 |
|
|---|
| 37 |
<p><tt>SharedLibProcLoadException</tt><br> |
|---|
| 38 |
This exception is thrown when a symbol cannot be loaded from a shared library. |
|---|
| 39 |
This might indicate that the library is corrupt, or that it is a different version |
|---|
| 40 |
than expected. In other words, the library exists on the system, but |
|---|
| 41 |
no symbol that matches the name returned by the <tt>procName</tt> property of |
|---|
| 42 |
this exception could be found. In some cases, it may be desirable to prevent this |
|---|
| 43 |
exception from being thrown. You can learn how by reading about |
|---|
| 44 |
<a href="selective.html">Selective Symbol Loading</a>.</p> |
|---|
| 45 |
|
|---|
| 46 |
<p><tt>InvalidSharedLibHandleException</tt><br> |
|---|
| 47 |
This exception might be thrown when attempting to use a handle to a shared library |
|---|
| 48 |
that has already been unloaded. The name of the unloaded library can be retrieved |
|---|
| 49 |
by accessing the <tt>sharedLibName</tt> property of this exception. |
|---|
| 50 |
|
|---|
| 51 |
<p><tt>void Derelict_SetMissingProcCallback(MissingProcCallback callback)</tt></br> |
|---|
| 52 |
<tt><b>[typedef bool function(char[] libName, char[] procName) MissingProcCallback]</b></tt><br> |
|---|
| 53 |
This function allows the client to set a callback that will be called when a |
|---|
| 54 |
symbol cannot be found in a shared library. The name of the library will be passed |
|---|
| 55 |
to the callback in the <tt>libName</tt> parameter and the name of the missing |
|---|
| 56 |
symbol in the <tt>procName</tt> parameter. The client can use these parameters |
|---|
| 57 |
to determine if Derelict should continue loading the shared library. If so, then |
|---|
| 58 |
the callback should return true. If Derelict should abort loading and throw an exception, |
|---|
| 59 |
the callback should return false. Note that the callback must be set before loading |
|---|
| 60 |
the library(ies) you are interested in. You can read more about this feature in |
|---|
| 61 |
the <a href="selective.html">Selective Symbol Loading</a> documentation.</p> |
|---|
| 62 |
<p><hr></p> |
|---|
| 63 |
|
|---|
| 64 |
<h3>The Loader Module</h3> |
|---|
| 65 |
<tt>derelict.util.loader</tt> provides a common interface for Derelict packages |
|---|
| 66 |
to load shared libraries. You should generally only use this module if you are |
|---|
| 67 |
creating a new package for inclusion in Derelict. However, it is useful if you |
|---|
| 68 |
need to load other shared libraries in your Derelict application. Also, |
|---|
| 69 |
DerelictUtil can be used as a standalone package, perhaps as a replacement for |
|---|
| 70 |
<tt>std.loader</tt>. |
|---|
| 71 |
|
|---|
| 72 |
<p><hr></p><p> |
|---|
| 73 |
<tt>SharedLib Derelict_LoadSharedLib(char[] libName)</tt><br> |
|---|
| 74 |
Opens and returns a shared library handle of type <tt>SharedLib</tt>. This handle |
|---|
| 75 |
is used by other functions in this module to manipulate the shared library. If |
|---|
| 76 |
the library cannot be loaded, a <tt>SharedLibLoadException</tt> is thrown.</p> |
|---|
| 77 |
|
|---|
| 78 |
<p><tt>SharedLib Derelict_LoadSharedLib(char[][] libNames)</tt><br> |
|---|
| 79 |
Given an array of shared library names, returns a handle to the first shared |
|---|
| 80 |
library successfully loaded. This is intended for use on platforms where a single |
|---|
| 81 |
library may have multiple possible names, such as Linux. The function iterates |
|---|
| 82 |
the array until a successful load. If none of the names result in a successful |
|---|
| 83 |
load, an exception is thrown for the last library name.</p> |
|---|
| 84 |
|
|---|
| 85 |
<p><tt>void* Derelict_GetProc(SharedLib lib, char[] procName)</tt><br> |
|---|
| 86 |
Given a handle to a shared library and the name of a symbol, this function loads |
|---|
| 87 |
the symbol from the shared library into memory and returns a pointer to it. This |
|---|
| 88 |
can be used to load exported functions and variables from a shared library. If |
|---|
| 89 |
the symbol cannot be found, this function first checks if a <tt>MissingProcCallback</tt> |
|---|
| 90 |
has been set and, if so, calls it. Otherwise a <tt>SharedLibProcLoadException</tt> |
|---|
| 91 |
is thrown. If the shared library referenced by the handle has already been |
|---|
| 92 |
unloaded, an <tt>InvalidSharedLibHandleException</tt> is thrown.</p> |
|---|
| 93 |
|
|---|
| 94 |
<p><tt>void Derelict_UnloadSharedLib(SharedLib lib)</tt><br> |
|---|
| 95 |
Unloads a shared library from memory. The library handle will no longer be valid. |
|---|
| 96 |
Attempts to use it again could cause an <tt>InvalidSharedLibHandleException</tt> to |
|---|
| 97 |
be thrown. However, if an invalid shared library handle is passed to this function, |
|---|
| 98 |
no exception is thrown and the function is a no-op. |
|---|
| 99 |
</body> |
|---|
| 100 |
</html> |
|---|
