From ddd308b3146b0a200ad027f3de16a3bbebd84b36 Mon Sep 17 00:00:00 2001 From: dmex Date: Wed, 8 Jan 2025 12:16:26 +1100 Subject: [PATCH] Update ntpsapi.h --- phnt/include/ntpsapi.h | 614 ++++++++++++++++++++++++++++------------- 1 file changed, 419 insertions(+), 195 deletions(-) diff --git a/phnt/include/ntpsapi.h b/phnt/include/ntpsapi.h index f412a69cdb8f..2dcf93801beb 100644 --- a/phnt/include/ntpsapi.h +++ b/phnt/include/ntpsapi.h @@ -7,6 +7,8 @@ #ifndef _NTPSAPI_H #define _NTPSAPI_H +#include + // // Process Object Specific Access Rights // @@ -171,8 +173,6 @@ typedef struct _INITIAL_TEB PVOID StackAllocationBase; } INITIAL_TEB, *PINITIAL_TEB; -#include - #if (PHNT_MODE != PHNT_MODE_KERNEL) typedef enum _PROCESSINFOCLASS { @@ -375,30 +375,38 @@ typedef struct _PAGE_PRIORITY_INFORMATION // Process information structures // +/** + * The PROCESS_BASIC_INFORMATION structure contains basic information about a process. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntqueryinformationprocess#process_basic_information + */ typedef struct _PROCESS_BASIC_INFORMATION { - NTSTATUS ExitStatus; - PPEB PebBaseAddress; - KAFFINITY AffinityMask; - KPRIORITY BasePriority; - HANDLE UniqueProcessId; - HANDLE InheritedFromUniqueProcessId; + NTSTATUS ExitStatus; // The exit status of the process. (GetExitCodeProcess) + PPEB PebBaseAddress; // A pointer to the process environment block (PEB) of the process. + KAFFINITY AffinityMask; // The affinity mask of the process. (GetProcessAffinityMask) (deprecated) + KPRIORITY BasePriority; // The base priority of the process. (GetPriorityClass) + HANDLE UniqueProcessId; // The unique identifier of the process. (GetProcessId) + HANDLE InheritedFromUniqueProcessId; // The unique identifier of the parent process. } PROCESS_BASIC_INFORMATION, *PPROCESS_BASIC_INFORMATION; +/** + * The PROCESS_EXTENDED_BASIC_INFORMATION structure contains extended basic information about a process. + */ typedef struct _PROCESS_EXTENDED_BASIC_INFORMATION { - _In_ SIZE_T Size; + _In_ SIZE_T Size; // The size of the structure, in bytes. This member must be set to sizeof(PROCESS_EXTENDED_BASIC_INFORMATION). union { PROCESS_BASIC_INFORMATION BasicInfo; struct { - NTSTATUS ExitStatus; - PPEB PebBaseAddress; - KAFFINITY AffinityMask; - KPRIORITY BasePriority; - HANDLE UniqueProcessId; - HANDLE InheritedFromUniqueProcessId; + NTSTATUS ExitStatus; // The exit status of the process. (GetExitCodeProcess) + PPEB PebBaseAddress; // A pointer to the process environment block (PEB) of the process. + KAFFINITY AffinityMask; // The affinity mask of the process. (GetProcessAffinityMask) (deprecated) + KPRIORITY BasePriority; // The base priority of the process. (GetPriorityClass) + HANDLE UniqueProcessId; // The unique identifier of the process. (GetProcessId) + HANDLE InheritedFromUniqueProcessId; // The unique identifier of the parent process. }; }; union @@ -421,80 +429,185 @@ typedef struct _PROCESS_EXTENDED_BASIC_INFORMATION }; } PROCESS_EXTENDED_BASIC_INFORMATION, *PPROCESS_EXTENDED_BASIC_INFORMATION; +/** + * The VM_COUNTERS structure contains various memory usage statistics for a process. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/psapi/ns-psapi-process_memory_counters + */ typedef struct _VM_COUNTERS { - SIZE_T PeakVirtualSize; - SIZE_T VirtualSize; - ULONG PageFaultCount; - SIZE_T PeakWorkingSetSize; - SIZE_T WorkingSetSize; - SIZE_T QuotaPeakPagedPoolUsage; - SIZE_T QuotaPagedPoolUsage; - SIZE_T QuotaPeakNonPagedPoolUsage; - SIZE_T QuotaNonPagedPoolUsage; - SIZE_T PagefileUsage; - SIZE_T PeakPagefileUsage; + SIZE_T PeakVirtualSize; // The peak virtual address space size of this process, in bytes. + SIZE_T VirtualSize; // The virtual address space size of this process, in bytes. + ULONG PageFaultCount; // The number of page faults. + SIZE_T PeakWorkingSetSize; // The peak working set size, in bytes. + SIZE_T WorkingSetSize; // The current working set size, in bytes + SIZE_T QuotaPeakPagedPoolUsage; // The peak paged pool usage, in bytes. + SIZE_T QuotaPagedPoolUsage; // The current paged pool usage, in bytes. + SIZE_T QuotaPeakNonPagedPoolUsage; // The peak non-paged pool usage, in bytes. + SIZE_T QuotaNonPagedPoolUsage; // The current non-paged pool usage, in bytes. + SIZE_T PagefileUsage; // The Commit Charge value in bytes for this process. Commit Charge is the total amount of private memory that the memory manager has committed for a running process. + SIZE_T PeakPagefileUsage; // The peak value in bytes of the Commit Charge during the lifetime of this process. } VM_COUNTERS, *PVM_COUNTERS; +/** + * The VM_COUNTERS_EX structure extends VM_COUNTERS to include private memory usage. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/psapi/ns-psapi-process_memory_counters_ex2 + */ typedef struct _VM_COUNTERS_EX { - SIZE_T PeakVirtualSize; - SIZE_T VirtualSize; - ULONG PageFaultCount; - SIZE_T PeakWorkingSetSize; - SIZE_T WorkingSetSize; - SIZE_T QuotaPeakPagedPoolUsage; - SIZE_T QuotaPagedPoolUsage; - SIZE_T QuotaPeakNonPagedPoolUsage; - SIZE_T QuotaNonPagedPoolUsage; - SIZE_T PagefileUsage; - SIZE_T PeakPagefileUsage; - SIZE_T PrivateUsage; + SIZE_T PeakVirtualSize; // The peak virtual address space size of this process, in bytes. + SIZE_T VirtualSize; // The virtual address space size of this process, in bytes. + ULONG PageFaultCount; // The number of page faults. + SIZE_T PeakWorkingSetSize; // The peak working set size, in bytes. + SIZE_T WorkingSetSize; // The current working set size, in bytes + SIZE_T QuotaPeakPagedPoolUsage; // The peak paged pool usage, in bytes. + SIZE_T QuotaPagedPoolUsage; // The current paged pool usage, in bytes. + SIZE_T QuotaPeakNonPagedPoolUsage; // The peak non-paged pool usage, in bytes. + SIZE_T QuotaNonPagedPoolUsage; // The current non-paged pool usage, in bytes. + SIZE_T PagefileUsage; // The Commit Charge value in bytes for this process. Commit Charge is the total amount of private memory that the memory manager has committed for a running process. + SIZE_T PeakPagefileUsage; // The peak value in bytes of the Commit Charge during the lifetime of this process. + SIZE_T PrivateUsage; // Same as PagefileUsage. The Commit Charge value in bytes for this process. Commit Charge is the total amount of private memory that the memory manager has committed for a running process. } VM_COUNTERS_EX, *PVM_COUNTERS_EX; +/** + * The VM_COUNTERS_EX2 structure extends VM_COUNTERS_EX to include private working set size and shared commit usage. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/psapi/ns-psapi-process_memory_counters_ex2 + */ typedef struct _VM_COUNTERS_EX2 { - VM_COUNTERS_EX CountersEx; - SIZE_T PrivateWorkingSetSize; - SIZE_T SharedCommitUsage; + union + { + VM_COUNTERS_EX CountersEx; + struct + { + SIZE_T PeakVirtualSize; // The peak virtual address space size of this process, in bytes. + SIZE_T VirtualSize; // The virtual address space size of this process, in bytes. + ULONG PageFaultCount; // The number of page faults. + SIZE_T PeakWorkingSetSize; // The peak working set size, in bytes. + SIZE_T WorkingSetSize; // The current working set size, in bytes + SIZE_T QuotaPeakPagedPoolUsage; // The peak paged pool usage, in bytes. + SIZE_T QuotaPagedPoolUsage; // The current paged pool usage, in bytes. + SIZE_T QuotaPeakNonPagedPoolUsage; // The peak non-paged pool usage, in bytes. + SIZE_T QuotaNonPagedPoolUsage; // The current non-paged pool usage, in bytes. + SIZE_T PagefileUsage; // The Commit Charge value in bytes for this process. Commit Charge is the total amount of private memory that the memory manager has committed for a running process. + SIZE_T PeakPagefileUsage; // The peak value in bytes of the Commit Charge during the lifetime of this process. + SIZE_T PrivateUsage; // Same as PagefileUsage. The Commit Charge value in bytes for this process. Commit Charge is the total amount of private memory that the memory manager has committed for a running process. + }; + }; + SIZE_T PrivateWorkingSetSize; // The current private working set size, in bytes. + SIZE_T SharedCommitUsage; // The current shared commit usage, in bytes. } VM_COUNTERS_EX2, *PVM_COUNTERS_EX2; +/** + * The KERNEL_USER_TIMES structure contains timing information for a process or thread. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadtimes + */ typedef struct _KERNEL_USER_TIMES { - LARGE_INTEGER CreateTime; - LARGE_INTEGER ExitTime; - LARGE_INTEGER KernelTime; - LARGE_INTEGER UserTime; + LARGE_INTEGER CreateTime; // The creation time of the process or thread. + LARGE_INTEGER ExitTime; // The exit time of the process or thread. + LARGE_INTEGER KernelTime; // The amount of time the process has executed in kernel mode. + LARGE_INTEGER UserTime; // The amount of time the process has executed in user mode. } KERNEL_USER_TIMES, *PKERNEL_USER_TIMES; +/** + * The POOLED_USAGE_AND_LIMITS structure contains information about the usage and limits of paged and non-paged pool memory. + */ typedef struct _POOLED_USAGE_AND_LIMITS { - SIZE_T PeakPagedPoolUsage; - SIZE_T PagedPoolUsage; - SIZE_T PagedPoolLimit; - SIZE_T PeakNonPagedPoolUsage; - SIZE_T NonPagedPoolUsage; - SIZE_T NonPagedPoolLimit; - SIZE_T PeakPagefileUsage; - SIZE_T PagefileUsage; - SIZE_T PagefileLimit; + SIZE_T PeakPagedPoolUsage; // The peak paged pool usage. + SIZE_T PagedPoolUsage; // The current paged pool usage. + SIZE_T PagedPoolLimit; // The limit on paged pool usage. + SIZE_T PeakNonPagedPoolUsage; // The peak non-paged pool usage. + SIZE_T NonPagedPoolUsage; // The current non-paged pool usage. + SIZE_T NonPagedPoolLimit; // The limit on non-paged pool usage. + SIZE_T PeakPagefileUsage; // The peak pagefile usage. + SIZE_T PagefileUsage; // The current pagefile usage. + SIZE_T PagefileLimit; // The limit on pagefile usage. } POOLED_USAGE_AND_LIMITS, *PPOOLED_USAGE_AND_LIMITS; #define PROCESS_EXCEPTION_PORT_ALL_STATE_BITS 0x00000003 #define PROCESS_EXCEPTION_PORT_ALL_STATE_FLAGS ((ULONG_PTR)((1UL << PROCESS_EXCEPTION_PORT_ALL_STATE_BITS) - 1)) +/** + * The PROCESS_EXCEPTION_PORT structure is used to manage exception ports for a process. + */ typedef struct _PROCESS_EXCEPTION_PORT { - _In_ HANDLE ExceptionPortHandle; // Handle to the exception port. No particular access required. - _Inout_ ULONG StateFlags; // Miscellaneous state flags to be cached along with the exception port in the kernel. + // + // Handle to the exception port. No particular access required. + // + _In_ HANDLE ExceptionPortHandle; + + // + // Miscellaneous state flags to be cached along with the exception + // port in the kernel. + // + _Inout_ ULONG StateFlags; + } PROCESS_EXCEPTION_PORT, *PPROCESS_EXCEPTION_PORT; +/** + * The PROCESS_ACCESS_TOKEN structure is used to manage the security context of a process or thread. + * + * A process's access token can only be changed if the process has no threads or a single thread that has not yet begun execution. + */ typedef struct _PROCESS_ACCESS_TOKEN { - HANDLE Token; // needs TOKEN_ASSIGN_PRIMARY access - HANDLE Thread; // handle to initial/only thread; needs THREAD_QUERY_INFORMATION access + // + // Handle to Primary token to assign to the process. + // TOKEN_ASSIGN_PRIMARY access to this token is needed. + // + HANDLE Token; + + // + // Handle to the initial thread of the process. + // THREAD_QUERY_INFORMATION access to this thread is needed. + // + // N.B. This field is unused. + // + HANDLE Thread; + } PROCESS_ACCESS_TOKEN, *PPROCESS_ACCESS_TOKEN; +#ifndef _LDT_ENTRY_DEFINED +#define _LDT_ENTRY_DEFINED +typedef struct _LDT_ENTRY +{ + USHORT LimitLow; + USHORT BaseLow; + union + { + struct + { + UCHAR BaseMid; + UCHAR Flags1; + UCHAR Flags2; + UCHAR BaseHi; + } Bytes; + struct + { + ULONG BaseMid : 8; + ULONG Type : 5; + ULONG Dpl : 2; + ULONG Pres : 1; + ULONG LimitHi : 4; + ULONG Sys : 1; + ULONG Reserved_0 : 1; + ULONG Default_Big : 1; + ULONG Granularity : 1; + ULONG BaseHi : 8; + } Bits; + } HighWord; +} LDT_ENTRY, *PLDT_ENTRY; +#endif + +/** + * The PROCESS_LDT_INFORMATION structure is used to manage Local Descriptor Table (LDT) entries for a process. + */ typedef struct _PROCESS_LDT_INFORMATION { ULONG Start; @@ -502,20 +615,32 @@ typedef struct _PROCESS_LDT_INFORMATION LDT_ENTRY LdtEntries[1]; } PROCESS_LDT_INFORMATION, *PPROCESS_LDT_INFORMATION; +/** + * The PROCESS_LDT_SIZE structure is used to specify the size of the Local Descriptor Table (LDT) for a process. + */ typedef struct _PROCESS_LDT_SIZE { ULONG Length; } PROCESS_LDT_SIZE, *PPROCESS_LDT_SIZE; +/** + * The PROCESS_WS_WATCH_INFORMATION structure is used to store information about working set watch events for a process. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/psapi/ns-psapi-psapi_ws_watch_information + */ typedef struct _PROCESS_WS_WATCH_INFORMATION { - PVOID FaultingPc; - PVOID FaultingVa; + PVOID FaultingPc; // A pointer to the instruction that caused the page fault. + PVOID FaultingVa; // A pointer to the page that was added to the working set. } PROCESS_WS_WATCH_INFORMATION, *PPROCESS_WS_WATCH_INFORMATION; #endif -// psapi:PSAPI_WS_WATCH_INFORMATION_EX +/** + * The PROCESS_WS_WATCH_INFORMATION_EX structure contains extended information about a page added to a process working set. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/psapi/ns-psapi-psapi_ws_watch_information_ex + */ typedef struct _PROCESS_WS_WATCH_INFORMATION_EX { union @@ -523,12 +648,12 @@ typedef struct _PROCESS_WS_WATCH_INFORMATION_EX PROCESS_WS_WATCH_INFORMATION BasicInfo; struct { - PVOID FaultingPc; - PVOID FaultingVa; + PVOID FaultingPc; // The address of the instruction that caused the page fault. + PVOID FaultingVa; // The virtual address that caused the page fault. }; }; - ULONG_PTR FaultingThreadId; - ULONG_PTR Flags; + HANDLE FaultingThreadId; // The identifier of the thread that caused the page fault. + ULONG_PTR Flags; // This member is reserved for future use. } PROCESS_WS_WATCH_INFORMATION_EX, *PPROCESS_WS_WATCH_INFORMATION_EX; #define PROCESS_PRIORITY_CLASS_UNKNOWN 0 @@ -539,12 +664,18 @@ typedef struct _PROCESS_WS_WATCH_INFORMATION_EX #define PROCESS_PRIORITY_CLASS_BELOW_NORMAL 5 #define PROCESS_PRIORITY_CLASS_ABOVE_NORMAL 6 +/** + * The PROCESS_PRIORITY_CLASS structure is used to manage the priority class of a process. + */ typedef struct _PROCESS_PRIORITY_CLASS { BOOLEAN Foreground; UCHAR PriorityClass; } PROCESS_PRIORITY_CLASS, *PPROCESS_PRIORITY_CLASS; +/** + * The PROCESS_PRIORITY_CLASS_EX structure extends PROCESS_PRIORITY_CLASS to include validity flags. + */ typedef struct _PROCESS_PRIORITY_CLASS_EX { union @@ -632,17 +763,23 @@ typedef struct _PROCESS_SESSION_INFORMATION #define PROCESS_HANDLE_RAISE_EXCEPTION_ON_INVALID_HANDLE_CLOSE_DISABLED 0x00000000 #define PROCESS_HANDLE_RAISE_EXCEPTION_ON_INVALID_HANDLE_CLOSE_ENABLED 0x00000001 +/** + * The PROCESS_HANDLE_TRACING_ENABLE structure is used to enable handle tracing for a process. + */ typedef struct _PROCESS_HANDLE_TRACING_ENABLE { - ULONG Flags; + ULONG Flags; // Flags that control handle tracing. } PROCESS_HANDLE_TRACING_ENABLE, *PPROCESS_HANDLE_TRACING_ENABLE; #define PROCESS_HANDLE_TRACING_MAX_SLOTS 0x20000 +/** + * The PROCESS_HANDLE_TRACING_ENABLE_EX structure extends PROCESS_HANDLE_TRACING_ENABLE to include the total number of slots. + */ typedef struct _PROCESS_HANDLE_TRACING_ENABLE_EX { - ULONG Flags; - ULONG TotalSlots; + ULONG Flags; // Flags that control handle tracing. + ULONG TotalSlots; // Total number of handle tracing slots. } PROCESS_HANDLE_TRACING_ENABLE_EX, *PPROCESS_HANDLE_TRACING_ENABLE_EX; #define PROCESS_HANDLE_TRACING_MAX_STACKS 16 @@ -668,108 +805,146 @@ typedef struct _PROCESS_HANDLE_TRACING_QUERY #endif +/** + * The THREAD_TLS_INFORMATION structure contains information about the Thread Local Storage (TLS) data for a thread. + */ typedef struct _THREAD_TLS_INFORMATION { - ULONG Flags; - PVOID NewTlsData; - PVOID OldTlsData; - HANDLE ThreadId; + ULONG Flags; // Flags that provide additional information about the TLS data. + PVOID NewTlsData; // Pointer to the new TLS data. + PVOID OldTlsData; // Pointer to the old TLS data. + HANDLE ThreadId; // Handle to the thread associated with the TLS data. } THREAD_TLS_INFORMATION, *PTHREAD_TLS_INFORMATION; +/** + * The PROCESS_TLS_INFORMATION_TYPE enumeration defines the types of TLS operations that can be performed on a process. + */ typedef enum _PROCESS_TLS_INFORMATION_TYPE { - ProcessTlsReplaceIndex, - ProcessTlsReplaceVector, - MaxProcessTlsOperation + ProcessTlsReplaceIndex, // Replace the TLS index. + ProcessTlsReplaceVector, // Replace the TLS vector. + MaxProcessTlsOperation // Maximum value for the enumeration. } PROCESS_TLS_INFORMATION_TYPE, *PPROCESS_TLS_INFORMATION_TYPE; +/** + * The PROCESS_TLS_INFORMATION structure contains information about the TLS operations for a process. + */ typedef struct _PROCESS_TLS_INFORMATION { - ULONG Flags; - ULONG OperationType; - ULONG ThreadDataCount; - ULONG TlsIndex; - ULONG PreviousCount; - _Field_size_(ThreadDataCount) THREAD_TLS_INFORMATION ThreadData[1]; + ULONG Flags; // Flags that provide additional information about the TLS operation. + ULONG OperationType; // The type of TLS operation to be performed. + ULONG ThreadDataCount; // The number of THREAD_TLS_INFORMATION structures in the ThreadData array. + ULONG TlsIndex; // The TLS index to be replaced. + ULONG PreviousCount; // The previous count of TLS data. + _Field_size_(ThreadDataCount) THREAD_TLS_INFORMATION ThreadData[1]; // Array of THREAD_TLS_INFORMATION structures. } PROCESS_TLS_INFORMATION, *PPROCESS_TLS_INFORMATION; +/** + * The PROCESS_INSTRUMENTATION_CALLBACK_INFORMATION structure contains information about the instrumentation callback for a process. + */ typedef struct _PROCESS_INSTRUMENTATION_CALLBACK_INFORMATION { - ULONG Version; - ULONG Reserved; - PVOID Callback; + ULONG Version; // The version of the instrumentation callback information. + ULONG Reserved; // Reserved for future use. + PVOID Callback; // Pointer to the callback function. } PROCESS_INSTRUMENTATION_CALLBACK_INFORMATION, *PPROCESS_INSTRUMENTATION_CALLBACK_INFORMATION; +/** + * The PROCESS_STACK_ALLOCATION_INFORMATION structure contains information about the stack allocation for a process. + */ typedef struct _PROCESS_STACK_ALLOCATION_INFORMATION { - SIZE_T ReserveSize; - SIZE_T ZeroBits; - PVOID StackBase; + SIZE_T ReserveSize; // The size of the stack to be reserved. + SIZE_T ZeroBits; // The number of zero bits in the stack base address. + PVOID StackBase; // Pointer to the base of the stack. } PROCESS_STACK_ALLOCATION_INFORMATION, *PPROCESS_STACK_ALLOCATION_INFORMATION; +/** + * The PROCESS_STACK_ALLOCATION_INFORMATION_EX structure extends PROCESS_STACK_ALLOCATION_INFORMATION to include additional fields. + */ typedef struct _PROCESS_STACK_ALLOCATION_INFORMATION_EX { - ULONG PreferredNode; - ULONG Reserved0; - ULONG Reserved1; - ULONG Reserved2; - PROCESS_STACK_ALLOCATION_INFORMATION AllocInfo; + ULONG PreferredNode; // The preferred NUMA node for the stack allocation. + ULONG Reserved0; // Reserved for future use. + ULONG Reserved1; // Reserved for future use. + ULONG Reserved2; // Reserved for future use. + PROCESS_STACK_ALLOCATION_INFORMATION AllocInfo; // The stack allocation information. } PROCESS_STACK_ALLOCATION_INFORMATION_EX, *PPROCESS_STACK_ALLOCATION_INFORMATION_EX; - +/** + * The PROCESS_AFFINITY_UPDATE_MODE union is used to specify the affinity update mode for a process. + */ typedef union _PROCESS_AFFINITY_UPDATE_MODE { ULONG Flags; struct { - ULONG EnableAutoUpdate : 1; - ULONG Permanent : 1; - ULONG Reserved : 30; + ULONG EnableAutoUpdate : 1; // Indicates whether auto-update of affinity is enabled. + ULONG Permanent : 1; // Indicates whether the affinity update is permanent. + ULONG Reserved : 30; // Reserved for future use. }; } PROCESS_AFFINITY_UPDATE_MODE, *PPROCESS_AFFINITY_UPDATE_MODE; +/** + * The PROCESS_MEMORY_ALLOCATION_MODE union is used to specify the memory allocation mode for a process. + */ typedef union _PROCESS_MEMORY_ALLOCATION_MODE { ULONG Flags; struct { - ULONG TopDown : 1; - ULONG Reserved : 31; + ULONG TopDown : 1; // Indicates whether memory allocation should be top-down. + ULONG Reserved : 31; // Reserved for future use. }; } PROCESS_MEMORY_ALLOCATION_MODE, *PPROCESS_MEMORY_ALLOCATION_MODE; +/** + * The PROCESS_HANDLE_INFORMATION structure contains information about the handles of a process. + */ typedef struct _PROCESS_HANDLE_INFORMATION { - ULONG HandleCount; - ULONG HandleCountHighWatermark; + ULONG HandleCount; // The number of handles in the process. + ULONG HandleCountHighWatermark; // The highest number of handles that the process has had. } PROCESS_HANDLE_INFORMATION, *PPROCESS_HANDLE_INFORMATION; +/** + * The PROCESS_CYCLE_TIME_INFORMATION structure contains information about the cycle time of a process. + */ typedef struct _PROCESS_CYCLE_TIME_INFORMATION { - ULONGLONG AccumulatedCycles; - ULONGLONG CurrentCycleCount; + ULONGLONG AccumulatedCycles; // The total number of cycles accumulated by the process. + ULONGLONG CurrentCycleCount; // The current cycle count of the process. } PROCESS_CYCLE_TIME_INFORMATION, *PPROCESS_CYCLE_TIME_INFORMATION; +/** + * The PROCESS_WINDOW_INFORMATION structure contains information about the windows of a process. + */ typedef struct _PROCESS_WINDOW_INFORMATION { - ULONG WindowFlags; - USHORT WindowTitleLength; - _Field_size_bytes_(WindowTitleLength) WCHAR WindowTitle[1]; + ULONG WindowFlags; // Flags that provide information about the window. + USHORT WindowTitleLength; // The length of the window title. + _Field_size_bytes_(WindowTitleLength) WCHAR WindowTitle[1]; // The title of the window. } PROCESS_WINDOW_INFORMATION, *PPROCESS_WINDOW_INFORMATION; +/** + * The PROCESS_HANDLE_TABLE_ENTRY_INFO structure contains information about a handle table entry of a process. + */ typedef struct _PROCESS_HANDLE_TABLE_ENTRY_INFO { - HANDLE HandleValue; - SIZE_T HandleCount; - SIZE_T PointerCount; - ACCESS_MASK GrantedAccess; - ULONG ObjectTypeIndex; - ULONG HandleAttributes; - ULONG Reserved; + HANDLE HandleValue; // The value of the handle. + SIZE_T HandleCount; // The number of references to the handle. + SIZE_T PointerCount; // The number of pointers to the handle. + ACCESS_MASK GrantedAccess; // The access rights granted to the handle. + ULONG ObjectTypeIndex; // The index of the object type. + ULONG HandleAttributes; // The attributes of the handle. + ULONG Reserved; // Reserved for future use. } PROCESS_HANDLE_TABLE_ENTRY_INFO, *PPROCESS_HANDLE_TABLE_ENTRY_INFO; +/** + * The PROCESS_HANDLE_SNAPSHOT_INFORMATION structure contains information about the handle snapshot of a process. + */ typedef struct _PROCESS_HANDLE_SNAPSHOT_INFORMATION { - SIZE_T NumberOfHandles; + ULONG_PTR NumberOfHandles; ULONG_PTR Reserved; _Field_size_(NumberOfHandles) PROCESS_HANDLE_TABLE_ENTRY_INFO Handles[1]; } PROCESS_HANDLE_SNAPSHOT_INFORMATION, *PPROCESS_HANDLE_SNAPSHOT_INFORMATION; @@ -898,6 +1073,9 @@ typedef struct _PROCESS_REVOKE_FILE_HANDLES_INFORMATION #define PROCESS_WORKING_SET_CONTROL_VERSION 3 +/** + * The PROCESS_WORKING_SET_OPERATION enumeration defines the operation to perform on a process's working set. + */ typedef enum _PROCESS_WORKING_SET_OPERATION { ProcessWorkingSetSwap, @@ -905,6 +1083,9 @@ typedef enum _PROCESS_WORKING_SET_OPERATION ProcessWorkingSetOperationMax } PROCESS_WORKING_SET_OPERATION; +/** + * The PROCESS_WORKING_SET_CONTROL structure is used to control the working set of a process. + */ typedef struct _PROCESS_WORKING_SET_CONTROL { ULONG Version; @@ -912,25 +1093,31 @@ typedef struct _PROCESS_WORKING_SET_CONTROL ULONG Flags; } PROCESS_WORKING_SET_CONTROL, *PPROCESS_WORKING_SET_CONTROL; +/** + * The PS_PROTECTED_TYPE enumeration defines the types of protection that can be applied to a process. + */ typedef enum _PS_PROTECTED_TYPE { - PsProtectedTypeNone, - PsProtectedTypeProtectedLight, - PsProtectedTypeProtected, + PsProtectedTypeNone, // No protection. + PsProtectedTypeProtectedLight, // Light protection. + PsProtectedTypeProtected, // Full protection. PsProtectedTypeMax } PS_PROTECTED_TYPE; +/** + * The PS_PROTECTED_SIGNER enumeration defines the types of signers that can be associated with a protected process. + */ typedef enum _PS_PROTECTED_SIGNER { - PsProtectedSignerNone, - PsProtectedSignerAuthenticode, - PsProtectedSignerCodeGen, - PsProtectedSignerAntimalware, - PsProtectedSignerLsa, - PsProtectedSignerWindows, - PsProtectedSignerWinTcb, - PsProtectedSignerWinSystem, - PsProtectedSignerApp, + PsProtectedSignerNone, // No signer. + PsProtectedSignerAuthenticode, // Authenticode signer. + PsProtectedSignerCodeGen, // Code generation signer. + PsProtectedSignerAntimalware, // Antimalware signer. + PsProtectedSignerLsa, // Local Security Authority signer. + PsProtectedSignerWindows, // Windows signer. + PsProtectedSignerWinTcb, // Windows Trusted Computing Base signer. + PsProtectedSignerWinSystem, // Windows system signer. + PsProtectedSignerApp, // Application signer. PsProtectedSignerMax } PS_PROTECTED_SIGNER; @@ -938,20 +1125,23 @@ typedef enum _PS_PROTECTED_SIGNER #define PS_PROTECTED_AUDIT_MASK 0x08 #define PS_PROTECTED_TYPE_MASK 0x07 -// vProtectionLevel.Level = PsProtectedValue(PsProtectedSignerCodeGen, FALSE, PsProtectedTypeProtectedLight) -#define PsProtectedValue(aSigner, aAudit, aType) ( \ - (((aSigner) & PS_PROTECTED_SIGNER_MASK) << 4) | \ - (((aAudit) & PS_PROTECTED_AUDIT_MASK) << 3) | \ - ((aType) & PS_PROTECTED_TYPE_MASK)\ +// ProtectionLevel.Level = PsProtectedValue(PsProtectedSignerCodeGen, FALSE, PsProtectedTypeProtectedLight) +#define PsProtectedValue(PsSigner, PsAudit, PsType) ( \ + (((PsSigner) & PS_PROTECTED_SIGNER_MASK) << 4) | \ + (((PsAudit) & PS_PROTECTED_AUDIT_MASK) << 3) | \ + (((PsType) & PS_PROTECTED_TYPE_MASK)) \ ) -// InitializePsProtection(&vProtectionLevel, PsProtectedSignerCodeGen, FALSE, PsProtectedTypeProtectedLight) -#define InitializePsProtection(aProtectionLevelPtr, aSigner, aAudit, aType) { \ - (aProtectionLevelPtr)->Signer = aSigner; \ - (aProtectionLevelPtr)->Audit = aAudit; \ - (aProtectionLevelPtr)->Type = aType; \ +// InitializePsProtection(&ProtectionLevel, PsProtectedSignerCodeGen, FALSE, PsProtectedTypeProtectedLight) +#define InitializePsProtection(PsProtectionLevel, PsSigner, PsAudit, PsType) { \ + (PsProtectionLevel)->Signer = (PsSigner); \ + (PsProtectionLevel)->Audit = (PsAudit); \ + (PsProtectionLevel)->Type = (PsType); \ } +/** + * The PS_PROTECTION structure is used to define the protection level of a process. + */ typedef struct _PS_PROTECTION { union @@ -966,33 +1156,42 @@ typedef struct _PS_PROTECTION }; } PS_PROTECTION, *PPS_PROTECTION; +/** + * The PROCESS_FAULT_INFORMATION structure contains information about process faults. + */ typedef struct _PROCESS_FAULT_INFORMATION { - ULONG FaultFlags; - ULONG AdditionalInfo; + ULONG FaultFlags; // Flags that provide additional information about the fault. + ULONG AdditionalInfo; // Additional information about the fault. } PROCESS_FAULT_INFORMATION, *PPROCESS_FAULT_INFORMATION; +/** + * The PROCESS_TELEMETRY_ID_INFORMATION structure contains telemetry information about a process. + */ typedef struct _PROCESS_TELEMETRY_ID_INFORMATION { - ULONG HeaderSize; - ULONG ProcessId; - ULONGLONG ProcessStartKey; - ULONGLONG CreateTime; - ULONGLONG CreateInterruptTime; - ULONGLONG CreateUnbiasedInterruptTime; - ULONGLONG ProcessSequenceNumber; - ULONGLONG SessionCreateTime; - ULONG SessionId; - ULONG BootId; - ULONG ImageChecksum; - ULONG ImageTimeDateStamp; - ULONG UserSidOffset; - ULONG ImagePathOffset; - ULONG PackageNameOffset; - ULONG RelativeAppNameOffset; - ULONG CommandLineOffset; + ULONG HeaderSize; // The size of the structure, in bytes. + ULONG ProcessId; // The ID of the process. + ULONGLONG ProcessStartKey; // The start key of the process. + ULONGLONG CreateTime; // The creation time of the process. + ULONGLONG CreateInterruptTime; // The interrupt time at creation. + ULONGLONG CreateUnbiasedInterruptTime; // The unbiased interrupt time at creation. + ULONGLONG ProcessSequenceNumber; // The monotonic sequence number of the process. + ULONGLONG SessionCreateTime; // The session creation time. + ULONG SessionId; // The ID of the session. + ULONG BootId; // The boot ID. + ULONG ImageChecksum; // The checksum of the process image. + ULONG ImageTimeDateStamp; // The timestamp of the process image. + ULONG UserSidOffset; // The offset to the user SID. + ULONG ImagePathOffset; // The offset to the image path. + ULONG PackageNameOffset; // The offset to the package name. + ULONG RelativeAppNameOffset; // The offset to the relative application name. + ULONG CommandLineOffset; // The offset to the command line. } PROCESS_TELEMETRY_ID_INFORMATION, *PPROCESS_TELEMETRY_ID_INFORMATION; +/** + * The PROCESS_COMMIT_RELEASE_INFORMATION structure contains information about the commit and release of memory for a process. + */ typedef struct _PROCESS_COMMIT_RELEASE_INFORMATION { ULONG Version; @@ -1000,7 +1199,7 @@ typedef struct _PROCESS_COMMIT_RELEASE_INFORMATION { ULONG Eligible : 1; ULONG ReleaseRepurposedMemResetCommit : 1; - ULONG ForceReleaseMemResetCommit : 1; + ULONG ForceReleaseMemResetCommit : 1; ULONG Spare : 29; }; SIZE_T CommitDebt; @@ -1008,33 +1207,45 @@ typedef struct _PROCESS_COMMIT_RELEASE_INFORMATION SIZE_T RepurposedMemResetSize; } PROCESS_COMMIT_RELEASE_INFORMATION, *PPROCESS_COMMIT_RELEASE_INFORMATION; +/** + * The PROCESS_JOB_MEMORY_INFO structure contains Represents app memory usage at a single point in time. + * + * \remarks https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-app_memory_information + */ typedef struct _PROCESS_JOB_MEMORY_INFO { - ULONGLONG SharedCommitUsage; - ULONGLONG PrivateCommitUsage; - ULONGLONG PeakPrivateCommitUsage; - ULONGLONG PrivateCommitLimit; - ULONGLONG TotalCommitLimit; + ULONGLONG SharedCommitUsage; // The current shared commit usage, in bytes. + ULONGLONG PrivateCommitUsage; // The current private commit usage, in bytes. + ULONGLONG PeakPrivateCommitUsage; // The peak private commit usage, in bytes. + ULONGLONG PrivateCommitLimit; // The private commit limit, in bytes. + ULONGLONG TotalCommitLimit; // The total commit limit, in bytes. } PROCESS_JOB_MEMORY_INFO, *PPROCESS_JOB_MEMORY_INFO; +/** + * The PROCESS_CHILD_PROCESS_INFORMATION structure contains information about child process policies. + */ typedef struct _PROCESS_CHILD_PROCESS_INFORMATION { - BOOLEAN ProhibitChildProcesses; - BOOLEAN AlwaysAllowSecureChildProcess; // REDSTONE3 - BOOLEAN AuditProhibitChildProcesses; + BOOLEAN ProhibitChildProcesses; // Child processes are prohibited. + BOOLEAN AlwaysAllowSecureChildProcess; // Secure child processes are always allowed. + BOOLEAN AuditProhibitChildProcesses; // Child processes are audited. } PROCESS_CHILD_PROCESS_INFORMATION, *PPROCESS_CHILD_PROCESS_INFORMATION; #define POWER_THROTTLING_PROCESS_CURRENT_VERSION 1 #define POWER_THROTTLING_PROCESS_EXECUTION_SPEED 0x1 #define POWER_THROTTLING_PROCESS_DELAYTIMERS 0x2 #define POWER_THROTTLING_PROCESS_IGNORE_TIMER_RESOLUTION 0x4 // since WIN11 -#define POWER_THROTTLING_PROCESS_VALID_FLAGS ((POWER_THROTTLING_PROCESS_EXECUTION_SPEED | POWER_THROTTLING_PROCESS_DELAYTIMERS | POWER_THROTTLING_PROCESS_IGNORE_TIMER_RESOLUTION)) +#define POWER_THROTTLING_PROCESS_VALID_FLAGS \ + ((POWER_THROTTLING_PROCESS_EXECUTION_SPEED | POWER_THROTTLING_PROCESS_DELAYTIMERS | POWER_THROTTLING_PROCESS_IGNORE_TIMER_RESOLUTION)) +/** + * The POWER_THROTTLING_PROCESS_STATE structure is used to manage the power throttling state of a process. + */ typedef struct _POWER_THROTTLING_PROCESS_STATE { - ULONG Version; - ULONG ControlMask; - ULONG StateMask; + ULONG Version; // The version of the structure. + ULONG ControlMask; // A mask that specifies the control settings for power throttling. + ULONG StateMask; // A mask that specifies the current state of power throttling. } POWER_THROTTLING_PROCESS_STATE, *PPOWER_THROTTLING_PROCESS_STATE; // rev (tyranid) @@ -1714,7 +1925,7 @@ NtResumeProcess( EXTERN_C IMAGE_DOS_HEADER __ImageBase; #define NtCurrentImageBase() ((PIMAGE_DOS_HEADER)&__ImageBase) -#define NtCurrentSessionId() (RtlGetActiveConsoleId()) +#define NtCurrentSessionId() (RtlGetActiveConsoleId()) // USER_SHARED_DATA->ActiveConsoleId #define NtCurrentLogonId() (NtCurrentPeb()->LogonId) /** @@ -1750,6 +1961,25 @@ NtWow64QueryInformationProcess64( _Out_opt_ PULONG ReturnLength ); +/** + * Sets information for the specified process. + * + * @param ProcessHandle A handle to the process. + * @param ProcessInformationClass The type of process information to be set. + * @param ProcessInformation A pointer to a buffer that contains the process information. + * @param ProcessInformationLength The size of the buffer pointed to by the ProcessInformation parameter. + * @return NTSTATUS Successful or errant status. + */ +NTSYSCALLAPI +NTSTATUS +NTAPI +NtSetInformationProcess( + _In_ HANDLE ProcessHandle, + _In_ PROCESSINFOCLASS ProcessInformationClass, + _In_reads_bytes_(ProcessInformationLength) PVOID ProcessInformation, + _In_ ULONG ProcessInformationLength + ); + #define PROCESS_GET_NEXT_FLAGS_PREVIOUS_PROCESS 0x00000001 #if (PHNT_VERSION >= PHNT_WS03) @@ -1760,7 +1990,7 @@ NtWow64QueryInformationProcess64( * @param DesiredAccess The access rights desired for the new process handle. * @param HandleAttributes The attributes for the new process handle. * @param Flags Flags that modify the behavior of the function. This can be a combination of the following flags: - * - PROCESS_GET_NEXT_FLAGS_PREVIOUS_PROCESS (0x00000001): Retrieve the previous process in the system. + * - \ref PROCESS_GET_NEXT_FLAGS_PREVIOUS_PROCESS (0x00000001): Retrieve the previous process in the system. * @param NewProcessHandle A pointer to a variable that receives the handle to the next process. * @return NTSTATUS Successful or errant status. */ @@ -1774,19 +2004,17 @@ NtGetNextProcess( _In_ ULONG Flags, _Out_ PHANDLE NewProcessHandle ); -#endif -#if (PHNT_VERSION >= PHNT_WS03) /** * Retrieves a handle to the next thread in the system. * * @param ProcessHandle A handle to the process for enumerateration of threads. * @param ThreadHandle An optional handle to a thread. If this parameter is NULL, the function retrieves the first thread in the process. - * @param DesiredAccess The access rights desired for the new process handle. - * @param HandleAttributes The attributes for the new process handle. + * @param DesiredAccess The access rights desired for the new thread handle. + * @param HandleAttributes The attributes for the new thread handle. * @param Flags Flags that modify the behavior of the function. This can be a combination of the following flags: - * - THREAD_GET_NEXT_FLAGS_PREVIOUS_THREAD (0x00000001): Retrieve the previous thread in the process. - * @param NewProcessHandle A pointer to a variable that receives the handle to the next process. + * - \ref THREAD_GET_NEXT_FLAGS_PREVIOUS_THREAD (0x00000001): Retrieve the previous thread in the process. + * @param NewThreadHandle A pointer to a variable that receives the handle to the next thread. * @return NTSTATUS Successful or errant status. */ NTSYSCALLAPI @@ -1802,25 +2030,6 @@ NtGetNextThread( ); #endif -/** - * Sets information for the specified process. - * - * @param ProcessHandle A handle to the process. - * @param ProcessInformationClass The type of process information to be set. - * @param ProcessInformation A pointer to a buffer that contains the process information. - * @param ProcessInformationLength The size of the buffer pointed to by the ProcessInformation parameter. - * @return NTSTATUS Successful or errant status. - */ -NTSYSCALLAPI -NTSTATUS -NTAPI -NtSetInformationProcess( - _In_ HANDLE ProcessHandle, - _In_ PROCESSINFOCLASS ProcessInformationClass, - _In_reads_bytes_(ProcessInformationLength) PVOID ProcessInformation, - _In_ ULONG ProcessInformationLength - ); - #endif #define STATECHANGE_SET_ATTRIBUTES 0x0001 @@ -2180,6 +2389,13 @@ NtAlertThreadByThreadId( #endif #if (PHNT_VERSION >= PHNT_WIN11) +/** + * Sends an alert to the specified thread by its thread ID, with an optional lock. + * + * @param ThreadId The thread ID of the thread to be alerted. + * @param Lock An optional pointer to an SRW lock to be used during the alert. + * @return NTSTATUS Successful or errant status. + */ NTSYSCALLAPI NTSTATUS NTAPI @@ -2188,7 +2404,15 @@ NtAlertThreadByThreadIdEx( _In_opt_ PRTL_SRWLOCK Lock ); -// rev +/** + * Sends an alert to multiple threads by their thread IDs. + * + * @param MultipleThreadId A pointer to an array of thread IDs to be alerted. + * @param Count The number of thread IDs in the array. + * @param Boost A pointer to a boost value to be applied to the threads. + * @param BoostCount The number of boost values in the array. + * @return NTSTATUS Successful or errant status. + */ NTSYSCALLAPI NTSTATUS NTAPI