Cross Point


IReaderNetwork Interface Reference

Inheritance diagram for IReaderNetwork:

IEventBase List of all members.

Detailed Description

A reader network represents a physical network of readers (on a single COM-port).

This object handles all low-level communication with all readers attached to this COM-port. It ensures that all messages send to the readers are send one at a time and that all received data goes to the correct reader.

When a reader-network object is returned by the IApplication::ReaderNetworks or IApplication::FindReaderNetwork functions, the first thing that should be done is to connect to the network (use the Connect method). Then the reader-network object is able to communicate with the real COM-port.

This object enables the user to search for readers on a single network using the ScanReaders. The found readers can be retrieved using the Readers property.

To find a particular reader on a specific address, use the FindReader method.

When you are done using this reader-network (when you are ready with all readers of this reader-network), call Disconnect to close the COM-port. All further communication with the COM-port will fail after the Disconnect method is called!

This object also contains functionality to change the baudrate and framing of the COM-port. Using the ChangeSettings method, it is possible to change the baudrate of the reader-network as well as changing the baudrate settings of all readers atached to this reader-network. Note that only the readers that are scanned using the ScanReaders method and are logged-on (using the IProximityReader::Logon method) will change their settings. Since the baudrate of the network is also changed, readers that were not logged-on, or readers that were not scanned will not be accessable anymore. To access/find these readers again, use the ScanReaders method again to change the communication settings to their original values, but do not set the UpdateReaders flag. Rescan the reader-network, and the old readers are (hopefully) found again.

Note that the ScanReaders operation can be performed asynchronously, meaning that it can operate in the background, allowing the user to perform other tasks. The CancelScanning method and the IsScanning property are only meaningfull when executing the scan asynchronously.


Public Member Functions

HRESULT Application ([out, retval] IApplication **pintfApplication)
 Returns the main application object.

HRESULT PortNumber ([out, retval] short *psPortNumber)
 Returns the number of the COM port that is used by this network.

HRESULT Connect ([in, defaultvalue(br9600)] EBaudrate Baudrate,[in, defaultvalue("8N2")] BSTR Framing,[out, retval] VARIANT_BOOL *pfSucceeded)
 Connects the readernetwork to the actual COM-port.

HRESULT Disconnect ([out, retval] VARIANT_BOOL *pfSucceeded)
 Disconnects the software from the actual COM-port.

HRESULT IsConnected ([out, retval] VARIANT_BOOL *pfConnected)
 Checks if the reader-network is connected to the COM-port.

HRESULT ChangeSettings ([in] EBaudrate NewBaudrate,[in, defaultvalue("8N2")] BSTR NewFraming,[in, defaultvalue(-1)] VARIANT_BOOL UpdateReaders,[in, defaultvalue(-1)] VARIANT_BOOL fChangeAsync)
 Change the communication settings for this network and (optional) all connected readers.

HRESULT SetTurboMode ([in] EBaudrate NewBaudrate)
 Temporary increases the speed of this reader-network and all attached readers.

HRESULT Baudrate ([out, retval] EBaudrate *peBaudrate)
 Returns the current baudrate of this reader-network.

HRESULT CharacterFrame ([out, retval] BSTR *pbstrFraming)
 Returns the current character frame setting of this reader-network.

HRESULT ScanReaders ([in, defaultvalue(0)] VARIANT_BOOL ScanAsync,[in, defaultvalue(0)] short StartAddress,[in, defaultvalue(32)] short EndAddress,[out, retval] short *sReaders)
 Scan this reader-network for attached readers.

HRESULT IsScanning ([out, retval] ECollectingStatus *peStatus)
 Returns the status of the current asynchronous scanning process.

HRESULT CancelScanning ()
 Cancel an asynchronous scanning process that is currently in progress.

HRESULT Readers ([out, retval] ICollection **Readers)
 Returns all readers on this network.

HRESULT FindReader ([in] short Address,[out, retval] IProximityReader **ppintfReader)
 Returns the reader at a specific address.

HRESULT CheckPresence ([in, defaultvalue(0)] VARIANT_BOOL Async,[in, defaultvalue(smBootloader)] ESoftwareMode Mode,[in, defaultvalue(0)] short Address,[in, defaultvalue(5000)] long Timeout,[in, defaultvalue(0)] VARIANT_BOOL ActivateBootloader,[out, retval] IProximityReader **ppintfReader)
 Periodically checks if a reader is present at a specific address.

HRESULT ReaderCount ([out, retval] long *plReaders)
 Returns the total number of all readers that are currently connected to this network.

HRESULT SetFastTimeout ([in] VARIANT_BOOL fFast)
 Set the time out value to the fast time-out.


Member Function Documentation

IReaderNetwork::Application [out, retval] IApplication **  ppintfApplication  ) 
 

Returns the main application object.

Parameters:
ppintfApplication Receives the application object.
Precondition:
ppintfApplication is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IApplication

IReaderNetwork::PortNumber [out, retval] short *  psPortNumber  ) 
 

Returns the number of the COM port that is used by this network.

Parameters:
psPortNumber Receives the portnumber.
Precondition:
psPortNumber is not NULL.
Note:
This is a read-only property when used in scripting languages.

This is the default property of this object.

IReaderNetwork::Connect [in, defaultvalue(br9600)] EBaudrate  eBaudrate,
[in, defaultvalue("8N2")] BSTR  bstrFraming,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Connects the readernetwork to the actual COM-port.

Use this method before calling any other method/property of this interface. It will establish the communication. When you are finished with this reader-network (and all it's readers), use the Disconnect method to close the COM-port.

To determine if the reader-network is already connected, use the IsConnected property.

The framing argument should be a string in the following form: "8N2". The first digit represents the number of data bytes, followed by the parity: O (for Odd), N (for None), E (for Event), the last digit is the number of stopbits. The default framing for communicating with the readers is "8N2".

The default factory setting for the baudrate of a reader is 9600 bps.

Parameters:
eBaudrate The baudrate for this connection.
bstrFraming The framing string.
pfSucceeded This argument will be set to true when the connection succeeds.
See also:
Disconnect, IsConnected

IReaderNetwork::Disconnect [out, retval] VARIANT_BOOL *  pfSucceeded  ) 
 

Disconnects the software from the actual COM-port.

Call this method to close a connection that was opened with the Connect method. To determine if the reader-network is already connected, use the IsConnected property.

Parameters:
pfSucceeded Set to true when the disconnect sequence succeeds.
Note:
Should be called last! Any operation that communicates with a reader of this network will fail if a reader-network is not connected!
See also:
Connect, IsConnected

IReaderNetwork::IsConnected [out, retval] VARIANT_BOOL *  pfConnected  ) 
 

Checks if the reader-network is connected to the COM-port.

Parameters:
pfConnected Will be set top true if there is a valid connection with the reader-network.
Precondition:
pfConnected is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Connect, Disconnect

IReaderNetwork::ChangeSettings [in] EBaudrate  eNewBaudrate,
[in, defaultvalue("8N2")] BSTR  bstrNewFraming,
[in, defaultvalue(-1)] VARIANT_BOOL  fUpdateReaders,
[in, defaultvalue(-1)] VARIANT_BOOL  fChangeAsync
 

Change the communication settings for this network and (optional) all connected readers.

When the fUpdateReaders flag is set, all connected (logged-on) readers will be set to the new baudrate and framing. If there are no readers in the internal cached collection of scanned readers, only the setting of this network will be changed.

This method will fire events of processtype ptChangingNetworkSettings. If the fUpdateReaders flag is set to true, this method will start by changing the baudrate and framing of all connected readers by changing their baudrate and framing parameters. This may generate an sptItemModified event of processtype ptParameterdatabaseChange on the parameter database object. After changing these parameters, a reset will be initiate on all readers, causing ptResetting events to be fired on the readers. The next step is to poll all readers to check whether they are finished changing. During the polling progress events are fired. When a reader has finished changing its settings, the OnProcessInfo event is fired with the sptItemModified sub process type, the Info flag will the reader object. If a reader fails to change its settings the OnProcessInfo event is fired with the sptItemFailed sub process type. When all readers changed their settings successfully, the OnProcessFinished event will return S_OK (0) as ResultCode. If one or more readers fail, the ResultCode will be set to E_FAIL.

Parameters:
eNewBaudrate The new baudrate setting.
bstrNewFraming The new character frame setting.
fUpdateReaders If set, all connected (and logged on) readers will be set to the new settings as well.
fChangeAsync If set the changing process is done asynchronously.
Note:
This method cannot be canceled.

A reader will fail to accept the new settings if it is not logged on! Make sure all readers that you want to change are logged-on (using the IProximityReader::Logon method).

See also:
Baudrate, CharacterFrame

IReaderNetwork::SetTurboMode [in] EBaudrate  eNewBaudrate  ) 
 

Temporary increases the speed of this reader-network and all attached readers.

Parameters:
eNewBaudrate The new baudrate to switch to.
Note:
The settings will be volatile, after the reader is reset, the previous baudrate settings will be active again.
Warning:
This method has not been tested, use at your own risk!
See also:
ChangeSettings

IReaderNetwork::Baudrate [out, retval] EBaudrate peBaudrate  ) 
 

Returns the current baudrate of this reader-network.

Parameters:
peBaudrate Receives the baudrate.
Precondition:
peBaudrate is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
CharacterFrame, Connect, ChangeSettings

IReaderNetwork::CharacterFrame [out, retval] BSTR *  pbstrFraming  ) 
 

Returns the current character frame setting of this reader-network.

Parameters:
pbstrFraming Receives the character frame string (e.g. "8N2").
Precondition:
pbstrFraming is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Baudrate, Connect, ChangeSettings

IReaderNetwork::ScanReaders [in, defaultvalue(0)] VARIANT_BOOL  fScanAsync,
[in, defaultvalue(0)] short  sStartAddress,
[in, defaultvalue(32)] short  sEndAddress,
[out, retval] short *  psReaders
 

Scan this reader-network for attached readers.

You can control the range of addresses that should be scanned using the sStartAddress and sEndAddress arguments. Since readers are assigned address in the range of 0 upto 32 during the production process. A good scan range is from 0 upto 32. You can always change the address of your readers (using IProximityReader::ChangeNetworkAddress) and modify the scan range to increase performance.

This method creates a collection with found readers. This collection is cached internally for future uses. The number of found readers is returned when performing a synchronous scan. To get the collection of found readers, use the Readers property.

This method fires the default events of event type ptScanningReaders. Progress events are also generated for every scanned address. When a reader is found on a specific address, an OnProcessInfo event is fired with the sptItemFound sub process type, the Info parameter will then contain the found reader object (IProximityReader). If a reader is found with old (incompatible) firmware, the OnProcessInfo will be fired with the sptItemFailed sub process type, again, the Info parameter will contain the relevant reader. If the OnProcessInfo returns S_OK (0) when the sptItemFailed event occurs, the specific reader will be added to the internal collection (they reader is accepted), when the OnProcessInfo returns something other then 0, the reader will not be added to the internal collection.

When executing the scan asynchronously, you can use the CancelScanning method to cancel the scan, and use the IsScanning property to determine the state of the current scan process.

Parameters:
fScanAsync When set to true, the scan is performed asynchrously.
sStartAddress The address where the scanning process should start looking for readers (default 0).
sEndAddress The address where the scanning process should stop looking for readers (default 32).
psReaders Receives the number of readers found (only when fScanAsync is false).
See also:
Readers, ReaderCount, CancelScanning, IsScanning

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

Returns the status of the current asynchronous 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:
ScanReaders, CancelScanning

IReaderNetwork::CancelScanning  ) 
 

Cancel an asynchronous scanning process that is currently in progress.

See also:
ScanReaders, IsScanning

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

Returns all readers on this network.

Returns the cached collection of found readers (IProximityReader objects).

When this property is called before the ScanReaders method is called, it will scan for readers itself. This can be very time-concuming since this property will scan from address 0 upto address 255. So to increase performance, first call the ScanReaders method.

Parameters:
ppintfReaders A collection that receives the readers.
Precondition:
ppintfReaders is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ICollection, ScanReaders

IReaderNetwork::FindReader [in] short  sAddress,
[out, retval] IProximityReader **  ppintfReader
 

Returns the reader at a specific address.

This method returns the reader found at a specific address on this readernetwork. If no reader is found at the specified address an empty/null object is returned (and the return code will be set to 1, S_FALSE).

If ScanReaders has not yet been called, this method will scan for readers only at the requested address (calling ScanReaders(false, sAddress, sAddress)). The Readers property will then return only this found reader and nothing more.

If the ScanReaders method has been called, this method will first search the requested address inside the internal cached reader collection. If no matching reader is found in this collection, the requested address will be re-scanned for a reader.

If a new reader is found that was previously not in the internal collection, it will be added. So the new reader can also be found in the collection returned by the Readers property.

Events of processtype ptFindingReader are fired by this method. No progress events are generated ( since this method will only scan 1 address and is thus very fast). If a reader is found, an OnProcessInfo event with sub process type sptItemFound is fired with the found reader in the Info parameter.

Parameters:
sAddress The address to check (value between 0 and 255).
ppintfReader Receives the reader if it is found or NULL if not found.
Precondition:
ppintfReader is not NULL.
See also:
ScanReaders, Readers

IReaderNetwork::CheckPresence [in, defaultvalue(0)] VARIANT_BOOL  fAsync,
[in, defaultvalue(smBootloader)] ESoftwareMode  eMode,
[in, defaultvalue(0)] short  sAddress,
[in, defaultvalue(5000)] long  lTimeout,
[in, defaultvalue(0)] VARIANT_BOOL  fActivateBootloader,
[out, retval] IProximityReader **  ppintfReader
 

Periodically checks if a reader is present at a specific address.

This method will check a certain address until it finds a reader in the specified mode, or until the timeout expires. If the fActivateBootloader flag is set and a reader is found that is currently in bootloader mode, the bootloader mode will be made permanently.

If a new reader is found that was previously not in the internal collection, it will be added. So the new reader can also be found in the collection returned by the Readers property.

This method is especially useful for repairing damaged readers. When a reader is powered up, it will remain in bootloader mode for approximately 3 seconds before activating its application. When the application is damaged, the reader can not be accessed after this 3 second period. Use this method to force the reader to stay in bootloader mode after the powering up a reader.

Parameters:
fAsync Performs this method asynchronously.
eMode The software mode to check for.
sAddress The address to check (value between 0 and 255).
lTimeout The time to check for the presence of a certain reader (msec).
fActivateBootloader If set, activate the bootloader if a reader is found (when the found reader is in bootloader mode, the bootloader mode will be made permanent).
ppintfReader Receives the reader if it is found or NULL if not found.
Precondition:
ppintfReader is not NULL.
See also:
ESoftwareMode, IProximityReader::SoftwareMode, IProximityReader::InterruptBooting

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

Returns the total number of all readers that are currently connected to this network.

If this property is used before the ScanReaders method, the ScanReaders method will be called first to build the internal readers collection. Note however that all addresses will be scanned (from 0 upto 255), decreasing performance. So please call the ScanReaders method before calling this property.

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:
ScanReaders

IReaderNetwork::SetFastTimeout [in] VARIANT_BOOL  fFast  ) 
 

Set the time out value to the fast time-out.

Normally, a reader will have an internal communication time out of 1 second. Since that slows down an application considerable, this time out value is decreased to 200 milliseconds in firmware 1.64 and higher. For backwards compatibility, this API will work with a time out value of 1 second by default.

If you are sure you network holds only readers with a firmware version of 1.64 or higher, you can use this method to set the internal API time out value to 200 milliseconds. This will increase the communication performance.

When the Disconnect method or the ChangeSettings method are called, the default time out of 1 second is used again. So you have to call this method again to switch to the faster time out value.

Beware however that readers with a firmware version lower then 1.64 will unable to recover from communication errors when the fast time out value is used by the API!

Parameters:
fFast Set to true to let the API use a faster time out value to communicate with the readers.
Note:
Readers with firmware below 1.64 will be experience communication errors when the fast time out is used!
See also:
Disconnect, ChangeSettings


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