Cross Point


IProximityReader Interface Reference

Inheritance diagram for IProximityReader:

IXMLBase IEventBase List of all members.

Detailed Description

This interface represents a proximity reader.

This interface can be used to access all other reader specific interfaces and to logon to the reader.


Almost all actions require that the application is logged-on to the reader (using Logon).

The normal sequence of operations is:


Note that the auto authorize flag can be used to let the API automatically re-logon if the internal reader inactivity timer is ellapsed. This feature can be useful since the inactivity timer for a standard reader is set to 30 seconds by default. When a command fails due to an authorization failure, and the AutoAuthorize option is turned on, an automatic logon is performed and the command will be executed again.

Most methods send commands to the reader. These commands are send to the reader over the COM port. They can be send Asynchronously or Synchronously. Since communication is relatively fast, all normal messages are send synchronous by default. Long operations such as the searchin of events, the adding of user(s), erasing of the flash area's during uploading etc. are always performed asynchronously.

The functionality of the reader (IProximityReader) is divided in several logical groups. These groups are:

Further functionality of this reader object consists of the adding/removing and viewing of holidays, a locate method to easily locate a reader within a building, retrieval of various reader settings (like its versions, serial number etc), changing the readers filesystem, resetting and determining a reader's software mode.

This reader object also contains advanced search facilities to search both the user database and event database at once for certain user's and/or events.

An advanced CopyFrom method allows all users and parameters to be copied from one reader to another.

A time scheme is a feature that allows a user to customize the entry times of different user groups to be customized on a weekly basis. Fully customizable times are possible. It is for instance possible to allow a group of users access every monday morning and evening, tuesday between 9:00 and 16:15 etc. When time schemes are supported by the firmware (firmware version 1.64 or higher), the TimeSchemes property can be used to retrieve all time schemes of this reader. It is further possible to create new time schemes, remove existing time schemes, or to search for a specific time scheme.


Public Member Functions

HRESULT Network ([out, retval] IReaderNetwork **ppintfNetwork)
 Returns the reader-network where this reader is connected to.

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

HRESULT Name ([in] BSTR bstrName)
 Set the new reader name of this reader.

HRESULT SerialNumber ([out, retval] long *plSerialNumber)
 Returns the serial number of the current connected reader.

HRESULT Time ([out, retval] DATE *pDate)
 Returns the time of the real time clock in this reader.

HRESULT Time ([in] DATE Date)
 Sets the real time clock in the reader.

HRESULT NetworkAddress ([out, retval] short *psNetworkAddress)
 Return the network address of this reader.

HRESULT ChangeNetworkAddress ([in] short NewNetworkAddress,[in, defaultvalue(-1)] VARIANT_BOOL ResetNow,[in, defaultvalue(0)] VARIANT_BOOL ChangeAsync)
 Change the network address of this reader.

HRESULT Logon ([in] ELogonLevel LogonLevel,[in] long PinCode,[in, defaultvalue(1)] VARIANT_BOOL AutoAuthorize,[out, retval] VARIANT_BOOL *pfSucceeded)
 Logon a user with the given pincode and level to the reader.

HRESULT ReLogon ()
 Re-logon to the reader.

HRESULT Logoff ()
 Logoff from this reader.

HRESULT IsLoggedOn ([out, retval] VARIANT_BOOL *pfLoggedOn)
 Checks if this reader is currently logged on.

HRESULT AutoAuthorize ([out, retval] VARIANT_BOOL *pfStatus)
 Returns the current setting of the AutoAuthorized option.

HRESULT LogonLevel ([out, retval] ELogonLevel *peLogonLevel)
 Returns the current logon level.

HRESULT Reset ([in, defaultvalue(0)] VARIANT_BOOL ResetAsync,[in, defaultvalue(0)] VARIANT_BOOL ActivateBootloader,[in, defaultvalue(0)] VARIANT_BOOL DoNotPoll,[out, retval] VARIANT_BOOL *pfSucceeded)
 Reset the reader.

HRESULT IsResetting ([out, retval] ECollectingStatus *peStatus)
 Returns the status of the current resetting process.

HRESULT InterruptBooting ([out, retval] VARIANT_BOOL *pfSucceeded)
 Interrupt the booting process of this reader.

HRESULT SoftwareMode ([out, retval] ESoftwareMode *peMode)
 Reports the current software mode of the reader.

HRESULT ParameterDatabase ([out, retval] IParameterDatabase **ppintfParameterDatabase)
 Returns the object that can be used to set and get parameters, the parameter database.

HRESULT UserDatabase ([out, retval] IUserDatabase **ppintfUserDatabase)
 Returns the object that supports user manipulation and user access methods.

HRESULT EventDatabase ([out, retval] IEventDatabase **ppintfEventDatabase)
 Returns the object that supports event manipulation and event retrieval methods.

HRESULT MemoryAccess ([out, retval] IMemoryAccess **ppintfMemoryAccess)
 Returns object that can be used to set and get data directly from the reader's memory.

HRESULT AccessControl ([out, retval] IAccessControl **ppintfAccessControlOptions)
 Returns the object that can be used to set and get access control parameters.

HRESULT HardwareControl ([out, retval] IHardwareControl **ppintfHardwareControl)
 Returns the object that can be used to set and get hardware related settings.

HRESULT GetVersion ([in] EVersionType VersionType,[out, retval] short *psVersion)
 Can be used to request different version numbers of the reader.

HRESULT ExtensionBoardType ([out, retval] EExtensionBoardType *peBoardType)
 Returns the type of the current extension board (if present).

HRESULT EnableRFID ([out, retval] VARIANT_BOOL *pfEnabled)
 Returns the current status of the RFID interface (enabled or disabled).

HRESULT EnableRFID ([in] VARIANT_BOOL Enabled)
 Enable or disable the RFID interface of this reader.

HRESULT SoftwareConfiguration ([out, retval] ESoftwareConfiguration *peConfiguration)
 Returns the current embedded software configuration.

HRESULT UpgradeSoftwareConfiguration ([in] ESoftwareConfiguration eConfiguration,[in] long lUpgradeKey)
 Upgrade the reader's embedded software configuration.

HRESULT SetFileSystem ([in] short sFileSystem,[in, defaultvalue(0)] VARIANT_BOOL fSetAsync,[in, defaultvalue(0)] VARIANT_BOOL fRestoreUsersAndParameters)
 Set a new file system in this reader.

HRESULT GetProperty ([in] BSTR bstrPropertyName,[out, retval] VARIANT *pvtPropertyValue)
 Returns a property of this reader object.

HRESULT SetTurboMode ([in] EBaudrate NewBaudrate)
 Temporarily increase the baudrate of this reader.

HRESULT CopyFrom ([in] IProximityReader *pintfSourceReader,[in] ECopyFlags eFlags,[in, defaultvalue(-1)] VARIANT_BOOL fCopyAsync,[out, retval] VARIANT_BOOL *pfSucceeded)
 Copy all settings from another reader to this reader.

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 this reader.

HRESULT CancelSearch ()
 Cancel a search process that is currently in progress (only when searching asynchronous).

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

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

HRESULT ClearSearchResults ([out, retval] VARIANT_BOOL *pfSucceeded)
 Clears the last search results for this reader.

HRESULT GetSerialNumber ([in, defaultvalue(0)] VARIANT_BOOL fRefresh,[out, retval] long *plSerialNumber)
 Returns the serial number of the current connected reader.

HRESULT Locate ([out, retval] VARIANT_BOOL *pfEnabled)
 Returns true if the reader is in locate mode.

HRESULT Locate ([in] VARIANT_BOOL fEnable)
 Turns the locate mode on or off.

HRESULT Holidays ([out, retval] ICollection **ppintfHolidays)
 Returns a collection of all defined holidays.

HRESULT RemoveHolidays ()
 Removes all holidays from this reader.

HRESULT AddHolidays ([in] ICollection *pintfHolidays)
 Add a collection of holidays to this reader.

HRESULT TimeSchemes ([out, retval] ICollection **ppintfTimeSchemes)
 Returns a collection of all defined time schemes of this reader.

HRESULT CreateTimeScheme ([out, retval] ITimeScheme **ppintfTimeScheme)
 Create a new time scheme object.

HRESULT RemoveTimeScheme ([in] ITimeScheme *pintfTimeScheme)
 Remove a time scheme.

HRESULT FindTimeScheme ([in] long lTimeSchemeID,[out, retval] ITimeScheme **ppintfTimeScheme)
 Return a particular time scheme.


Member Function Documentation

IProximityReader::Network [out, retval] IReaderNetwork **  ppintfNetwork  ) 
 

Returns the reader-network where this reader is connected to.

Parameters:
ppintfNetwork Receives the network.
Precondition:
ppintfNetwork is not NULL .
Note:
This is a read-only property when used in scripting languages.
See also:
IReaderNetwork

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

Returns the name of this reader.

Parameters:
pbstrName Receives the current reader name.
Precondition:
pbstrName is not NULL.
Note:
This is the default property of this object.

IProximityReader::Name [in] BSTR  bstrName  ) 
 

Set the new reader name of this reader.

Parameters:
bstrName The new reader name.
Note:
The name cannot be longer then 23 characters.

IProximityReader::SerialNumber [out, retval] long *  plSerialNumber  ) 
 

Returns the serial number of the current connected reader.

The serial number of a reader is always unique. So this is a good property to identify readers (better then Name which can be changed by the user).

Parameters:
plSerialNumber Receives the serialnumber of the current reader.
Precondition:
plSerialNumber is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
GetSerialNumber

IProximityReader::Time [out, retval] DATE *  pDate  ) 
 

Returns the time of the real time clock in this reader.

Note that the internal clock of the reader is reset to the time of the last entry in the event-log of the reader (if it has one, else to 1-1-2000, 00:00) every time it is reset!

Parameters:
pDate The current reader time & date.
Precondition:
pDate is not NULL.
Note:
This is a read-only property when used in scripting languages.

IProximityReader::Time [in] DATE  date  ) 
 

Sets the real time clock in the reader.

Note that the internal clock of the reader is reset to the time of the last entry in the event-log of the reader (if it has one, else to 1-1-2000, 00:00) every time it is reset!

Parameters:
date The new reader time & date.

IProximityReader::NetworkAddress [out, retval] short *  psNetworkAddress  ) 
 

Return the network address of this reader.

Return values:
psNetworkAddress Receives the current network address of this reader.
Precondition:
psNetworkAddress is not NULL.
Note:
This is a read-only property when used in scripting languages.

IProximityReader::ChangeNetworkAddress [in] short  sNewNetworkAddress,
[in, defaultvalue(-1)] VARIANT_BOOL  fResetNow,
[in, defaultvalue(0)] VARIANT_BOOL  fChangeAsync
 

Change the network address of this reader.

The address will only be set after the next reset of the reader. So to activate the changed network address, reset the reader (using the Reset method) or use the fResetNow argument.

This method can be executed asynchronously by setting the fChangeAsync flag to true.

This method will generate all default events of processtype ptChangingNetworkAddress. No progress message will be generated during this process. When the fResetNow flag is set, the Reset method will be executed after the network address is changed, this will cause all reset events to be fired as sub process events of this process. See the Reset method for more information about the fired events.

Since this method uses the nvpNetworkAddress parameter to change the network address, a sub process type sptItemAdded or sptItemModified of processtype ptParameterdatabaseChange might be fired on the parameter database during this method.

Note that the address cannot be set to an address that is already in use by another reader in the same network. This method will check if this is the case, if so it will generate and error (E_INVALIDARG).

Parameters:
sNewNetworkAddress The new network address for this reader.
fResetNow If set to true, a reset will be performed automatically.
fChangeAsync When this flag is set to true, the changing of the network address will be performed asynchronously.
See also:
NetworkAddress, Reset

IProximityReader::Logon [in] ELogonLevel  eLevel,
[in] long  lPassword,
[in, defaultvalue(1)] VARIANT_BOOL  fAutoAuthorize,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Logon a user with the given pincode and level to the reader.

Logon to this reader. This method should be called first before any other operation is done on this reader.

Use the eLevel argument to specify the required logon level. Depending on this level, the user is allowed or disallowed to perform certain actions. An installer might for instance change the filesystem of a reader, a user cannot change it.

Every reader has an internal inactivity timer, if there is no communication for a certain period of time with the reader, it will automatically log out. The inactivity time for a standard reader is set to 30 seconds by default. When logged-out, every message send to the reader will fail with a E_NOTAUTHORIZED return code.

When a command fails due to an authorization failure and the AutoAuthorize option is turned on, an automatic logon is performed, and the command is resend automatically. If the AutoAuthorize option is turned off, the easiest way to re-establish communication is to use the ReLogon method. Turn the AutoAuthorize option on by setting the fAutoAuthorize argument of this method to true.

Note that the IsLoggedOn property will always return logged-on when the Logon method is succesfully called. It is not affected by the inactivity-timer. With other words, the property can not be used to determine if the reader itself is logged-out.

Parameters:
eLevel The requested logon level.
lPassword The password/accesscode for this reader.
fAutoAuthorize If set to true, this object automatically logs on again if the readers inactivity timer elapses.
pfSucceeded Will be set to true if the logon process succeeds, false if the process fails. A failure almost always indicates an incorrect password.
Precondition:
pfSucceeded Is not NULL.
Note:
The default password for both user and installer level is: 123456789.
See also:
IsLoggedOn, Logoff, ReLogon

IProximityReader::ReLogon  ) 
 

Re-logon to the reader.

Tries to re-logon to a reader with the password and level that were passed to the Logon method.

Precondition:
Logon should be called before this method can be called.
See also:
Logon, Logoff, IsLoggedOn

IProximityReader::Logoff  ) 
 

Logoff from this reader.

Precondition:
The reader should be logged on.
Note:
Almost all communication with this reader will fail after the reader is logged-off (with the exception of Logon, Name and SerialNumber, GetVersion).
See also:
Logon, IsLoggedOn, ReLogon

IProximityReader::IsLoggedOn [out, retval] VARIANT_BOOL *  pfLoggedOn  ) 
 

Checks if this reader is currently logged on.

Parameters:
pfLoggedOn Receives true if the reader is currently logged on.
Precondition:
pfLoggedOn is not NULL
Note:
Note that the IsLoggedOn property will always return true after the Logon method is succesfully called. It is not affected by the inactivity-timer. With other words, the property can not be used to determine if the reader itself logged-out.

This is a read-only property when used in scripting languages.

See also:
Logon, Logoff, ReLogon

IProximityReader::AutoAuthorize [out, retval] VARIANT_BOOL *  pfAutoAuthorize  ) 
 

Returns the current setting of the AutoAuthorized option.

Can be used to check what the current setting of the AutoAuthorized option is. AutoAuthorize can be turned on using the fAutoAuthorize flag in the Logon method.

Parameters:
pfAutoAuthorize Receives true if the AutoAuthorize flag was set during the Logon.
Precondition:
pfAutoAuthorize is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Logon

IProximityReader::LogonLevel [out, retval] ELogonLevel peLevel  ) 
 

Returns the current logon level.

Returns the logon-level that was passed to the Logon method.

Parameters:
peLevel Receives the current logon level.
Precondition:
peLevel is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ELogonLevel, Logon

IProximityReader::Reset [in, defaultvalue(0)] VARIANT_BOOL  fResetAsync,
[in, defaultvalue(0)] VARIANT_BOOL  fActivateBootloader,
[in, defaultvalue(0)] VARIANT_BOOL  fDoNotPoll,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Reset the reader.

This method can be used in two different ways. When reseting asynchronously, this method will start resetting the reader and return immediately. The application is then free to perform other tasks while waiting for the reset to finish. The property IsResetting can be used to determine if the resetting process has finished. Another way is to reset synchronously, this method will then block until the reader has finished resetting.

The default events of processtype ptResetting are fired by this method. Progress events are also fired.

After a reset, the reader will be logged off. For executing new reader operations after the reset a new Logon is required. However, if the AutoAuthorize option is turned on, the logon will be performed automatically.

When changing parameters (see IParameterDatabase), some parameters require a reset to activate the changes. To determine what parameter require a reset, refer to the IParameter::IsResetRequired property.

If the fActiveBootloader flag is set, the reader will be reset and after the reset, the reader will not start its Application but remain in bootloader mode. This is a mode that is required for for instance uploading new firmware (the IMemoryAccess::UploadFirmware method however, can also perform the switching to bootloader mode automatically).

The SoftwareMode property can be used to determine if the reader is in bootloader mode or normal application mode.

Parameters:
fResetAsync When set to true, the reset operation is done in the background.
fActivateBootloader When set to true, the reader will be put in bootloader mode after the reset.
fDoNotPoll If this argument set to true, a reset command will be send to the reader and this method will return immediately, it will not wait for the reader to finish resetting. This parameter is ignored when the fResetAsync flag is set.
pfSucceeded Set to true when the reset process has completed successfully (only when resetting synchronously).
Warning:
This method may take a lot of time, so asynchronous resetting is preferred.
See also:
IsResetting, InterruptBooting

IProximityReader::IsResetting [out, retval] ECollectingStatus peStatus  ) 
 

Returns the status of the current resetting process.

When resetting, this method will return csBusy. When finished, it will return csReady.

Parameters:
peStatus Set to the status of the current reset operation.
Note:
This is a read-only property when used in scripting languages.
See also:
Reset

IProximityReader::InterruptBooting [out, retval] VARIANT_BOOL *  pfSucceeded  ) 
 

Interrupt the booting process of this reader.

If the reader is corrupt, and the reset functionality no longer works, the reader can be powered down. After power up, this method should be called immediately (within 2 seconds). This method will cause the reader to skip loading its firmware, it will thus stay in bootloader mode (in bootloader mode, the firmware can be repaired). In bootloader mode, the reader has limited functionality. Use the SoftwareMode property to determine if the reader is in bootloader mode or normal application mode.

Parameters:
pfSucceeded Set to true if the booting process has been successfully interrupted.
Warning:
When the reader is in bootloader mode only a very limited number of methods and properties can be used successfully, all other methods and properties will return the not-authorized error code.
See also:
Reset, SoftwareMode, IMemoryAccess::UploadFirmware

IProximityReader::SoftwareMode [out, retval] ESoftwareMode peMode  ) 
 

Reports the current software mode of the reader.

This method can be used to determine the current software mode of the reader. Since it is a very fast method (and no logon is required), it can also be used to determine if a reader is responds to a certain address (it is used internally in the IReaderNetwork::ScanReaders method).

Parameters:
peMode Receives the current software mode of the reader (XM2 compatible, bootloader or application mode).
Precondition:
peMode is not NULL.
Note:
A Logon is not required for this method.

This is a read-only property when used in scripting languages.

Warning:
When the reader is in bootloader mode only a very limited number of methods and properties can be used successfully, all other methods and properties will return a not-authorized error code.

IProximityReader::ParameterDatabase [out, retval] IParameterDatabase **  ppintfParameterDatabase  ) 
 

Returns the object that can be used to set and get parameters, the parameter database.

Note that the parameterdatabase object is cached internally in this reader object.

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

IProximityReader::UserDatabase [out, retval] IUserDatabase **  ppintfUserDatabase  ) 
 

Returns the object that supports user manipulation and user access methods.

Note that the userdatabase object is cached internally in this reader object.

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

If the reader is configured as a basic or default reader, no user database is present on the reader, this property will return nothing.

See also:
IUserDatabase

IProximityReader::EventDatabase [out, retval] IEventDatabase **  ppintfEventDatabase  ) 
 

Returns the object that supports event manipulation and event retrieval methods.

Note that the usersdatabase object is cached internally in this reader object.

When the current file-system of this reader does not support events, this property will return an empty object (file-systems 0, 1, 4 and 5 do not support events).

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

If the reader is configured as a basic or default reader, no event database is present on the reader, this property will then return nothing.

See also:
IEventDatabase

IProximityReader::MemoryAccess [out, retval] IMemoryAccess **  ppintfMemoryAccess  ) 
 

Returns object that can be used to set and get data directly from the reader's memory.

The memory access object also contains the upload functionality to upload new firmware into the reader.

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

IProximityReader::AccessControl [out, retval] IAccessControl **  ppintfAccessControl  ) 
 

Returns the object that can be used to set and get access control parameters.

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

IProximityReader::HardwareControl [out, retval] IHardwareControl **  ppintfHardwareControl  ) 
 

Returns the object that can be used to set and get hardware related settings.

Parameters:
ppintfHardwareControl Receives the IHardwareControl interface.
Precondition:
ppintfHardwareControl is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IHardwareControl

IProximityReader::GetVersion [in] EVersionType  eVersionType,
[out, retval] short *  psVersion
 

Can be used to request different version numbers of the reader.

Parameters:
eVersionType The requested version number.
psVersion Receives the requested version number (when it is set to 125, the value should be interpreted as version 1.25).
Precondition:
psVersion is not NULL.

IProximityReader::ExtensionBoardType [out, retval] EExtensionBoardType peBoardType  ) 
 

Returns the type of the current extension board (if present).

Parameters:
peBoardType Receives a current extension board type.
Precondition:
peBoardType is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
EExtensionBoardType

IProximityReader::EnableRFID [out, retval] VARIANT_BOOL *  pfEnabled  ) 
 

Returns the current status of the RFID interface (enabled or disabled).

Parameters:
pfEnabled Receives the current state of the RFID interface.
Precondition:
pfEnabled is not NULL.

IProximityReader::EnableRFID [in] VARIANT_BOOL  fEnable  ) 
 

Enable or disable the RFID interface of this reader.

The RFID interface is disabled internally when saving parameters. This is done to prevent a keypad programmer from modifying a parameter while this API is also modifying the same parameter. To increase performance, the RFID interface is also disabled when collecting users, events, adding users etc. This is done because presenting a card while the API is collecting users, will slow down the collection process considerable.

Parameters:
fEnable Set to true to enable the interface, false to disable.
Warning:
When the RFID interface is disabled, the reader will not respond to any cards, programmers or keypad's that are held in the range of the reader!

IProximityReader::SoftwareConfiguration [out, retval] ESoftwareConfiguration peConfiguration  ) 
 

Returns the current embedded software configuration.

For more information about upgrading the embedded software to a new configuration, see UpgradeSoftwareConfiguration.

Parameters:
peConfiguration Receives the current software configuration.
Precondition:
peConfiguration is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ESoftwareConfiguration, UpgradeSoftwareConfiguration

IProximityReader::UpgradeSoftwareConfiguration [in] ESoftwareConfiguration  eConfiguration,
[in] long  lUpgradeKey
 

Upgrade the reader's embedded software configuration.

The embedded software in the reader can be configured in three different ways:

  • Default configuration (scDefault), very limited functionality, no databases.
  • Basic configuration (scBasic), no user and event database, only a few parameters supported.
  • Advanced configuration (scAdvanced), all functionality supported except some stand-alone specific functions.
  • Stand alone configuration (scStandAlone), all functionality supported.
Upon successful completion of the operation, the reader will first transmit the result of the operation. Next, it will automatically reset itself to activate the new software configuration. After the reset, the new software configuration can be verified by using the SoftwareConfiguration property.

Parameters:
eConfiguration The requested new configuration of the software.
lUpgradeKey The required key for upgrading the software.
Note:
Required authorization level: Installer.

For security reasons this operation will be disabled after 3 failing attempts (due to invalid key). The reader will have to be powered down before another attempt can be made.

See also:
ESoftwareConfiguration, SoftwareConfiguration

IProximityReader::SetFileSystem [in] short  sFileSystem,
[in, defaultvalue(0)] VARIANT_BOOL  fSetAsync,
[in, defaultvalue(0)] VARIANT_BOOL  fRestoreUsersAndParameters
 

Set a new file system in this reader.

This method will automatically reset the reader to stabilize drivers and interfaces for the changes that may have resulted from the new file system configuration.

The default events of processtype ptSettingFileSystem are fired by this method including progress events. After the filesystem has been set successful, this method will perform a reset. The reset events will be fired as sub process of this ptSettingFileSystem process.

Note that using the fSetAsync argument it is possible to set the filesystem asynchronously. The application is then free to perform other tasks while waiting for this method to finish.

To retrieve the current filesystem, use the GetProperty method with "FileSystem" as argument.

Changing the filesystem will clear all users, events, parameters, holidays, user groups and timeschemes of the reader, so backup those settings. When the fRestoreUsersAndParameters flag is set, the backup of users, parameters and holidays will be performed automatically. Events, users groups and timeschemes however will be cleared!

When the fRestoreUsersAndParameters flag is set, all users, parameters and holidays will be collected before the filesystem is set, this will fire all events of the IUserDatabase::CollectUsers, IParameterDatabase::CollectParameters and the IProximityReader::Holidays methods as sub process events of the ptSettingFileSystem process.

Parameters:
sFileSystem The new filesystem type (see master manual).
fSetAsync Set the new filesystem asynchronously.
fRestoreUsersAndParameters When this flag is set, all users and parameter setting will be restored after the file system has been reset (all events however will be destroyed!).
Note:
Required authorization level: Installer.

Does not work in basic configuration (since basic mode does not support a file system).

Warning:
This will erase the entire reader filesystem, including the user database!!!, all parameters!!! ,all events, holidays, user groups and timeschemes!!! So be sure to back-up all settings and users before performing this function! Or use the fRestoreUsersAndParameters flag to automatically backup users, parameters and holidays.
See also:
GetProperty, Reset

IProximityReader::GetProperty [in] BSTR  bstrPropertyName,
[out, retval] VARIANT *  pvtPropertyValue
 

Returns a property of this reader object.

Currently the following properties can be retrieved using this method:

  • FileSystem Returns the current filesystem configuration (see master manual for more information).
  • MaxUsers Returns the maximum number of users this reader can hold.
  • CurrentUsers Returns the current number of users.
  • MaxEvents Returns the maximum number of events this reader can hold.
  • CurrentEvents Returns the current number of events.
  • SupportNames Returns true if the filesystem supports user names, false if not supported.
  • SupportPincodes Returns true if the filesystem supports user pincodes, false if not supported.
  • SupportValidPeriod Returns true if the filesystem supports valid periods for users, false if not supported.
  • SupportUsergroups Returns true if the filesystem supports user groups, false if not supported.
  • BootloaderVersion Returns the version of the bootloader (see GetVersion).
  • OSVersion Returns the version of the OS (see GetVersion).
  • ApplicationVersion Returns the version of the application (see GetVersion).
  • HardwareVersion Returns the version of the hardware (see GetVersion).
  • ExtensionBoardVersion Returns the version of the extension board (see ExtensionBoardType).
  • ReaderLevel Returns the current reader level (Installer = 0 or User = 1)
  • ReaderCardOptions Returns the reader card options (if bit 1 is set, this reader can only read specific EM-Marin cards)
  • BypassOptions Returns the reader bypass options (if bit 1 is set, the reader is bypassed) Pass for instance the string "OSVersion" as bstrPropertyName argument to receive the current version of the operating system of this reader in the pvtPropertyValue argument.
Parameters:
bstrPropertyName The name of the property that should be retreived.
pvtPropertyValue Receives the value of the property.

IProximityReader::SetTurboMode [in] EBaudrate  eNewBaudrate  ) 
 

Temporarily increase the baudrate of this reader.

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!

IProximityReader::CopyFrom [in] IProximityReader pintfSourceReader,
[in] ECopyFlags  eFlags,
[in, defaultvalue(-1)] VARIANT_BOOL  fCopyAsync,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Copy all settings from another reader to this reader.

This method can be used to copy users and/or holidays and/or parameters from one reader into this reader. When the cfClearUsers flag is specified, all user in this reader will be cleared first, before the users of the source reader are copied to it (only applicable when also specifying cfUsers). If the cfClearUsers flag is not set, and users are copied, users who's cardnumbers match will be automatically overwritten.

The cfFileSystem will set the filesystem of this reader to the same filesystem as the source reader, use this option with care, since it deletes ALL users, holidays, events, parameters etc. of this reader (see SetFileSystem for more information).

The events fired by this method are of processtype ptCopyFrom. The following events are fired (in this order):

  • When the cfFileSystem is specified, all events fired by the SetFileSystem method are fired as sub process of this process.
  • If the cfParameters flag is used, the events generated by the IParameterDatabase::CollectParameters are fired on the source reader.
  • If the cpParameters flag is specified, the IParameterDatabase::Parameters property is used to set the parameters of this reader, read the IParameterDatabase::Parameters property documentation more information about its events.
  • The cfUsers flag will first call the IUserDatabase::CollectUsers method. All events of that method will be fired on the userdatabase object of the source reader.
  • If the cfClearUsers flag is used, the IUserDatabase::Clear method will be called. Read the documentation of that method to see what events are fired on this reader's userdatabase.
  • The cfUsers flag also causes the IUserDatabase::Users property of this reader to be called. Read the documentation of that method to see what events are fired.
  • When the cfHolidays flag is specified, this method will use the Holidays property to retrieve the holiday collection of the source reader. See the Holidays documentation for detailed information.
  • The cfHolidays flag will further call the RemoveHolidays method of this reader, causing that methods events to be fired as sub process of this method.
  • When the cfHolidays flag is used, the last step will be to add the holidays to this reader using AddHolidays method. The events fired by the AddHolidays method are thus fired as sub process events of this method.
  • If the parameters are copied (the cfParameters flag is set), this reader will be reset as the final step in the copy process. This is done since some parameters require a reset to be activated. All events fired by the Reset method are thus also fired as sub process of this method.
When copying parameters, the networkaddress and readername parameters are not copied to this reader to avoid double network addresses and names on the same network.

When for instance copying users from another reader to this reader, all users of the source-reader are automatically retrieved, if they are not already collected. The next step will be to retrieve all users of this reader's userdatabase. Next the users are copied using the IUserDatabase::Users property.

Parameters:
pintfSourceReader The source reader where of the data should be copied from.
eFlags The flags for this copy operation (can be or-ed together).
fCopyAsync Perform the copy action asynchronously.
pfSucceeded Set to true when the copy opertion finished successful (only when fCopyAsync flag is false).
See also:
SetFileSystem

IProximityReader::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 this reader.

Perform a search operation on this reader. The collection containing all search results can be retrieved using the SearchResults property.

If the sfUsers flag is specified, the IUserDatabase::SearchUsers method will be called to execute the search in the userdatabase. If the sfEvents flag is specified, the IEventDatabase::SearchEvents method will be called to execute the search in the eventdatabase. When both flags are specified, the search results will be combined. Note that the resulting collecting will then contain both IUser and IEvent objects!

When the sfSearchAsync is set in the eFlags argument, the search is 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 completed. 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. When searching events, the sptSearchingEvents sub process events are fired. 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). See the documentation of IUserDatabase::SearchUsers and IEventDatabase::SearchEvents for more information.

Note that the last search-results will be cached inside the databases to increase performance. To clear the search results of this reader, use the ClearSearchResults method or specify the sfClearResults flag when searching again.

All arguments (except the eFlags argument) are optional, you do not have to provide them (for C++ programmers, simply set the VARIANT to VT_EMPTY). Only the arguments that are provided will influence the search results.

Parameters:
eFlags Searchflags, specifying the search type to perform (may be or-ed together).
vtUser This parameter may contain:
  • A IUser object (with either a correct ID or a correct username).
  • A string containing the ID that should be searched. This id-string should be in the following form: ~Cardtype~Facility~Number~.
  • A string with a (part) of the username where we should search for.
vtRange This parameter may hold a 4 byte integer.
vtStartDate This parameter may hold a start date/time from where the events should be searched.
vtEndDate This parameter may hold a end date/time. Only events before this date will be searched.
pfSucceeded Receives true if the search process finished successful (only when searching synchronously).
See also:
SearchStatus, SearchResults, CancelSearch, ClearSearchResults

IProximityReader::CancelSearch  ) 
 

Cancel a search process that is currently in progress (only when searching asynchronous).

See also:
Search, SearchStatus, SearchResults

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

Returns the collection of all search results.

When both the userdatabase and the eventdatabase have been searched, the results of both databases will be merged. The returned collection can thus contain both IUser and/or IEvent objects!

Only returns valid data when this reader is finished searching. Check the search status of this reader using the SearchStatus property.

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.

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

See also:
Search, SearchStatus, CancelSearch, ClearSearchResults, IUser, IEvent, ICollection

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

Returns the status of the search process.

The status is determined by combining the search status of the userdatabase (if searched) and the status of the eventdatabase (if searched).

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

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

Clears the last search results for this reader.

This method will call both the IUserDatabase::ClearSearchResults method and IEventDatabase::ClearSearchResults.

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

IProximityReader::GetSerialNumber [in, defaultvalue(0)] VARIANT_BOOL  fRefresh,
[out, retval] long *  plSerialNumber
 

Returns the serial number of the current connected reader.

The serial number of a reader is always unique. The difference between this method and the SerialNumber property is that this method can be instructed to refresh the serial number by requesting it from the reader. The SerialNumber property will return the internally cached number.

Parameters:
fRefresh Refresh the serial number by retrieving it from the reader.
plSerialNumber Receives the serialnumber of the current reader.
Precondition:
plSerialNumber is not NULL.
See also:
SerialNumber

IProximityReader::Locate [out, retval] VARIANT_BOOL *  pfEnabled  ) 
 

Returns true if the reader is in locate mode.

This method returns true if the reader is in locate mode. When a reader is in locate mode, the LEDs are flashing and the buzzer beeps to enable a user to locate the reader within a facility.

Parameters:
pfEnabled Receives true if the reader is in locate mode.

IProximityReader::Locate [in] VARIANT_BOOL  fEnabled  ) 
 

Turns the locate mode on or off.

Set this property to true to set the reader in locate mode. When in locate mode, all LEDs of the reader are flashing and the buzzer beeps enabling a user to locate this reader within the facility.

Parameters:
fEnabled Set to true to enable locate mode or false to set the reader to normal operational mode.

IProximityReader::Holidays [out, retval] ICollection **  ppintfHolidays  ) 
 

Returns a collection of all defined holidays.

This method returns all the defined holidays for this reader. All default events of processtype ptCollectingHolidays are fired by this method. For every collected holiday the OnProcessInfo event is fired (sub process type sptItemFound) with the found holiday in the Info argument.

Parameters:
ppintfHolidays Receives the collection with holidays.
Precondition:
ppintfHoliday may not be NULL.
Note:
This is a read-only property in scripting languages.

Holidays are supported in readers with a firmware version of 1.62 or higher.

See also:
RemoveHolidays, AddHolidays

IProximityReader::RemoveHolidays  ) 
 

Removes all holidays from this reader.

This method removes all the defined holidays from this reader. The default events of processtype ptRemovingHolidays are fired including progress events.

Note:
Holidays are supported in readers with a version of 1.62 or higher.
See also:
Holidays, AddHolidays

IProximityReader::AddHolidays [in] ICollection pintfHolidays  ) 
 

Add a collection of holidays to this reader.

This method adds a collection of holidays to this reader. This collection must be sorted by startdate, this means that the holiday with the smallest startdate should be the first item in the collection (see the ICollection::Sort for information about sorting a collection). A holiday may not overlap another holiday.

Default events of processtype ptAddingHolidays are fired including progress events.

Parameters:
pintfHolidays The sorted collection with holidays.
Note:
Holidays are supported in readers with a version of 1.62 or higher.

After uploading the new firmware for the first time, you have to change the filesystem of your reader to support holidays! Changing the filesystem will create the holiday database in your reader! When you do not change the filesystem, adding new holidays will fail!

See also:
RemoveHolidays, Holidays

IProximityReader::TimeSchemes [out, retval] ICollection **  ppintfTimeSchemes  ) 
 

Returns a collection of all defined time schemes of this reader.

This method returns all the defined time schemes of this reader. All normal events of processtype ptCollectingTimeSchemes are fired by this method. For every collected time scheme the OnProcessInfo event is fired (sub process type sptItemFound) with the found time scheme object in the Info argument.

Parameters:
ppintfTimeSchemes Receives the collection with time schemes.
Precondition:
ppintfTimeSchemes may not be NULL.
Note:
This is a read-only property in scripting languages.

Time schemes are supported in readers with a firmware version of 1.63 or higher. Time schemes will only work if the filesystem of the reader is set to 16 or 17 (see SetFileSystem).

See also:
ITimeScheme, CreateTimeScheme, RemoveTimeScheme

IProximityReader::CreateTimeScheme [out, retval] ITimeScheme **  ppintfTimeScheme  ) 
 

Create a new time scheme object.

When adding a new time scheme, use this method to create a new time scheme object, then set all properties of the time scheme and finally call the ITimeScheme::Save method. See ITimeScheme::Save for more information.

Parameters:
ppintfTimeScheme Receives an newly created empty time scheme object.
Precondition:
ppintfTimeScheme is not NULL.
Note:
Time schemes are supported in readers with a firmware version of 1.63 or higher. Time schemes will only work if the filesystem of the reader is set to 16 or 17 (see SetFileSystem).
See also:
ITimeScheme, TimeSchemes, RemoveTimeScheme, ITimeScheme::Save

IProximityReader::RemoveTimeScheme [in] ITimeScheme pintfTimeScheme  ) 
 

Remove a time scheme.

This method removes a specific time scheme.

Parameters:
pintfTimeScheme The time scheme that should be removed.
Note:
Time schemes are supported in readers with a firmware version of 1.63 or higher. Time schemes will only work if the filesystem of the reader is set to 16 or 17 (see SetFileSystem).
See also:
ITimeScheme, TimeSchemes, CreateTimeScheme

IProximityReader::FindTimeScheme [in] long  lTimeSchemeID,
[out, retval] ITimeScheme **  ppintfTimeScheme
 

Return a particular time scheme.

This method returns a time scheme with the specific ID (or an empty object if the time scheme is not found in this reader). The return code of this method is set to 1 (S_FALSE) when a timescheme with the specified ID is not found.

Parameters:
lTimeSchemeID ID of the requested time scheme.
ppintfTimeScheme Receives the time scheme with the specified ID.
Note:
Time schemes are supported in readers with a firmware version of 1.63 or higher. Time schemes will only work if the filesystem of the reader is set to 16 or 17 (see SetFileSystem).
See also:
ITimeScheme, TimeSchemes, CreateTimeScheme


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