LogOpenEventNotification - Remarks

The event-notification filter is a flexible data structure that is used to specify the class of events whose notifications will be received through the event-notification mechanism. It is available to event consumers (through LogOpenEventNotification and LogChangeEventFilter) and to log file readers (through LogReadEntry). This provides a common search criteria when waiting for events and reading selected entries within a log file.

                EVENT NOTIFICATION FILTER STRUCTURE

 ______________________    _______________________   _______________________
 _ SELECTION CRITERIA _    _ SELECTION CRITERIA  _   _ SELECTION CRITERIA  _
 _       BLOCK        ____>_       BLOCK         ___>_       BLOCK         _
 _                    _    _                     _   _                     _
 ______________________    _______________________   _______________________

The event-notification filter consists of an array of one or more selection criteria blocks. Each selection criteria block contains a small header block that specifies the revision of the filter and points to the next selection criteria block.

Each selection criteria block consists of an array of selection criteria subblocks. Each selection criteria subblock contains three pieces of information:

• The ID of an attribute that is contained within this class of log entry.

  For more information see the entry_attribute_ID parameter.

• A comparison operator that is to be applied against the specified log entry attribute.

  For more information see the comparison_operator_ID parameter.

• A pointer to a data that can be either ASCII or UniCode data. The data type is determined by the packet_revision_number

The following diagram summarizes the structure of a selection criteria block:

 ____________________
 _                  _
 _     HEADER       _
 _      BLOCK       _
 ____________________
 _    LOG ENTRY     _           SELECTION
 _  ATTRIBUTE ID    _            CRITERIA
 ____________________             BLOCK
 _   COMPARISON     _           STRUCTURE
 _  OPERATOR ID     _
 ____________________
 _   POINTER TO     _
 _COMPARISON DATA   _
 ____________________
 _                  _
 _                  _
 _                  _
 _                  _
 _                  _
 ____________________-------------------------
 _   LOG ENTRY      _           
 _  ATTRIBUTE ID    _           _
 ____________________       SELECTION
 _  COMPARISON      _       CRITERIA
 _ OPERATOR ID      _       SUBBLOCK
 ____________________           _
 _  POINTER TO      _           _
 _COMPARISON DATA   _           
 ____________________--------------------------

Each selection criteria subblock specifies a comparison with respect to an attribute within a log entry. The result of the comparison is a Boolean value. The Boolean value of the array of selection criteria subblocks (within a selection criteria block) is the logical AND of the Boolean values for each subblock.

If an event-notification filter contains more than one selection criteria block, the entire chain of selection criteria blocks is considered to resolve to the logical OR of the Boolean values of the individual blocks. In this manner, a consumer can construct appropriately complex event-discrimination filters.

The following diagram illustrates the logical representation of an event-notification filter:

                        EVENT NOTIFICATION FILTER STRUCTURE


  ____________    ______________      _______________        _______________
                 _  HEADER    _      _             _        _             _
        _         _   BLOCK    _ ___> _             _______> _             _
        _         ______________      _             _        _             _
     LOGICAL      _            _      _             _        _             _
       AND        _SELECTION   _      _ SELECTION   _        _ SELECTION   _
        _         _ CRITERIA   _      _  CRITERIA   _        _  CRITERIA   _
        _         _ SUBBLOCK   _      _    BLOCK    _        _    BLOCK    _
        _         ______________      _             _        _             _
        _         _            _      _             _        _             _
        _         _    .       _      _             _        _             _
        _         _    .       _      _             _        _             _
        _         _    .       _      _             _        _             _
        _         ______________      _             _        _             _
        _         _ SELECTION  _      _             _        _             _
        _         _ CRITERIA   _      _             _        _             _
        _         _ SUBBLOCK   _      _             _        _             _
                 _            _      _             _        _             _
   ___________    ______________      _______________        _______________

                  _                                                        _
                  _  <________________     LOGICAL     ________________>   _
                  _                          OR                            _
                  _                                                        _

The library LFAPI.LIB must be linked with object files that use LogOpenEventNotification