Cross Point


IApplication Interface Reference

Inheritance diagram for IApplication:

IEventBase List of all members.

Detailed Description

The main api interface.

This is the main API interface. It can be used to access all other interfaces.

This interface can be used to scan for reader-networks (COM-ports) on this PC. Use the ScanReaderNetworks to start a scan. The found reader-networks can be retrieved using the ReaderNetworks property. Each available reader-network can in turn be scanned for attached readers, see the IReaderNetwork interface for more detailed information. A collection with all found reader-networks is cached internally to increase performance.

This interface also includes advanced search capabilities to perform a search on all connected readers at once. See the Search method for more information.

Another feature of the application interface is that it can be used to get a collection of all available readers (using Readers) of all reader networks. Or find a specific reader (using FindReader).

Note that both the ScanReaderNetworks and Search operations can be performed asynchronously, meaning that they can operate in the background, allowing the user interface to perform other tasks. A number of methods and properties in the interface are especially useful when performing asynchronous operations, like IsScanning, SearchStatus, CancelScanning etc.

All other 'sub' objects in this API have properties enabling it to reach their parent object, thus allowing all objects to reach this main application object. For instance the IReaderNetwork interface contains a IReaderNetwork::Application property. The IUser interface for instance contains an IUser::UserDatabase property, that contains a IUserDatabase::Reader that holds an IProximityReader::Network etc. So from all objects you can always return to this IApplication object.

To increase performance when using an Application object in your own program (VBScript, JScript, HTML or whatever other language you prefer), make sure that this Application object does not go out of scope. Best practice is to store the application object in a global variable. The reason for this is that when all references to the application are released, all internal cached collections are cleared. When this happens, all reader networks and readers etc. should then be scanned again before they can be re-used.


Public Member Functions

HRESULT Name ([out, retval] BSTR *pbstrName)
 Returns the full path name of this dll.

HRESULT ScanReaderNetworks ([in, defaultvalue(0)] VARIANT_BOOL ScanAsync,[in, defaultvalue(1)] short StartPortNumber,[in, defaultvalue(31)] short EndPortNumber,[out, retval] short *psNumberOfNetworks)
 Scan reader networks on this computer.

HRESULT IsScanning ([out, retval] ECollectingStatus *peStatus)
 Returns the status of this reader-network scanning process.

HRESULT CancelScanning ()
 Cancel a network scan that is currently in progress.

HRESULT ReaderNetworks ([out, retval] ICollection **ppintfReaderNetworks)
 Returns all available scanned networks.

HRESULT FindReaderNetwork ([in] short PortNumber,[out, retval] IReaderNetwork **ppintfReaderNetwork)
 Returns the network connected on the specified portnumber (COM-port) if available.

HRESULT ReaderNetworkCount ([out, retval] long *plNetworks)
 Returns the number of scanned reader networks (COM-ports) currently available.

HRESULT Readers ([out, retval] ICollection **ppintfReaders)
 Returns all readers on all available scanned networks.

HRESULT ReaderCount ([out, retval] long *plReaders)
 Returns the number of all available scanned readers.

HRESULT FindReader ([in] short PortNumber,[in] short NetworkAddress,[out, retval] IProximityReader **ppintfReader)
 Returns the proximity reader connected on a specific portnumber (COM-port) and network address.

HRESULT Search ([in] ESearchFlags Flags,[in] VARIANT User,[in, defaultvalue(0)] VARIANT Range,[in, defaultvalue(0)] VARIANT StartDate,[in, defaultvalue(0)] VARIANT EndDate,[out, retval] VARIANT_BOOL *pfSucceeded)
 Perform a search operation on all readers.

HRESULT CancelSearch ()
 Cancel all running search processes in all readers.

HRESULT SearchResults ([out, retval] ICollection **ppintfResults)
 Returns a collection of all search results of all readers.

HRESULT SearchStatus ([out, retval] ESearchStatus *peStatus)
 Returns the status of the current search process.

HRESULT ClearSearchResults ([out, retval] VARIANT_BOOL *pfSucceeded)
 Clears the last search results of all readers.

HRESULT ArchiveEvents ([in] BSTR bstrFilename,[in] EFileType eFileType,[in, defaultvalue(0)] VARIANT_BOOL fAsync,[in, defaultvalue(0)] VARIANT StartDate,[in, defaultvalue(0)] VARIANT EndDate,[in, defaultvalue(0)] EArchiveEventsOptions eOptions,[out, retval] VARIANT_BOOL *pfSucceeded)
 Archive all events of all readers in a certain time-span to file.

HRESULT SynchronizeClocks ([out, retval] VARIANT_BOOL *pfSucceeded)
 Synchronize the clocks of all logged-on readers.


Member Function Documentation

IApplication::Name [out, retval] BSTR *  pbstrName  ) 
 

Returns the full path name of this dll.

Parameters:
pbstrName Receives the full path name of this dll.
Precondition:
pbstrName is not NULL.
Note:
This is a read-only property when used in scripting languages. This is the default property of this object.

IApplication::ScanReaderNetworks [in, defaultvalue(0)] VARIANT_BOOL  fScanAsync,
[in, defaultvalue(1)] short  sStartPortNumber,
[in, defaultvalue(31)] short  sEndPortNumber,
[out, retval] short *  psNumberOfNetworks
 

Scan reader networks on this computer.

A collection with all readernetworks is created. This collection is cached internally for future use. This method returns the number of reader networks when scanning is performed synchronously. To retrieve the collection, use ReaderNetworks.

When the fScanAsync flag is set to true, the scanning process is done in the background and this method will return immediately (enabling the caller to perform other tasks).

This method fires the default OnProcessStarted and OnProcessFinished events. The process type is the ptScanningNetworks. The OnProcessInfo is also fired with the sub process type of sptItemFound when a new network is found. The Info parameter of the OnProcessInfo will then contain the found IReaderNetwork object.

Note that the during the scanning the OnProcessInfo event is also fired with the ptApplicationChange process type. This ptApplicationChange is a general process type, all changes to the application i.e. new networks found and networks changed can be monitored using this process type. When the ScanReaderNetworks method fires the ptApplicationChange process event, the sub process type is set to sptItemAdded for every found network (Info contains a IReaderNetwork object).

The status of the scanning process can be determined using the IsScanning property. The process can be interrupted using the CancelScanning method.

Parameters:
fScanAsync When set to true, the scan is performed in the background (in another thread).
sStartPortNumber The portnumber where the scanning process should start looking for readernetworks.
sEndPortNumber The portnumber where the scanning process should stop looking for readernetworks.
psNumberOfNetworks Receives the number of readernetworkss found (ONLY when fScanAsync is false).
See also:
ReaderNetworks, ReaderNetworkCount, FindReaderNetwork, IsScanning, CancelScanning

IApplication::IsScanning [out, retval] ECollectingStatus peStatus  ) 
 

Returns the status of this reader-network scanning process.

Parameters:
peStatus Receives the status of the scanning process.
Precondition:
peStatus is not NULL
Note:
This is a read-only property when used in scripting languages.
See also:
ScanReaderNetworks, CancelScanning

IApplication::CancelScanning  ) 
 

Cancel a network scan that is currently in progress.

If the network scan process is not active, this method will do nothing.

See also:
ScanReaderNetworks, IsScanning

IApplication::ReaderNetworks [out, retval] ICollection **  ppintfReaderNetworks  ) 
 

Returns all available scanned networks.

Returns the cached collection of all reader-networks (IReaderNetwork objects).

This property will fail if the ScanReaderNetworks method has not yet been called. A collection with all available scanned networks is returned. This collection has been cached for future use by the ScanReaderNetworks method. Note that all networks are returned, even those with no readers attached (actually, all available COM-ports).

Parameters:
ppintfReaderNetworks Receives a collection (ICollection) that holds all reader networks (IReaderNetwork).
Precondition:
ppintfReaderNetworks is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ScanReaderNetworks, FindReaderNetwork, ReaderNetworkCount

IApplication::FindReaderNetwork [in] short  sPortNumber,
[out, retval] IReaderNetwork **  ppintfReaderNetwork
 

Returns the network connected on the specified portnumber (COM-port) if available.

This method tries to return the network that is attached on the given port number (COM-port). If the network is not found, or not available, an empty object is returned (with a return code of 1, S_FALSE).

This method will fire events. The process type of those events is ptFindingNetwork. The OnProcessInfo is fired with the sub process type of sptItemFound when the specified network is found. The Info parameter of the OnProcessInfo will then contain the found IReaderNetwork object.

When the reader networks are not yet scanned, this method will start scanning all networks (from port 1 to 32) before it start to find a specific network. The events fired by the ScanReaderNetwork will then be fired as sub process events of this process.

When a new network is found, that was not found during the ScanReaderNetworks, the general ptApplicationChange process is also fired with sptItemAdded, the Info parameter then contains the newly found IReaderNetwork object.

Parameters:
sPortNumber The portnumber to check (value between 1 and 31).
ppintfReaderNetwork Receives the IReaderNetwork if it is found or NULL if not found.
Precondition:
ppintfReaderNetwork is not NULL
Note:
The network is only returned when it is currently not in use by any other program.
See also:
ScanReaderNetworks, ReaderNetworks, ReaderNetworkCount

IApplication::ReaderNetworkCount [out, retval] long *  plNetworks  ) 
 

Returns the number of scanned reader networks (COM-ports) currently available.

If this property is used before ScanReaderNetworks, the ScanReaderNetworks method will be called first to build the internal network collection. This method will return the number of reader networks contained in the internal cached collection of available scanned networks.

This property will not fire any events.

Parameters:
plNetworks Receives the number of reader networks.
Precondition:
plNetworks is not NULL
Note:
This is a read-only property when used in scripting languages.
See also:
ScanReaderNetworks, ReaderNetworks, FindReaderNetwork

IApplication::Readers [out, retval] ICollection **  ppintfReaders  ) 
 

Returns all readers on all available scanned networks.

Returns a collection with all readers. If this property is used before ScanReaderNetworks is called, the internal network collection will be build first.

Note that this property loops through all reader-networks and calls the IReaderNetwork::Readers on each reader-network. Since the IReaderNetwork::Readers property is a very slow property (since it will scan all addresses for readers), this property can be a very slow operation. To increase performance, it is better to scan for readers on each reader-network separately using the IReaderNetwork::ScanReaders method before calling this property to retrieve all readers.

This property will not fire any events.

Parameters:
ppintfReaders Receives a collection ICollection with all the reader (IProximityReader) objects.
Precondition:
ppintfReaders is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ReaderCount, FindReader

IApplication::ReaderCount [out, retval] long *  plReaders  ) 
 

Returns the number of all available scanned readers.

If this property is used before ScanReaderNetworks is called, the internal network collection will be build first.

This property will loop through all reader networks, and calls the IReaderNetwork::ReaderCount method of each reader-network. This operation might be very slow.

This property will not fire any events.

Parameters:
plReaders Receives the number of readers.
Precondition:
plReaders is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Readers, FindReader

IApplication::FindReader [in] short  sPortNumber,
[in] short  sNetworkAddress,
[out, retval] IProximityReader **  ppintfReader
 

Returns the proximity reader connected on a specific portnumber (COM-port) and network address.

This method starts by using the FindReaderNetwork to find the specified reader-network. It then calls the IReaderNetwork::FindReader method of the reader-network to get the requested address. Read the detailed descriptions of those methods to gain more insight in this method. This method fires events of process type ptFindingReader. It will fire the sptFindingNetwork and sptFindingReader sub processes.

If no reader is found at the specified address and port, this method will return an empty object the return code of this method will then be set to 1 (S_FALSE).

Parameters:
sPortNumber The portnumber to check (value between 1 and 31).
sNetworkAddress The network address to check (value between 0 and 255).
ppintfReader Receives the proximity reader if found or NULL if not found.
Precondition:
ppintfReader is not NULL
See also:
FindReaderNetwork, IReaderNetwork::FindReader

IApplication::Search [in] ESearchFlags  eFlags,
[in] VARIANT  vtUser,
[in, defaultvalue(0)] VARIANT  vtRange,
[in, defaultvalue(0)] VARIANT  vtStartDate,
[in, defaultvalue(0)] VARIANT  vtEndDate,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Perform a search operation on all readers.

This method uses the Readers property to get a collection of all readers. It then calls the IProximityReader::Search method for each of reader separately. See the IProximityReader::Search method for more detailed information about searching.

When the sfSearchAsync is set in the eFlags argument, the search process will be performed asynchronously (in the background). To get the status of the pending asynchronous search process, use the SearchStatus property. It will be set to ssSearched when the search operation is complete. It is then possible to get the search results using the SearchResults property. Cancel a pending search process by calling the CancelSearch method.

This method fires events. The process type is ptSearching. When searching users, the sptSearchingUsers sub process is fired for each reader. When searching events, the sptSearchingEvents is fired for each reader. Note that the BaseObject parameter of those events will hold the IUserDatabase or IEventDatabase object of the specific reader. When a matching user is found, the sub process will hold sptSearchingUsers | sptItemFound. The Info parameter will hold the found user object (IUser object). For a matching event, the sub process will hold sptSearchingEvents | sptItemFound. The Info parameter will hold the found event object (IEvent object). Note that you should use the sptItemMask to mask out the sptItemFound sub process. The sub process itself should be retrieved using the sptSubProcessMask mask.

The IProximityReader::Search operation forwards the search operation to the IUserDatabse::SearchUsers and/or IEventDatabase::SearchEvents. Note that the last search-results will be cached inside each database to increase performance. To clear all search results of all readers, use the ClearSearchResults method or specify the sfClearResults flag when searching.

Parameters:
eFlags Searchflags, specifying the search type to perform.
vtUser This parameter may contain a IUser object (with either a correct ID or a correct username), or a string containing the ID that should be searched. This id-string should be in the following form: ~Cardtype~Facility~Number~. This parameter may also contain a string with a (part) of a username.
vtRange This parameter may hold an VT_I4. When sfUsers is specified as flag, the highest 2 bytes should hold the users levels (see vtLevelRange of IUserDatabase::SearchUsers). When sfEvents is specified as flag, the lowest 2 bytes should hold the event numbers (see vtRange of IEventDatabase::SearchEvents).
vtStartDate This parameter may hold a start date/time from where the events should be searched.
vtEndDate This parameter may hold the end date/time. Only events before this date will be returned.
pfSucceeded Receives true if the search process finished successful (only useful when searching synchronously).
See also:
SearchStatus, SearchResults, CancelSearch, ClearSearchResults, IProximityReader::Search,

IApplication::CancelSearch  ) 
 

Cancel all running search processes in all readers.

See also:
Search, SearchStatus, SearchStatus

IApplication::SearchResults [out, retval] ICollection **  ppintfResults  ) 
 

Returns a collection of all search results of all readers.

Only returns valid data when all readers have finished searching. Check the search status of the readers using the SearchStatus property. This method will combine the search results of all readers in a single collection. If this method is called before the Search operation is finished, this method will only return the items it has found up till now.

The contents of the returned collection may vary. Depending on what has been searched the collection contains either IUser objects, IEvent objects or both.

Parameters:
ppintfResults Receives a collection of all search results.
Precondition:
ppintfResults is not NULL
Note:
This is a read-only property when used in scripting languages.
See also:
Search, SearchStatus, CancelSearch, ClearSearchResults, IUser, IEvent, ICollection

IApplication::SearchStatus [out, retval] ESearchStatus peStatus  ) 
 

Returns the status of the current search process.

The status is determined by combining the search status of all readers of all reader-networks. For every reader the IProximityReader::SearchStatus property is called.

Parameters:
peStatus Receives the status of all search processes.
Precondition:
peStatus is not NULL
Note:
This is a read-only property when used in scripting languages.
See also:
Search, SearchResults, CancelSearch

IApplication::ClearSearchResults [out, retval] VARIANT_BOOL *  pfSucceeded  ) 
 

Clears the last search results of all readers.

This method will call the IProximityReader::ClearSearchResults method for each reader of all reader-networks.

Parameters:
pfSucceeded Set to true when the clear succeeds.
See also:
Search, SearchResults, CancelSearch, SearchStatus

IApplication::ArchiveEvents [in] BSTR  bstrFilename,
[in] EFileType  eFileType,
[in, defaultvalue(0)] VARIANT_BOOL  fAsync,
[in, defaultvalue(0)] VARIANT  vtStartDate,
[in, defaultvalue(0)] VARIANT  vtEndDate,
[in, defaultvalue(0)] EArchiveEventsOptions  eOptions,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Archive all events of all readers in a certain time-span to file.

This method uses the Search method to create a collection of all events of all readers. It then calls the SearchResults property to retrieve all the event objects. See the IProximityReader::Search method for more detailed information about searching.

When the fAsync flag is set, the collecting is performed asynchronously (in the background). This operation cannot be canceled.

This method fires events. The process type is ptArchivingEvents. Since it uses the Search method internally to collect events, all events of the Search method will be fired as sub-process events of the ptArchivingEvents process. See the Search documentation for more information.

The found events can be saved to HTML, XML or CSV file.

Only events between the start and end date will be archived into the file.

Parameters:
bstrFilename The location/path of the file where the events should be saved to.
eFileType In what format should be events be saved (HTML, XML or CSV).
fAsync If set to true, this method will be performed asynchronously (in the background). This method will return immediately.
vtStartDate The start date/time from where the events should be searched.
vtEndDate The end date/time. Only events before this date will be returned.
eOptions Options for the archive events method (archive all events, or archive only security events).
pfSucceeded Receives true if the events are archived successful (only useful when searching synchronously).
See also:
Search, EFileType

IApplication::SynchronizeClocks [out, retval] VARIANT_BOOL *  pfSucceeded  ) 
 

Synchronize the clocks of all logged-on readers.

This method sets the time of all clocks of all connected, logged-on, readers to the current time.

Parameters:
pfSucceeded Receives true if all clocks are successfully synchronized.


© Copyright 2001 - 2006 Cross Point. Generated on Mon Mar 12 16:29:51 2007 Cross Point