Deprecate EventLogRecord#getEventId in favor of #getInstanceId (#1105)

dbwiddis · dblock · commit dabdcd7c27e2 · 2019-06-11T22:08:33.000-04:00
diff --git a/CHANGES.md b/CHANGES.md
@@ -7,6 +7,7 @@ Next release (5.4.0)
 
 Features
 --------
+* [#1105](https://github.com/java-native-access/jna/issues/1105): Deprecate `c.s.j.p.win32.Advapi32Util.EventLogRecord#getEventId` in favor of `#getInstanceId` - [@dbwiddis](https://github.com/dbwiddis).
 * [#1097](https://github.com/java-native-access/jna/issues/1097): Allow `.ocx` as extension of native libraries on windows - [@dmigowski](https://github.com/dmigowski).
 
 Bug Fixes
diff --git a/contrib/platform/src/com/sun/jna/platform/win32/Advapi32Util.java b/contrib/platform/src/com/sun/jna/platform/win32/Advapi32Util.java
@@ -55,6 +55,7 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.TreeMap;
@@ -92,7 +93,6 @@
 import com.sun.jna.ptr.LongByReference;
 import com.sun.jna.ptr.PointerByReference;
 import com.sun.jna.win32.W32APITypeMapper;
-import java.util.List;
 
 /**
  * Advapi32 utility API.
@@ -2342,10 +2342,23 @@ public EVENTLOGRECORD getRecord() {
         }
 
         /**
-         * Event Id.
+         * The Instance ID, a resource identifier that corresponds to a string
+         * definition in the message resource file of the event source. The
+         * Event ID is the Instance ID with the top two bits masked off.
          *
-         * @return Integer.
+         * @return An integer representing the 32-bit Instance ID.
+         */
+        public int getInstanceId() {
+            return _record.EventID.intValue();
+        }
+
+        /**
+         * @deprecated As of 5.4.0, replaced by {@link #getInstanceId()}. The
+         *             Event ID displayed in the Windows Event Viewer
+         *             corresponds to {@link #getStatusCode()} for
+         *             system-generated events.
          */
+        @Deprecated
         public int getEventId() {
             return _record.EventID.intValue();
         }
@@ -2360,9 +2373,11 @@ public String getSource() {
         }
 
         /**
-         * Status code for the facility, part of the Event ID.
+         * Status code, the rightmost 16 bits of the Instance ID. Corresponds to
+         * the Event ID field in the Windows Event Viewer for system-generated
+         * events.
          *
-         * @return Status code.
+         * @return An integer representing the low 16-bits of the Instance ID.
          */
         public int getStatusCode() {
             return _record.EventID.intValue() & 0xFFFF;
diff --git a/contrib/platform/test/com/sun/jna/platform/win32/Advapi32Test.java b/contrib/platform/test/com/sun/jna/platform/win32/Advapi32Test.java
@@ -55,6 +55,8 @@
 import com.sun.jna.Memory;
 import com.sun.jna.Native;
 import com.sun.jna.Pointer;
+import com.sun.jna.platform.win32.Advapi32Util.EventLogIterator;
+import com.sun.jna.platform.win32.Advapi32Util.EventLogRecord;
 import com.sun.jna.platform.win32.LMAccess.USER_INFO_1;
 import com.sun.jna.platform.win32.WinBase.FE_EXPORT_FUNC;
 import com.sun.jna.platform.win32.WinBase.FE_IMPORT_FUNC;
@@ -953,13 +955,29 @@ public void testReportEvent() {
         m.setByte(1, (byte) 2);
         m.setByte(2, (byte) 3);
         m.setByte(3, (byte) 4);
-        assertTrue(Advapi32.INSTANCE.ReportEvent(h, WinNT.EVENTLOG_ERROR_TYPE, 0, 0, null, 2, 4, s, m));
+        int eventId = 123 + 0x40000000;
+        assertTrue(Advapi32.INSTANCE.ReportEvent(h, WinNT.EVENTLOG_ERROR_TYPE, 0, eventId, null, 2, 4, s, m));
         IntByReference after = new IntByReference();
         assertTrue(Advapi32.INSTANCE.GetNumberOfEventLogRecords(h, after));
         assertTrue(before.getValue() < after.getValue());
         assertFalse(h.equals(WinBase.INVALID_HANDLE_VALUE));
         assertTrue(Advapi32.INSTANCE.DeregisterEventSource(h));
         Advapi32Util.registryDeleteKey(WinReg.HKEY_LOCAL_MACHINE, jnaEventSourceRegistryPath);
+
+        // Test the event record
+        EventLogIterator iter = new EventLogIterator(null, "Application", WinNT.EVENTLOG_BACKWARDS_READ);
+        while (iter.hasNext()) {
+            EventLogRecord record = iter.next();
+            if (record.getRecord().EventID.getLow().intValue() == 123 && record.getStrings().length > 1
+                    && "JNA".equals(record.getStrings()[0]) && "Event".equals(record.getStrings()[1])) {
+                // Test Status Code stripping top 16 bits
+                assertEquals(123, record.getStatusCode());
+                // Test InstanceId
+                assertEquals(123 | 0x40000000, record.getInstanceId());
+                // Test Event ID stripping top 2 bits from InstanceId
+                assertEquals(123, record.getInstanceId() & 0x3FFFFFFF);
+            }
+        }
     }
 
     public void testGetNumberOfEventLogRecords() {
