LogOpenEventNotification: Difference between revisions

Latest revision as of 17:17, 12 December 2022

LogOpenEventNotification registers a consumer with the Logging Service, so that the consumer will receive notification when specific log records have been created. Consumers specify which log records they will be notified about by providing filtering information. If no filter data structure is provided, all events that are logged to the specified log file will cause event notifications to be forwarded to the consumer. LogOpenEventNotification returns an ID used to reference this notification request.

Notifications will be sent for only those records placed in the error log by the FFSTProbe API.

Syntax

LogOpenEventNotification(service, pOpenEventNotification);

Parameters

service (ULONG) - input

The class of Logging Service:

Error logging
All other values are reserved for future use.

pOpenEventNotification (PVOID) - in/out: A pointer to the LogOpenEventNotification parameter packet.; For Error Logging, this is a pointer to a LOENREQUEST structure.

Returns

rc (APIRET) - returns: Return code.

LogOpenEventNotification returns the following values:

0 No error
523 Error LF invalid service
524 Error LF general failure
1703 Invalid data pointer
1701 RAS invalid LF log file id
1702 Invalid LF packet revision number
1706 RAS invalid parm packet ptr
1751 RAS invalid flag
1757 RAS invalid log notify ptr
1761 RAS invalid packet size

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.

Example Code

#define INCL_LOGGING
#include <os2.h>
#include <lfdef.h>

ULONG           service;
PVOID           pOpenEventNotification;
APIRET          rc;

rc = LogOpenEventNotification(service, pOpenEventNotification);

The following example opens error-logging event notification. It will initialize an event-notification filter that specifies any Error Log entry that has a product manufacturer named "IBM" and a severity less than 4.

  #define INCL_LOGGING
  #include <unidef.h>
  #include <os2.h>
  #include <stdio.h>
  #include <lfdef.h>
  #define ERROR_LOG_FILE_ID 1

  ULONG service;
  ULONG severity = 4;
  ULONG entry_id = 12;
  LOENREQUEST open_event_packet;
  HLOGNOTIFY log_notify;
  SUBBLOCK subblock1, subblock2, subblock3;
  HEADERBLOCK headerblock1, headerblock2;
  FILTERBLOCK filter;

  UniChar *manufacturer_name = L"IBM";

  service = ERROR_LOGGING_SERVICE;

  /*  Construct an event notification filter with 2 header blocks. */
  /*  The first header block points to a single subblock.          */
  /*  The second header block points to a chain of two subblocks.  */

  filter.packet_size = sizeof(FILTERBLOCK);
  filter.packet_revision_number = LF_UNI_API;
  filter.header_block = &headerblock1;

  /*-------------construct headerblock1---------------------*/
  headerblock1.pSubblock = &subblock1;
  headerblock1.pNextBlock = &headerblock2;

  /*construct subblock1 of headerblock1*/
  subblock1.entry_attribute_ID = LOG_ERROR_DMI_VENDOR_TAG;
  subblock1.comparison_operator = LOG_ERROR_EQUAL;
  subblock1.comparison_data_ptr = &manufacturer_name;
  subblock1.next_subblock = NULL;

  /*------------construct headerblock2----------------------*/
  headerblock2.pSubblock = &subblock2;
  headerblock2.pNextBlock = NULL;

  /*construct subblock2 of headerblock2*/
  subblock2.entry_attribute_ID = LOG_ERROR_SEVERITY;
  subblock2.comparison_operator = LOG_ERROR_LESS_THAN;
  subblock2.comparison_data_ptr = severity;
  subblock2.comparison_data_length = sizeof(ULONG);
  subblock2.next_subblock = &subblock3;

  /*construct subblock3 of headerblock2*/
  subblock3.entry_attribute_ID = LOG_ERROR_ENTRY_ID;
  subblock3.comparison_operator = LOG_ERROR_GREATER_THAN;
  subblock3.comparison_data_ptr = entry_id;
  subblock3.comparison_data_length = sizeof(ULONG);
  subblock3.next_subblock = null;

  /* Construct the LogOpenEventNotification parameter packet.*/
  open_event_packet.packet_size = sizeof(LOENREQUEST);
  open_event_packet.packet_revision_number = LF_UNI_API;
  open_event_packet.log_file_ID = ERROR_LOG_FILE_ID;
  open_event_packet.pLogNotify = &log_notify;
  open_event_packet.pFilter = &filter;
  open_event_packet.read_flags = 0;

  rc = LogOpenEventNotification(service,        /*service*/
                       &open_event_packet); /*parameter packet*/

  if (rc |= 0)
    {
     printf("LogOpenEventNotification error: return code = %d",rc);
     return;
    }