This document describes classes and members of the Talos API. The API consists of a set of COM classes (Microsoft Component Object Model) designed to program and manage multiple networks of multiple readers from within Window 2000 and Windows XP Professional.
This documentation is written for moderate programmers with knowledge of Visual Basic or other COM enabled languages. Some understanding of the COM programming model is required.
The API can be used to create an application like a normal Windows application, a web interface, or a simple script. Applications that use this API can be developed in several programming languages that support COM. Examples are C, C++, C#, Delphi, Visual Basic and Scripting languages (VBScript, JScript, ActivePerl or JavaScript).
To support scripting languages, some concessions are made to the design. Scripting languages cannot use the more advanced features of COM. Besides the description of the COM interfaces and the calling syntax of their interface functions, this document will also give a global description of the working of this API.
The functionality of the API is exposed through interfaces. Web servers like Microsoft Internet Information Server (IIS) with ASP can also be used to communicate with this API. ASP is a technique that produces HTML pages for web browsers from a template that can hold embedded scripting. When the server receives a request from a client (a web browser) for a page, this page is loaded and all scripting in this page runs to produces a static HTML page that is send to the browser. In this scripting, you can call the API to receive information and to use its functionality.
Scripting languages are not typed. Therefore, they need a mechanism to call functions in the interfaces to pass arguments and to get the function name. Microsoft has introduced such a mechanism in COM to handle this. Scripting clients can use the IDispatch interface. IDispatch is a normal COM interface with a standard set of functions. These functions are called by scripting languages to determine the functions exposed by the interfaces. These interfaces must inherit from IDispatch to enable the scripting client to call a function in this interface. Interfaces can be implemented in three ways:
All methods that require some time to execute will fire events. Events are 'callback' methods that inform the calling process about certain things like progress, the state of a running process etc. When the calling process is registered with the API, the API will call special methods of the calling process to inform this process about the state of certain running API methods.
In contrast with other API's, this API has only three event methods. Other API's usually have a separate event method for each event (for instance OnLeftMouseButtonDown, OnRightMouseButtonDown, etc.). In this API the event methods are combined, there are only three different event methods: one event method is always called when a process is started, one when the process has finished, the other method can be called multiple times, this to inform about progress, found items etc.
The three different kinds of events are:
Most of methods firing events are methods that can be executed both synchronously as well as asynchronously (in a background process).
As mentioned in the description of the OnProcessInfo event, a process might be fired as a sub process inside another process. When for instance copying users from one reader into another reader, the users of the source reader should be collected first. If they are not yet collected, the Copy method will start by collecting them, this would generate an OnProcessStarted event of process type ptCollectingUsers, some OnProcessInfo events and an OnProcessFinished event. These events are not quite as expected, since the API is currently in a copy process, not a collect-users process. So these events are modified by the API, they are now fired as sub-processes events, not as 'main' processes events.
In the above example, the OnProcessStarted event of the ptCollectingUsers process is fired as a OnProcessInfo of processtype ptCopyingReader with sub processtype sptCollectingUsers. To indicate that the sub processtype has started another flag is set in the sub processtype, the sptStarted flag.
When a sub process starts, the SubProcessType argument of the OnProcessInfo will contain the sptStarted flag, indicating that the sub process has started, as well as the code for the sub process in question. When a sub process has finished, the another flag is used, the sptFinished flag. Use the sptSubProcessMask mask to filter the sub process type out of the SubProcessType argument. Use the sptStatusMask to filter out the sptStarted and/or sptStopped flags.
Another example: when for instance the IProximityReader::SetFileSystem method is used to change the filesystem of a reader , the IProximityReader::Reset method will be used internally to reset the reader (resetting is required since the new settings will become effective only after a reset). In this case, the events generated by the reset method will be fired as sub process events in the SetFileSystem process. The events that are fired are thus:
To be able to access all enumerations used in this API when programming in JScript or VBScript, the files TalosAPI.js and TalosAPI.vbs might be useful. Both files contain all enumerations. They can easily be included into the source file (or simply copy the required parts into your source files).
This documentation contains a number of examples. These examples are written in JScript. They can be easily executed by the shell on any Windows (XP / 2000) PC. The following examples are provided:
Cross Point disclaims all warranties and liabilities for the use of this document and the information contained herein, and assumes no responsibility for any errors which may appear in this document or for hardware damage resulting from incorrect use of this API, nor does Cross Point make a commitment to update the information contained herein. Cross Point reserves the right to make changes to this document at any time, without notice.