#ifndef _NTPOAPI_H

// rev
/**
 * The POWER_INFORMATION_ENERGY_TRACKER_PROCESS_ENTRY structure describes an aggregate process record.
 *
 * All offsets are byte offsets from the start of the query output buffer, not from this entry. String counts
 * are WCHAR counts, exclude a terminating null, and do not imply null termination. UserSidLength is a byte
 * count. ProcessKey and ProcessId are zero unless POWER_INFORMATION_ENERGY_TRACKER_CREATE_FLAGS_MODE_PID is
 * enabled; ProcessKey is the process sequence number. The six trailing ULONG values count nonempty
 * energy-delta updates and contributing processes, not energy.
 *
 * StateFlags contains PROCESS_ENERGY_STATE_* bits captured in the aggregation key, masked by the low 16 bits
 * of POWER_INFORMATION_ENERGY_TRACKER_CREATE_INPUT.Reserved. It is not a duration-history indicator or
 * necessarily the process state at query completion. A zero creation mask produces zero StateFlags. Bits are
 * 0x1 (foreground), 0x2 (desktop-visible), 0x4 (PSM foreground), and 0x8 (PSM background).
 *
 * ActivityFlags contains POWER_INFORMATION_ENERGY_TRACKER_ACTIVITY_* bits ORed during nonempty energy-delta
 * aggregation: 0x1 for nonzero ForegroundDuration and 0x2 for nonzero DesktopVisibleDuration in a
 * contributing input snapshot. The kernel tests accumulated Duration values (excluding IsInState), not
 * calculated interval deltas. These flags therefore do not prove activity occurred in the current query
 * interval.
 * \remarks Snapshot reasons are internal discriminators passed as the fourth argument to
 * PopEtEnergyTrackerUpdateAggregate, not output flags or energy units:
 * - Reason 2 (explicit query): PopEtEnergyTrackerQuery enumerates processes through
 * PopEtProcessEnumSnapshotCallback to capture their current energy values; increments QuerySnapshotCount.
 * - Reason 3 (tracking-state change): PopEtEnergyContextProcessStateUpdate captures the process energy
 * values and notifies the energy trackers; increments StateChangeSnapshotCount.
 * - Reason 4 (process cleanup): PoEnergyContextCleanup captures the final state durations and notifies
 * the energy trackers before cleaning up the process energy context; increments TerminatedProcessCount.
 *
 * A reason-specific counter increments only when the calculated energy delta is nonempty. Every such update
 * also increments SnapshotCount. QuerySnapshotCount is therefore not simply the number of query API calls,
 * and TerminatedProcessCount does not count every process termination.
 *
 * SectionOffset locates the aggregated energy deltas for the query interval, aligned to 8 bytes. SectionSize
 * is 0x1B0 for PROCESS_EXTENDED_ENERGY_VALUES (Flags high nibble 0), or 0x1B8 for
 * PROCESS_EXTENDED_ENERGY_VALUES_V1 (Flags high nibble 1), in the kernel.
 */
typedef struct _POWER_INFORMATION_ENERGY_TRACKER_PROCESS_ENTRY
{
    ULONGLONG ProcessKey;                     // Process sequence number in per-process mode.
    ULONG ProcessId;                          // Process identifier in per-process mode; zero otherwise.
    USHORT StateFlags;                        // PROCESS_ENERGY_STATE_*; masked aggregation-key state.
    USHORT Reserved0E;                        // Reserved.
    ULONG FileNameOffset;                     // Process image path, or the fallback name.
    ULONG ImageCheckSum;                      // PE OptionalHeader.CheckSum.
    ULONG ImageTimeDateStamp;                 // PE FileHeader.TimeDateStamp.
    ULONG PackageFullNameOffset;              // Buffer-relative offset to the package full name.
    ULONG ApplicationIdOffset;                // Buffer-relative offset to the application identifier (RtlQueryPackageIdentity).
    ULONG SubProcessTagNameOffset;            // Buffer-relative offset to the subprocess tag name.
    ULONG UserSidOffset;                      // Buffer-relative offset to the token user SID.
    ULONG FileVersionLow;                     // VS_FIXEDFILEINFO.dwFileVersionLS.
    ULONG FileVersionHigh;                    // VS_FIXEDFILEINFO.dwFileVersionMS.
    USHORT FileNameCount;                     // Image path or fallback name length, in WCHARs, excluding a terminating null.
    USHORT PackageFullNameCount;              // Package full name length, in WCHARs, excluding a terminating null.
    USHORT ApplicationIdCount;                // Application identifier length, in WCHARs, excluding a terminating null.
    USHORT SubProcessTagNameCount;            // Subprocess tag name length, in WCHARs, excluding a terminating null.
    USHORT UserSidLength;                     // Size of the binary user SID, in bytes.
    USHORT Reserved;                          // Reserved.
    ULONG SectionOffset;                      // PROCESS_EXTENDED_ENERGY_VALUES // PROCESS_EXTENDED_ENERGY_VALUES_V1
    ULONG SectionSize;                        // Size of the aggregated energy-delta section, in bytes.
    ULONG ActiveTimeMs;                       // Accumulated unbiased elapsed time, capped to the query interval.
    ULONG ActivityFlags;                      // POWER_INFORMATION_ENERGY_TRACKER_ACTIVITY_*; accumulated-duration indicators.
    ULONG SnapshotCount;                      // All nonempty energy-delta updates.
    ULONG QuerySnapshotCount;                 // Updates during explicit queries (reason 2).
    ULONG StateChangeSnapshotCount;           // Updates during energy-tracking state changes (reason 3).
    ULONG ProcessCount;                       // Distinct processes contributing a nonempty delta in this query.
    ULONG NewProcessCount;                    // Processes contributing their first nonempty delta to this tracker.
    ULONG TerminatedProcessCount;             // Nonempty updates during process energy-context cleanup (reason 4).
} POWER_INFORMATION_ENERGY_TRACKER_PROCESS_ENTRY, *PPOWER_INFORMATION_ENERGY_TRACKER_PROCESS_ENTRY;

#endif
View code on GitHub