[teklib-general] teklib: Added exec:ScanModules(), teklib:GetNextEntry(), TMSG_GE...

[Timm S. Mueller]

details:   http://hg.teklib.org/teklib/rev/f8f8656ee57c
changeset: 257:f8f8656ee57c
user:      Timm S. Mueller <tmueller at neoscientists.org>
date:      Wed Mar 18 00:32:39 2009 +0100
description:
Added exec:ScanModules(), teklib:GetNextEntry(), TMSG_GETNEXTENTRY hook message type

diffs (truncated from 482 to 100 lines):

diff -r 35c8e375a710 -r f8f8656ee57c doc/manual.html
--- a/doc/manual.html	Tue Mar 17 12:03:06 2009 +0100
+++ b/doc/manual.html	Wed Mar 18 00:32:39 2009 +0100
@@ -1606,6 +1606,36 @@
 				<hr />
 			</div>
 		</div>
+		<div class="node"><h3><a name="teklib:TGetNextEntry" id="teklib:TGetNextEntry"><code>TGetNextEntry()</code></a></h3>
+<pre>
+entry = TGetNextEntry(handle)
+TAPTR                 struct THandle*
+</pre>
+			<div class="definition"><dfn>FUNCTION</dfn>
+				<p>
+					Get the next entry from a handle by dispatching TMSG_GETNEXTENTRY.
+				</p>
+			</div>
+			<div class="definition"><dfn>RESULTS</dfn>
+				<blockquote>
+					<ul>
+						<li style="list-style-type: none">
+							<code>entry</code> - Next entry, or <code>TNULL</code> if no next entry available
+						</li>
+					</ul>
+				</blockquote>
+			</div>
+			<div class="definition"><dfn>INPUTS</dfn>
+				<blockquote>
+					<ul>
+						<li style="list-style-type: none">
+							<code>handle</code> - Pointer to a generic object handle
+						</li>
+					</ul>
+				</blockquote>
+				<hr />
+			</div>
+		</div>
 		<div class="node"><h2><a name="string" id="string">string </a></h2>
 			<div class="definition"><dfn>FUNCTIONS</dfn>
 				<ul>
@@ -1973,6 +2003,9 @@
 					</li>
 					<li style="list-style-type: none">
 						<a href="#exec:TReplyMsg"><code>exec:TReplyMsg()</code></a> - Return a modified message to its sender
+					</li>
+					<li style="list-style-type: none">
+						<a href="#exec:TScanModules"><code>exec:TScanModules()</code></a> - Scan available TEKlib modules
 					</li>
 					<li style="list-style-type: none">
 						<a href="#exec:TSendMsg"><code>exec:TSendMsg()</code></a> - Send a message synchronously
@@ -4804,6 +4837,57 @@
 				<hr />
 			</div>
 		</div>
+		<div class="node"><h3><a name="exec:TScanModules" id="exec:TScanModules"><code>TScanModules()</code></a></h3>
+<pre>
+handle = TScanModules(tags)
+struct THandle*       TTAGITEM*
+</pre>
+			<div class="definition"><dfn>FUNCTION</dfn>
+				<p>
+					This function scans all available TEKlib modules and, if successful,
+					returns a handle that can be queried using <a href="#teklib:TGetNextEntry"><code>teklib:TGetNextEntry()</code></a>.
+					Each invocation of <a href="#teklib:TGetNextEntry"><code>teklib:TGetNextEntry()</code></a> returns a pointer to a
+					taglist, or <code>TNULL</code> when there are no more entries available.
+					Possible tags in this taglist, as currently defined, are:
+				</p>
+				<blockquote>
+					<ul>
+						<li>
+							<code>TExec_ModuleName, (TSTRPTR)</code> - Name of a module that would
+							be available to <a href="#exec:TOpenModule"><code>exec:TOpenModule()</code></a>.
+						</li>
+					</ul>
+				</blockquote>
+				<p>
+					When you are done scanning for modules, the handle should be destroyed
+					with <a href="#teklib:TDestroy"><code>teklib:TDestroy()</code></a>.
+				</p>
+			</div>
+			<div class="definition"><dfn>EXAMPLE</dfn>
+				<p>
+					The following code snippet scans the system for TEKlib modules:
+				</p>
+<pre>
+struct THandle *handle = TScanModules(TNULL);
+if (handle)
+{
+    TTAGITEM *entry;
+    while ((entry = TGetNextEntry(handle)))
+        printf(&quot;%s\n&quot;, (TSTRPTR) TGetTag(entry, TExec_ModuleName, TNULL));
+}
+TDestroy(handle);
+</pre>
+			</div>
+			<div class="definition"><dfn>RESULTS</dfn>
+				<ul>
+					<li style="list-style-type: none">
+						<code>handle</code> - A handle that can be passed to <a href="#teklib:TGetNextEntry"><code>teklib:TGetNextEntry()</code></a>,
+						or <code>TNULL</code>.