File: CastleDynLib.TDynLib.html

package info (click to toggle)
castle-game-engine 5.2.0-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 185,428 kB
  • sloc: pascal: 260,781; cpp: 1,363; objc: 713; makefile: 537; xml: 496; sh: 480; php: 4
file content (216 lines) | stat: -rw-r--r-- 12,505 bytes parent folder | download 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<title>Castle Game Engine: CastleDynLib: Class TDynLib</title>
<meta name="generator" content="PasDoc 0.13.0">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="StyleSheet" type="text/css" href="pasdoc.css">
</head>
<body>
<table class="container"><tr><td class="navigation">
<h2>Castle Game Engine</h2><p><a href="introduction.html" class="navigation">Introduction</a></p><p><a href="AllUnits.html" class="navigation">Units</a></p><p><a href="ClassHierarchy.html" class="navigation">Class Hierarchy</a></p><p><a href="AllClasses.html" class="navigation">Classes, Interfaces, Objects and Records</a></p><p><a href="AllTypes.html" class="navigation">Types</a></p><p><a href="AllVariables.html" class="navigation">Variables</a></p><p><a href="AllConstants.html" class="navigation">Constants</a></p><p><a href="AllFunctions.html" class="navigation">Functions and Procedures</a></p><p><a href="AllIdentifiers.html" class="navigation">Identifiers</a></p></td><td class="content">
<a name="TDynLib"></a><h1 class="cio">Class TDynLib</h1>
<table class="sections wide_list">
<tr>
<td><a class="section" href="#PasDoc-Description">Description</a></td><td><a class="section" href="#PasDoc-Hierarchy">Hierarchy</a></td><td>Fields</td><td><a class="section" href="#PasDoc-Methods">Methods</a></td><td><a class="section" href="#PasDoc-Properties">Properties</a></td></tr></table>
<a name="PasDoc-Description"></a><h2 class="unit">Unit</h2>
<p class="unitlink">
<a  href="CastleDynLib.html">CastleDynLib</a></p>
<h2 class="declaration">Declaration</h2>
<p class="declaration">
<code>type TDynLib = class(TObject)</code></p>
<h2 class="description">Description</h2>
<p>
Load functions from dynamic libraries.

<p>I wrote my own class to handle dynamic libraries because:

<p></p>

<ul class="paragraph_spacing">
  <li><p>I wanted to have <a class="normal" href="CastleDynLib.TDynLib.html#Load">Load</a> and <a class="normal" href="CastleDynLib.TDynLib.html#Symbol">Symbol</a> functions that <i>by default do error checking</i> (and raise necessary exceptions).</p></li>
  <li><p>I wanted to have a field <a class="normal" href="CastleDynLib.TDynLib.html#SymbolErrorBehaviour">SymbolErrorBehaviour</a> &mdash; this lets me to specify, <i>once for all subsequent Symbol calls</i>, what error checking I want. Default is to check errors and raise exceptions. There is also a very usefull value reWarnAndContinue: it allows you to run program <i>once</i> and see all symbols that are missing from dynamic library.</p></li>
  <li><p>Also, the interface of this is OS-independent and works for both FPC and Delphi, so you can avoid ugly $ifdefs in your code.</p></li>
</ul>

<p>

<p>Typical usage:

<p></p>

<pre class="longcode">
  <span class="pascal_keyword">var</span>
    ALLibrary: TDynLib = <span class="pascal_keyword">nil</span>;
  <span class="pascal_keyword">initialization</span>
    ALLibrary := TDynLib.Load(<span class="pascal_string">'libopenal.so'</span>);
    <span class="pascal_comment">{ ... some calls to ALLibrary.Symbol() ... }</span>
  <span class="pascal_keyword">finalization</span>
    FreeAndNil(ALLibrary);
  <span class="pascal_keyword">end</span>.
</pre>

<p>

<p>It is important that ALLibrary is initialized to nil (actually, writing &quot; = nil&quot; is not necessary for a global variable) and that in finalization you use Free(AndNil). This allows you to exit gracefully if library does not exist on the system and <a class="normal" href="CastleDynLib.TDynLib.html#Load">Load</a> will raise an exception: ALLibrary will stay then as nil and FreeAndNil(ALLibrary) will be a valid NOP. Using FreeAndNil(ALLibrary) instead of ALLibrary.Free is just a good practice.</p>
<a name="PasDoc-Hierarchy"></a><h2 class="hierarchy">Hierarchy</h2>
<ul class="hierarchy"><li class="ancestor">TObject</li>
<li class="thisitem">TDynLib</li></ul><h2 class="overview">Overview</h2>
<a name="PasDoc-Methods"></a><h3 class="summary">Methods</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>constructor <b><a  href="CastleDynLib.TDynLib.html#Create">Create</a></b>(const AName: string; AHandle: <a  href="CastleDynLib.html#TDynLibHandle">TDynLibHandle</a>);</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>destructor <b><a  href="CastleDynLib.TDynLib.html#Destroy">Destroy</a></b>; override;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>class function <b><a  href="CastleDynLib.TDynLib.html#Load">Load</a></b>(const AName: string; CheckResult: boolean = true): <a  href="CastleDynLib.TDynLib.html">TDynLib</a>;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>function <b><a  href="CastleDynLib.TDynLib.html#Symbol">Symbol</a></b>(SymbolName: PChar): Pointer;</code></td>
</tr>
</table>
<a name="PasDoc-Properties"></a><h3 class="summary">Properties</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a  href="CastleDynLib.TDynLib.html#Name">Name</a></b>: string read FName;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a  href="CastleDynLib.TDynLib.html#SymbolErrorBehaviour">SymbolErrorBehaviour</a></b>: <a  href="CastleDynLib.html#TDynLibSymbolErrorBehaviour">TDynLibSymbolErrorBehaviour</a>
      read FSymbolErrorBehaviour write FSymbolErrorBehaviour
      default seRaise;</code></td>
</tr>
</table>
<h2 class="description">Description</h2>
<h3 class="detail">Methods</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Create"></a><code>constructor <b>Create</b>(const AName: string; AHandle: <a  href="CastleDynLib.html#TDynLibHandle">TDynLibHandle</a>);</code></td>
</tr>
<tr><td colspan="2">
<p>
Standard constructor, requires a valid <a class="normal" href="CastleDynLib.html#TDynLibHandle">TDynLibHandle</a> already. Usually you will prefer to use <a class="normal" href="CastleDynLib.TDynLib.html#Load">Load</a> method instead of directly calling this constructor.

<p></p>
<h6 class="description_section">Exceptions raised</h6>
<dl class="exceptions_raised">
<dt><a class="normal" href="CastleUtils.ECheckFailed.html">ECheckFailed</a></dt>
<dd>if you supply invalid handle.</dd>
</dl>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Destroy"></a><code>destructor <b>Destroy</b>; override;</code></td>
</tr>
<tr><td colspan="2">
&nbsp;</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Load"></a><code>class function <b>Load</b>(const AName: string; CheckResult: boolean = true): <a  href="CastleDynLib.TDynLib.html">TDynLib</a>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Link to a dynamic library specified by Name. Returns created <a class="normal" href="CastleDynLib.TDynLib.html">TDynLib</a> instance.

<p>If the library is not found and CheckResult is <code>False</code>, <code>Nil</code> will be returned. If CheckResult is <code>True</code> then <a class="normal" href="CastleDynLib.EDynLibError.html">EDynLibError</a> will be raised in case library is not found. So if CheckResult is <code>True</code>, <code>Nil</code> is never returned.

<p>Note that the default situation prevents from unintentionally ignoring an error and <i>that's good</i>.

<p></p>
<h6 class="description_section">Exceptions raised</h6>
<dl class="exceptions_raised">
<dt><a class="normal" href="CastleDynLib.EDynLibError.html">EDynLibError</a></dt>
<dd>If library not found and CheckResult is <code>True</code>.</dd>
</dl>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Symbol"></a><code>function <b>Symbol</b>(SymbolName: PChar): Pointer;</code></td>
</tr>
<tr><td colspan="2">
<p>
Return address of given symbol (function name etc.) from loaded dynamic library. If the symbol doesn't exist, then <a class="normal" href="CastleDynLib.TDynLib.html#SymbolErrorBehaviour">SymbolErrorBehaviour</a> says what happens:

<p></p>

<ul class="paragraph_spacing">
  <li><p>seRaise (default), then <a class="normal" href="CastleDynLib.EDynLibError.html">EDynLibError</a> will be raised.</p></li>
  <li><p>seReturnNil, then return <code>Nil</code> (and continue, ignoring error).</p></li>
  <li><p>seWarnAndReturnNil, then write warning (using <a class="normal" href="CastleUtils.html#WarningWrite">WarningWrite</a>) and return <code>Nil</code> (and continue, ignoring error).

<p>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.</p></li>
</ul>

<p>

<p></p>
<h6 class="description_section">Exceptions raised</h6>
<dl class="exceptions_raised">
<dt><a class="normal" href="CastleDynLib.EDynLibError.html">EDynLibError</a></dt>
<dd>If SymbolName doesn't exist and <a class="normal" href="CastleDynLib.TDynLib.html#SymbolErrorBehaviour">SymbolErrorBehaviour</a> is seRaise.</dd>
</dl>
</td></tr>
</table>
<h3 class="detail">Properties</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Name"></a><code>property <b>Name</b>: string read FName;</code></td>
</tr>
<tr><td colspan="2">
<p>
Name of the library to link to. In practice, file name of the *.so or *.dylib or *.dll file.

<p>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.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a  href="legend.html"><img  src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="SymbolErrorBehaviour"></a><code>property <b>SymbolErrorBehaviour</b>: <a  href="CastleDynLib.html#TDynLibSymbolErrorBehaviour">TDynLibSymbolErrorBehaviour</a>
      read FSymbolErrorBehaviour write FSymbolErrorBehaviour
      default seRaise;</code></td>
</tr>
<tr><td colspan="2">
<p>
What happens when <a class="normal" href="CastleDynLib.TDynLib.html#Symbol">Symbol</a> fails.</p>
</td></tr>
</table>
<!-- Piwik -->
<script type="text/javascript">
  var _paq = _paq || [];
  _paq.push(["trackPageView"]);
  _paq.push(["enableLinkTracking"]);

  (function() {
    var u=(("https:" == document.location.protocol) ? "https" : "http") + "://michalis.ii.uni.wroc.pl/piwik-castle-engine/";
    _paq.push(["setTrackerUrl", u+"piwik.php"]);
    _paq.push(["setSiteId", "1"]);
    var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
    g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Piwik Code -->

<noscript>
<!-- Piwik Image Tracker -->
<img src="http://michalis.ii.uni.wroc.pl/piwik-castle-engine/piwik.php?idsite=1&amp;rec=1" style="border:0" alt="" />
<!-- End Piwik -->
</noscript>
<hr noshade size="1"><span class="appinfo"><em>Generated by <a  href="http://pasdoc.sourceforge.net/">PasDoc 0.13.0</a> on 2015-06-15 04:43:09</em>
</span>
</td></tr></table></body></html>