Cross Point


IUserDatabase Interface Reference

Inheritance diagram for IUserDatabase:

IXMLBase IEventBase List of all members.

Detailed Description

This interface handles all user database related functionality.

The user database is the database inside the reader that holds all card information, user names, valid periods, usergroup etc. Depending on the filesystem (see IProximityReader::SetFileSystem), the following items are stored in this database:

It is for instance possible to select a filesystem that doesn't support names and/or pincodes (only IDs). See Configuration for more details.

The number of users that the user database can hold also depends on the selected filesystem (see IProximityReader::SetFileSystem) of the reader. Use the Size property to determine the maximum number of users for the current filesystem.

The users can be retrieved from the database using the CollectUsers method. When this method is finished, the entire collection of users can be retrieved using the Users property. It is possible to collect the users asynchronously using a flag in the CollectUsers method. The IsCollectingUsers property can then be used to check if the asynchronous process has finished collecting all users. The asynchronous collect process can be canceled using the CancelCollectingUsers method. Note that while collecting users, events are fired that can be used to show the progress or perform other tasks (see the CollectUsers method for detailed information).

The FindUser method is a simplified method to retrieve a single user.

To edit an existing user, simply modify the IUser object and call the IUser::Save method. Adding a new user can be done by first creating a new IUser object using the CreateUser method. Fill in the user details on the returned IUser object, call the IUser::Save method.

When saving a newly created user who's ID is already inside the user database, the existing user's information will be overwritten with the new information. All IDs in the user database are unique.

The adding, removing and changing of all users in the user database can be monitored using the general events of processtype ptUserdatabaseChange. When a new user is added to the user database, or users are collected for the first time, an OnProcessInfo event of processtype ptUserdatabaseChange is fired with the sptItemAdded sub process type. If a existing user is modified, the sub process type will be sptItemModified. If a user is removed, the sub process type will be sptItemRemoved. The Info argument of all those events will contain the related user object (IUser).

The user database also contains advanced search facilities to search users. Users can be search by id, (or part of) a name or a range of levels (for instance: search all AddMasters).

All users currently in the database can be saved to disk using the IXMLBase::Download method. It is also possible to upload a previously saved file into the reader using the IXMLBase::Upload method. The user data can be saved to an HTML file, XML file or to a comma separated file (.CSV). These .CSV files can be easily imported and exported into/from Excel.

For more information about methods and properties, see the detailed sections of each method and property.

Warning:
All user database methods and properties are not supported in basic configuration.


Public Member Functions

HRESULT Reader ([out, retval] IProximityReader **ppintfReader)
 Returns the reader this user database belongs to.

HRESULT Count ([out, retval] long *plCount)
 Retrieves the number of users currently in the reader's user database.

HRESULT Size ([out, retval] long *plSize)
 Retrieve the total number of users that can be stored in the user database.

HRESULT IsEmpty ([out, retval] VARIANT_BOOL *pfEmpty)
 Returns true if the userdatabase is empty.

HRESULT Configuration ([out, retval] EUserConfiguration *peConfiguration)
 Retrieves the user configuration of the database.

HRESULT CollectUsers ([in, defaultvalue(0)] VARIANT_BOOL CollectAsync,[in, defaultvalue(ulNormalUser)] EUserLevel LowLevel,[in, defaultvalue(ulInstallerProgrammer)] EUserLevel HighLevel,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID,[out, retval] long *plUsers)
 Collect all users.

HRESULT IsCollectingUsers ([out, retval] ECollectingStatus *peStatus)
 Returns the status of the asynchronous user collecting process.

HRESULT CancelCollectingUsers ()
 Cancel an asynchronous collection process that is currently in progress.

HRESULT Users ([out, retval] ICollection **ppintfUsers)
 Returns the internal collection of all users.

HRESULT Users ([in] ICollection *pintfUsers)
 Adds new users into this reader.

HRESULT CreateUser ([out, retval] IUser **ppintfUser)
 Create a new user object.

HRESULT Remove ([in] ECardType ECardType,[in] BSTR bstrCardNumber,[in, defaultvalue("")] BSTR bstrFacility,[in, defaultvalue(0xffff)] VARIANT_BOOL fDisableRFID,[out, retval] VARIANT_BOOL *pfSucceeded)
 Remove a user from the userdatabase.

HRESULT Clear ([in, defaultvalue(0)] VARIANT_BOOL ClearAsync,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID)
 Remove all users from the user database.

HRESULT RemoveExpiredUsers ([in, defaultvalue(0)] VARIANT_BOOL ClearAsync,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID)
 Remove all expired users from the user database.

HRESULT FindUser ([in] ECardType CardType,[in] BSTR bstrCardNumber,[in, defaultvalue("")] BSTR bstrFacility,[out, retval] IUser **ppintfUser)
 Search for a particular user, if found, returns the found user object.

HRESULT SearchUsers ([in] ESearchFlags eFlags,[in] VARIANT User,[in, defaultvalue(0)] VARIANT LevelRange,[in, defaultvalue(0)] VARIANT Reserved1,[in, defaultvalue(0)] VARIANT Reserved2,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID,[out, retval] VARIANT_BOOL *pfSucceeded)
 Search a specific user or users that match certain search criteria.

HRESULT CancelSearch ()
 Cancel a search process that is currently in progress.

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

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

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

HRESULT GetSearchResults ([in] ESearchFlags eFlags,[out, retval] ICollection **ppintfResults)
 Returns an internal collection of searched results.

HRESULT UserGroups ([out, retval] ICollection **ppintfUserGroups)
 Returns a collecting of all usergroups.

HRESULT CreateUserGroup ([out, retval] IUserGroup **ppintfUserGroup)
 Create a new user group object.

HRESULT RemoveUserGroup ([in] IUserGroup *pintfUserGroup)
 Remove an existing user group.

HRESULT FindUserGroup ([in] long lID,[out, retval] IUserGroup **ppintfUserGroup)
 Return a user group with the specific ID.


Member Function Documentation

IUserDatabase::Reader [out, retval] IProximityReader **  ppintfReader  ) 
 

Returns the reader this user database belongs to.

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

IUserDatabase::Count [out, retval] long *  plCount  ) 
 

Retrieves the number of users currently in the reader's user database.

Parameters:
plCount Receives the number of users in the database.
Precondition:
plCount is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Size, IsEmpty

IUserDatabase::Size [out, retval] long *  plSize  ) 
 

Retrieve the total number of users that can be stored in the user database.

The size returned here is a mimimum size. Due to variance in memory requirements for user objects, more users then returned by this method might be added to the userdatabase.

Parameters:
plSize Returns the minimum number of users that this database can hold.
Precondition:
plSize is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Count, IsEmpty

IUserDatabase::IsEmpty [out, retval] VARIANT_BOOL *  pfEmpty  ) 
 

Returns true if the userdatabase is empty.

Parameters:
pfEmpty Returns true if the user database is empty.
Precondition:
pfEmpty is not NULL
Note:
This is a read-only property when used in scripting languages.
See also:
Count, Size

IUserDatabase::Configuration [out, retval] EUserConfiguration peConfiguration  ) 
 

Retrieves the user configuration of the database.

This method can be used to check whether the current filesystem supports a user database with IDs and/or PinCodes and/or Names, etc.

Parameters:
peConfiguration Returns the current configuration. The configuration can be or-ed together.
Precondition:
peConfiguration is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
EUserConfiguration

IUserDatabase::CollectUsers [in, defaultvalue(0)] VARIANT_BOOL  fCollectAsync,
[in, defaultvalue(ulNormalUser)] EUserLevel  eLowLevel,
[in, defaultvalue(ulInstallerProgrammer)] EUserLevel  eHighLevel,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID,
[out, retval] long *  plUsers
 

Collect all users.

This method creates an internal collection with all users currently available in this reader and returns the number of found users. To get the collection, use the Users property.

A collection with all users is created. This collection is cached internally for future use.

Only users that have a userlevel between eLowLevel and eHighLevel are added to the collection.

It is possible to collect the users asynchronously using a fCollectAsync flag. The IsCollectingUsers property can be used to check if the process has finished collecting all users. The collect process can be canceled using the CancelCollectingUsers method.

All default events (including progress events) of processtype ptCollectingUsers or fired by this method. When a new user is collected, the OnProcessInfo will be fired with the sptItemFound sub process type. The found IUser object is passed in the Info argument.

Parameters:
fCollectAsync When set to true, the collecting is performed asynchrously.
eLowLevel The low user level, only user with a user level equal or higher then this level will be collected.
eHighLevel The high user level, only user with a user level equal or lower then this level will be collected.
fDisableRFID Disable the RFID interface while collecting the users (it is recommended to set this to true).
plUsers Receives the number of users found (only when fCollectAsync is false).
Note:
The RFID interface will be disabled during this process. This is done to increase performance, when a card is presented during the collecting process, the collecting process slows down considerable.
See also:
Users, IsCollectingUsers, CancelCollectingUsers, IUser, Count

IUserDatabase::IsCollectingUsers [out, retval] ECollectingStatus peStatus  ) 
 

Returns the status of the asynchronous user collecting process.

Parameters:
peStatus Receives the status of the collecting process.
See also:
CollectUsers, CancelCollectingUsers, Users

IUserDatabase::CancelCollectingUsers  ) 
 

Cancel an asynchronous collection process that is currently in progress.

See also:
CollectUsers, IsCollectingUsers, Users

IUserDatabase::Users [out, retval] ICollection **  ppintfUsers  ) 
 

Returns the internal collection of all users.

If the CollectUsers method is not yet called, this property will fail. So please call the CollectUsers method first before calling this property.

Parameters:
ppintfUsers Receives a collection of all users.
Precondition:
ppintfUsers is not NULL.
See also:
CollectUsers, IUser, IsCollectingUsers, CancelCollectingUsers

IUserDatabase::Users [in] ICollection pintfUsers  ) 
 

Adds new users into this reader.

If a user from the new user collection is not found in this reader, it is added to this reader.

If the CollectUsers method has been called before this method, and a user with the same ID is already in the userdatabase, all values of this existing user will be overwritten with the new values (name, userlevel and pincode). An OnProcessInfo event of processtype ptUserdatabaseChange and sub process type sptItemModified will then be generated.

If the CollectUsers has not yet been called, the new user data is simply passed to the reader. An OnProcessInfo event of processtype ptUserdatabaseChange and sub process type sptItemAdded will then be generated for every succesfully stored user (even if the user is already in the reader's userdatabase!).

Events of processtype ptSettingUsers are fired by this method including progress events.

Parameters:
pintfUsers A collection with all new users (IUser objects).
Note:
The RFID interface will be disabled during this process.
See also:
CollectUsers, IUser

IUserDatabase::CreateUser [out, retval] IUser **  ppintfUser  ) 
 

Create a new user object.

When adding a new user, use this method to create a new user object, then set all properties of the user object and finally call the IUser::Save method. If the users are already collected, using the CollectUsers method, and the ID of the new user is already present in the user database, a modified event of type ptUserdatabaseChange will be generated instead of an added event. See IUser::Save for more information.

Parameters:
ppintfUser Receives an newly created empty user object.
Precondition:
ppintfUser is not NULL.
See also:
IUser, CollectUsers, IUser::Save

IUserDatabase::Remove [in] ECardType  eCardType,
[in] BSTR  bstrCardNumber,
[in, defaultvalue("")] BSTR  bstrFacilityCode,
[in, defaultvalue(0xffff)] VARIANT_BOOL  fDisableRFID,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Remove a user from the userdatabase.

If the users are already collected using the CollectUsers method and the specified user cannot be found, the user cannot be removed and the pfSucceeded flag will be set to false. If the user is found, the user will be removed from both the reader and the internal collection.

When a specific user is removed, the OnProcessInfo of processtype ptUserdatabaseChange is fired with sptItemRemoved sub process. The Info argument will receive a copy of the user that has just been removed.

Parameters:
bstrCardNumber The cardnumber (ID) of the user that must be deleted.
eCardType The type of the card to remove.
bstrFacilityCode The facility code of this card.
fDisableRFID When set to true (default), the RFID interface will be disabled while removing this user and re-enabled after the remove process completes. This ensures that a user presenting a card cannot interfere with the process.
pfSucceeded Set to true if this user has been successfully removed, false if the user cannot be found.
See also:
ECardType

IUserDatabase::Clear [in, defaultvalue(0)] VARIANT_BOOL  fClearAsync,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID
 

Remove all users from the user database.

This method clears the entire user database in the reader (as well as this object's cached collection). Since this can be a very long operation, it can be executed asynchronously (in the background).

All normal events of processtype ptClearingUsers are fired by this method including progress events.

Parameters:
fClearAsync If set, this clear action will be performed asynchronously.
fDisableRFID Disable the RFID interface while clearing the user database (it is recommended to set this to true).
Note:
This will also clear this object's internal cached collection.

The RFID interface will be disabled during this process.

IUserDatabase::RemoveExpiredUsers [in, defaultvalue(0)] VARIANT_BOOL  fClearAsync,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID
 

Remove all expired users from the user database.

Clears the entire user database of all expired users. Expired users are users who's valid period has expired, see IUser::SetValidPeriod for more information.

All normal events of processtype ptClearingUsers are fired by this method including progress events.

Parameters:
fClearAsync If set, this clear action will be performed asynchronously.
fDisableRFID Disable the RFID interface while removing the expired users (it is recommended to set this to true).
Note:
This will also clear this object's internal cached collection.

The RFID interface will be disabled during this process.

IUserDatabase::FindUser [in] ECardType  eCardType,
[in] BSTR  bstrCardNumber,
[in, defaultvalue("")] BSTR  bstrFacilityCode,
[out, retval] IUser **  ppintfUser
 

Search for a particular user, if found, returns the found user object.

When there is already an internal cached user collection (when the CollectUsers method is already called), this method will first try to find the requested user in the internal collection. If it is found in the collection, it will be returned. If not the requested user will be retrieved from the reader itself (if the user exists) and added to the internal collection.

When a new user is found that is not yet part of the internal collection, the OnProcessInfo of processtype ptUserdatabase is fired with sub process type sptItemAdded. The newly added user is passed in the Info parameter.

Parameters:
bstrCardNumber The card number (ID) of the user to search for.
eCardType The cardtype of the user that should be found.
bstrFacilityCode The facility code of this card.
ppintfUser Receives the user object (if found), or NULL if not found.
Precondition:
ppintfUser is not NULL.
See also:
IUser, CollectUsers

IUserDatabase::SearchUsers [in] ESearchFlags  eFlags,
[in] VARIANT  vtUser,
[in, defaultvalue(0)] VARIANT  vtLevelRange,
[in, defaultvalue(0)] VARIANT  vtReserved1,
[in, defaultvalue(0)] VARIANT  vtReserved2,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Search a specific user or users that match certain search criteria.

Perform a search operation on the user database. A collection with all search results can be retrieved using the SearchResults property.

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 ssUsersSearched 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.

Note that the last search results will be cached inside this object. To clear the last search results of this userdatabase, use the ClearSearchResults method or specify the sfClearResults flag when searching again.

It is possible to search users using different search criteria:

  • Search a specific user. Search for a user with a specific ID.
  • Search for all users who's name contain a certain string. For instance when searching for the text "jo" the users "John", "joan" and "Cajo" will be returned.
  • Search for all users with a certain userlevel or search a range of levels (for instance ulNormalUser to ulNightLockOnlyUser). Note that in contrast with IEventDatabase::SearchEvents the search options cannot be combined!
Events of processtype ptSearchingUsers are generated by this method. No progress events ar generated. When a user with matching search criteria is found, the OnProcessInfo event with the sub process type sptItemFound is fired. The Info parameter of that event will contain the found user object (IUser).

Note that all arguments 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 Different search flags (search asynchrously, clear previous search results etc.).
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 to search for.
vtLevelRange This parameter may hold an VT_I2, lowest byte: lowest user level, highest byte, higest user level.
vtReserved1 Not used, reserved for future use.
vtReserved2 Not used, reserved for future use.
fDisableRFID Disable the RFID interface while searching the users (it is recommended to set this to true).
pfSucceeded Receives true if the search process finished successful (only when searching synchronous).
Note:
The RFID interface will be disabled during this process.
See also:
IUser, SearchResults, SearchStatus, CancelSearch, ClearSearchResults.

IUserDatabase::CancelSearch  ) 
 

Cancel a search process that is currently in progress.

See also:
SearchUsers, SearchStatus, SearchResults, ClearSearchResults

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

Return the internal collection of all search results.

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

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:
IUser, SearchUsers, SearchStatus, CancelSearch, ClearSearchResults

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

Return the status of the search process.

When searching, this property will return ssSearchingUsers. When ready searching ssUsersSearched will be returned. When no search operation has been started yet, the ssNoSearchResults is returned.

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

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

Clears the last search results.

Parameters:
pfSucceeded Set to true when the clear succeeds.
Precondition:
pfSucceeded is not NULL.
See also:
IUser, SearchUsers, SearchResults, SearchStatus, CancelSearch

IUserDatabase::GetSearchResults [in] ESearchFlags  eFlags,
[out, retval] ICollection **  ppintfResults
 

Returns an internal collection of searched results.

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

This API is able to cache two collections of search results. When specifying the sfSearchResults2 flag when calling SearchUsers, the search results will be placed in the secondary internally cached collection.

This method can be used to retrieve both the first and second search results collections whereas the SearchResults property can only be used to retrieve the first search results. This method returns a copy of one of two internally cached collection of search results.

Parameters:
eFlags Flags specifying which internal collection should be retrieved.
ppintfResults Receives a collection of search results.
Precondition:
ppintfResults is not NULL
See also:
IUser, SearchUsers, SearchStatus, CancelSearch, ClearSearchResults

IUserDatabase::UserGroups [out, retval] ICollection **  ppintfUserGroups  ) 
 

Returns a collecting of all usergroups.

When this method is called for the first time, it will collect all usergroups from the reader and return a collection with all usergroups. This collection will be cached internally and returned when this method is called again.

When the user groups are collected from the reader, all normal events of processtype ptCollectingUserGroups are fired. For every found user group, the OnProcessInfo event is fired, with the sptItemFound sub process type, the Info argument contains the found user group. This method will also fire progress events. Since a reader can hold only 16 user groups, only 16 progress events will be fired.

Parameters:
ppintfUserGroups Receives a collection of all usergroups.
Precondition:
ppintfUserGroups is not NULL.
Note:
User groups are supported in readers with a firmware version of 1.63 or higher. User groups will only work if the filesystem of the reader is set to 16 or 17 (see IProximityReader::SetFileSystem).
See also:
IUserGroup, FindUserGroup

IUserDatabase::CreateUserGroup [out, retval] IUserGroup **  ppintfUserGroup  ) 
 

Create a new user group object.

When adding a new user group, use this method to create a new user group object, then set all properties of the user group object and finally call the IUserGroup::Save method. If the usergroups have already been collected, using the UserGroups method, and the ID of the new user group is already present in the user database, the user group will be modified. See IUserGroup::Save for more information.

Parameters:
ppintfUserGroup Receives an newly created empty user group object.
Precondition:
ppintfUserGroup is not NULL.
Note:
User groups are supported in readers with a firmware version of 1.63 or higher. User groups will only work if the filesystem of the reader is set to 16 or 17 (see IProximityReader::SetFileSystem).
See also:
IUserGroup, UserGroups, IUserGroup::Save, FindUserGroup

IUserDatabase::RemoveUserGroup [in] IUserGroup pintfUserGroup  ) 
 

Remove an existing user group.

This method removes a specific user group.

Parameters:
pintfUserGroup The user group that should be removed.
Note:
The user group can only be removed if it is empty! When one or more users are still assigned to this user group, removing the user group generates an error!

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

See also:
IUserGroup, UserGroups, CreateUserGroup, FindUserGroup

IUserDatabase::FindUserGroup [in] long  lID,
[out, retval] IUserGroup **  ppintfUserGroup
 

Return a user group with the specific ID.

This method starts by searching the specified ID in the internal cached collection of user groups. If it cannot find the specified user group in this collection (or when the collection does not exists), it will search for the user group inside the reader. If the user group is found in the reader, it will be added to the internal collection. If the user group is not found, an empty (null) object will be returned and the return code of this method will be set to 1 (S_FALSE).

Parameters:
lID The ID of the requested user group.
ppintfUserGroup Receives the user group with the specific ID.
Note:
User groups are supported in readers with a firmware version of 1.63 or higher. User groups will only work if the filesystem of the reader is set to 16 or 17 (see IProximityReader::SetFileSystem).
See also:
IUserGroup, UserGroups, CreateUserGroup


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