Cross Point


IEventDatabase Interface Reference

Inheritance diagram for IEventDatabase:

IXMLBase IEventBase List of all members.

Detailed Description

This interface handles all eventdatabase related functionality.

The event database is a database inside the reader that logs all reader events like: user added, access granted, access denied etc. Events consist of a timestamp, an event ID, event data and the event data type.

The number of events that the eventdatabase can hold depends on the used filesystem (see IProximityReader::SetFileSystem), it is even possible to set a filesystem that doesn't support events (no event database).

The LoggingMode property can be used to disable/enable the logging of events. Using the LoggingOptions property, the types of events that will be logged can be configured. It is for instance possible to log only security (access denied, granted etc.) events.

The events can be retrieved from the database using the CollectEvents method. When this method is finished, the entire collection of events can be retrieved using the Events property. It is possible to collect the events asynchronously using a flag in the CollectEvents method. The IsCollectingEvents property can be used to check if the process has finished collecting all events. The collect process can be canceled using the CancelCollectingEvents method. Note that while collecting events, events (code events) are fired that can be used to track the progress of the process and/or perform other tasks.

The events collected with a call to CollectEvents are cached internally. Calling the CollectEvents again will only add new events to the internal collection, it will not retrieve the entire collection again.

Using the LoggingOptions, the destructive read option can be toggled. When this option is on, all events that are read, will be deleted automatically from the event database of the reader.

The eventdatabase also contains advanced search facilities to search events. Events can be search by user (id or name), event ranges or start and end date.

All events in the database can be saved to disk using the IXMLBase::Download method. It is NOT possible to upload a previously saved file containing events to the reader.

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

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


Public Member Functions

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

HRESULT Count ([out, retval] long *plCount)
 Retrieves the number of events in the readers database.

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

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

HRESULT LoggingMode ([out, retval] ELoggingMode *peMode)
 Returns the current logging mode of the reader.

HRESULT LoggingMode ([in] ELoggingMode eMode)
 Sets the new logging mode of this reader.

HRESULT LoggingOptions ([out, retval] ELoggingOptions *peOptions)
 Retrieves the current options for logging from this reader.

HRESULT LoggingOptions ([in] ELoggingOptions eOptions)
 Sets the current options for logging.

HRESULT CollectEvents ([in, defaultvalue(0)] VARIANT_BOOL CollectAsync,[in, defaultvalue(-1)] long lNumber,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID,[out, retval] long *plEvents)
 Collect all events of this reader.

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

HRESULT CancelCollectingEvents ()
 Cancel a collection process that is currently in progress.

HRESULT Events ([out, retval] ICollection **ppintfEvents)
 Returns the internal collection of all events.

HRESULT Clear ([in, defaultvalue(0)] VARIANT_BOOL ClearAsync,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID)
 Removes all events from the eventlog.

HRESULT SearchEvents ([in] ESearchFlags eFlags,[in] VARIANT User,[in, defaultvalue(0)] VARIANT EventRange,[in, defaultvalue(0)] VARIANT StartDate,[in, defaultvalue(0)] VARIANT EndDate,[in, defaultvalue(1)] VARIANT_BOOL fDisableRFID,[out, retval] VARIANT_BOOL *pfSucceded)
 Search a specific event or events 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)
 Returns the status of the search process.

HRESULT ClearSearchResults ([in] ESearchFlags eFlags,[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.


Member Function Documentation

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

Returns the reader object this 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

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

Retrieves the number of events in the readers database.

This property returns the current number of events in the reader database by sending a message to the reader. The number of events is not cached internally since the number of events changes frequently (users presenting cards etc.). Note that the number of events in the reader does not have to be same as the number of event object returned by the Events property, especially when the eventdatabase in the reader is set to destructive read.

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

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

Retrieve the total number of events that can be stored in the event database.

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

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

Returns true if the eventdatabase is empty.

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

IEventDatabase::LoggingMode [out, retval] ELoggingMode peMode  ) 
 

Returns the current logging mode of the reader.

Parameters:
peMode Receives the current logging mode.
Precondition:
peMode is not NULL.
See also:
ELoggingMode

IEventDatabase::LoggingMode [in] ELoggingMode  eMode  ) 
 

Sets the new logging mode of this reader.

Used to turn the event logging on/off.

Parameters:
eMode The new logging mode.
See also:
ELoggingMode

IEventDatabase::LoggingOptions [out, retval] ELoggingOptions peOptions  ) 
 

Retrieves the current options for logging from this reader.

Parameters:
peOptions The current logging options.
Precondition:
peOptions is not NULL.
See also:
ELoggingOptions

IEventDatabase::LoggingOptions [in] ELoggingOptions  eOptions  ) 
 

Sets the current options for logging.

Use this method to configure what types of events should be logged. It is for instance possible to log only security events (access denied, granted etc.). Destructive read can also be turned on through this method. When destructive read is on, all events that have been read, are automatically removed from the reader's eventdatabase (they will be kept in this object's internal cached event collection).

Parameters:
eOptions The options to be set (can be or-ed).
See also:
ELoggingOptions

IEventDatabase::CollectEvents [in, defaultvalue(0)] VARIANT_BOOL  fCollectAsync,
[in, defaultvalue(-1)] long  lMaxNumber,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID,
[out, retval] long *  plEvents
 

Collect all events of this reader.

A collection with the collected events is created internally. This collection is cached for future use. This method returns the number of events stored in the collection. To retrieve the collection, use the Events property.

The process will start with the oldest event, and work it's way up to the newest event. So specifying for instance 100 as lMaxNumber will receive the oldest 100 events.

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

This method fires the default OnProcessStarted and OnProcessFinished events. The process type is ptCollectingEvents. The OnProcessInfo is fired with the sub process type of sptItemFound when an event is collected. The Info parameter of the OnProcessInfo will then contain the found IEvent object. The OnProcessInfo event is also fired with the sptProgress subtype, the Info parameter then holds the current progress percentage. This event is only fired when the progress percentage changes (thus maximum 100 progress events).

Note that the during the collecting process the OnProcessInfo event is also fired with the ptEventdatabaseChange process type. This ptEventdatabaseChange is a general process type, all changes to the event database i.e. new events added and events removed can be monitored using this process type.

Parameters:
fCollectAsync When set to true, the collecting is performed asynchrously (in another thread).
lMaxNumber The maximum number of events that should be collected (-1 means: collect all events).
fDisableRFID Disable the RFID interface while collecting the events (it is recommended to set this to true).
plEvents Receives the number of events found (only when fCollectAsync is false).
Precondition:
plEvents is not NULL.
Note:
The RFID interface will be disabled during this process.
See also:
Events, IsCollectingEvents, CancelCollectingEvents

IEventDatabase::IsCollectingEvents [out, retval] ECollectingStatus peStatus  ) 
 

Returns the status of the collecting process.

Use this method to check if the CollectEvents method has finished collecting the events. This method is only useful when collecting the events asynchronously.

Parameters:
peStatus Receives the status of the collecting process.
See also:
CollectEvents, CancelCollectingEvents, Events

IEventDatabase::CancelCollectingEvents  ) 
 

Cancel a collection process that is currently in progress.

See also:
IsCollectingEvents, CollectEvents, Events

IEventDatabase::Events [out, retval] ICollection **  ppintfEvents  ) 
 

Returns the internal collection of all events.

Returns the collection of IEvent objects. If the CollectEvents method is not yet called, this property will fail! Call the CollectEvents method before using this property!

This method returns a copy of the internal events collection.

Parameters:
ppintfEvents Receives a collection of all events.
Precondition:
ppintfEvents is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IEvent, CollectEvents, IsCollectingEvents, CancelCollectingEvents

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

Removes all events from the eventlog.

Clears the entire event 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).

This method fires the default events of the ptClearingEvents process type. Apart from the default events this method will also fire the OnProcessInfo event with process type ptEventdatabaseChange and sub process type sptCleared when the event database has been cleared.

Parameters:
fClearAsync If set to TRUE, the clear operation will be performed asynchronously.
fDisableRFID Disable the RFID interface while clearing the event 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.

IEventDatabase::SearchEvents [in] ESearchFlags  eFlags,
[in] VARIANT  vtUser,
[in, defaultvalue(0)] VARIANT  vtEventRange,
[in, defaultvalue(0)] VARIANT  vtStartDate,
[in, defaultvalue(0)] VARIANT  vtEndDate,
[in, defaultvalue(1)] VARIANT_BOOL  fDisableRFID,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Search a specific event or events that match certain search criteria.

Perform a search operation on the eventdatabase. 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 ssEventsSearched 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 increase performance. To clear the search results of this reader, use the ClearSearchResults method or specify the sfClearResults flag when searching again.

It is possible to search events using different search criteria:

  • Search all user related events. All events that are generated by a certain user or users. For instance all acces-granted events of user "John". The user data can be passed to this method as a string with the ID, or a string with (a part of) the user name. You can also pass a User object to this method.
  • Search all events of a certain type or a group of events. It is for instance possible to search for all access-denied events, or search for all security-related events.
  • Search all events within a certain time-span. Multiple search options can be combined! It is for instance possible to search all access-granted events that occurred yesterday between 8:25 and 9:00, for users who's names contain the text "Jo".
This method fires the default events of processtype ptSearchingEvents. For every found event, the OnProcessInfo event is fired with the sptItemFound sub process type. The Info parameter will contain an IEvent object with the found information.

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 (asynchrously / clear 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 where we should search for.
vtEventRange This parameter may hold an VT_I2, lowest byte: lowest event number, highest byte, higest event number. See the reader protocol documentation for more information.
vtStartDate This parameter may hold the start date/time. Only events where that are newer (more recent) then startdate will be returned
vtEndDate This parameter may hold the end date/time. Only events that occurred before this date will be returned.
fDisableRFID Disable the RFID interface while searching the event database (it is recommended to set this to true!).
pfSucceeded Receives true if this method succeeds (only when searching synchronously).
Precondition:
pfSucceeded is not NULL.
Note:
The RFID interface will be disabled during this process.
See also:
IEvent, SearchResults, SearchStatus, CancelSearch, ClearSearchResults.

IEventDatabase::CancelSearch  ) 
 

Cancel a search process that is currently in progress.

See also:
SearchEvents, SearchStatus, SearchResults, ClearSearchResults

IEventDatabase::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.

This method returns a copy of the internally cached collection of search results.

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:
IEvent, SearchEvents, SearchStatus, CancelSearch, ClearSearchResults

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

Returns the status of the search process.

When searching, this property will return ssSearchingEvents. When ready searching ssEventsSearched will be returned. When the SearchEvents method has not yet been called, this property will return ssNoSearchResults.

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

IEventDatabase::ClearSearchResults [in] ESearchFlags  eFlags,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Clears the last search results.

Parameters:
eFlags Flags, can be used to specify which search result set should be cleared.
pfSucceeded Set to true when the clear succeeds.
Precondition:
pfSucceeded is not NULL.
See also:
IEvent, SearchEvents, SearchResults, SearchStatus, CancelSearch

IEventDatabase::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 SearchEvents, 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:
IEvent, SearchEvents, SearchStatus, CancelSearch, ClearSearchResults


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