Windows kernel opaque structures

The following table contains Windows kernel opaque structures:

Opaque Structure Description
EPROCESS

The EPROCESS structure is an opaque structure that serves as the process object for a process.

Some routines, such as PsGetProcessCreateTimeQuadPart, use EPROCESS to identify the process to operate on. Drivers can use the PsGetCurrentProcess routine to obtain a pointer to the process object for the current process and can use the ObReferenceObjectByHandle routine to obtain a pointer to the process object that is associated with the specified handle. The PsInitialSystemProcess global variable points to the process object for the system process.

Note that a process object is an Object Manager object. Drivers should use Object Manager routines such as ObReferenceObject and ObDereferenceObject to maintain the object's reference count.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

ETHREAD

The ETHREAD structure is an opaque structure that serves as the thread object for a thread.

Some routines, such as PsIsSystemThread, use ETHREAD to identify the thread to operate on. Drivers can use the PsGetCurrentThread routine to obtain a pointer to the thread object for the current thread and can use the ObReferenceObjectByHandle routine to obtain a pointer to the thread object that is associated with the specified handle.

Note that a thread object is an Object Manager object. Drivers should use Object Manager routines such as ObReferenceObject and ObDereferenceObject to maintain the object's reference count.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

EX_RUNDOWN_REF

The EX_RUNDOWN_REF structure is an opaque system structure that contains information about the status of run-down protection for an associated shared object.

typedef struct _EX_RUNDOWN_REF {

  ...  // opaque

} EX_RUNDOWN_REF, *PEX_RUNDOWN_REF;

The run-down protection routines all take a pointer to an EX_RUNDOWN_REF structure as their first parameter. These routines are listed at the bottom of this page.

For more information, see Run-Down Protection.

Header: Wdm.h. Include Wdm.h.

EX_TIMER

The EX_TIMER structure is an opaque structure that is used by the operating system to represent an EX_TIMER timer object.

typedef struct _EX_TIMER *PEX_TIMER;

All members of this structure are opaque to drivers.

The following ExXxxTimer routines require a pointer to a system-allocated EX_TIMER structure as an input parameter:

EX_TIMER-based timer objects are created by the operating system. To get such a timer object, your driver calls the ExAllocateTimer routine. When this object is no longer needed, the driver is responsible for deleting the object by calling ExDeleteTimer.

For more information, see ExXxxTimer Routines and EX_TIMER Objects.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

FAST_MUTEX

A FAST_MUTEX structure is an opaque data structure that represents a fast mutex.

A FAST_MUTEX structure is initialized by the ExInitializeFastMutex routine.

For more information about fast mutexes, see Fast Mutexes and Guarded Mutexes.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_CSQ

The IO_CSQ structure is an opaque structure used to specify the driver's cancel-safe IRP queue routines. Do not set the members of this structure directly. Use IoCsqInitialize or IoCsqInitializeEx to initialize this structure.

For an overview of how to use cancel-safe IRP queues, see Cancel-Safe IRP Queues.

Available on Microsoft Windows XP and later versions of the Windows operating system.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_CSQ_IRP_CONTEXT

The IO_CSQ_IRP_CONTEXT structure is an opaque data structure used to specify the IRP context for an IRP in the driver's cancel-safe IRP queue. It is used as a key by the IoCsqInsertIrp, IoCsqInsertIrpEx, and IoCsqRemoveIrp routines to identify particular IRPs in the queue.

For an overview of how to use cancel-safe IRP queues, see Cancel-Safe IRP Queues.

Available on Microsoft Windows XP and later versions of the Windows operating system.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_WORKITEM

The IO_WORKITEM structure is an opaque structure that describes a work item for a system worker thread.

A driver can allocate a work item by calling IoAllocateWorkItem. Alternatively, a driver can allocate its own buffer, and then call IoInitializeWorkItem to initialize that buffer as a work item.

Any work item that is allocated by IoAllocateWorkItem must be freed by IoFreeWorkItem. Any memory that is initialized by IoInitializeWorkItem must be uninitialized by IoUninitializeWorkItem before it can be freed.

For more information about work items, see System Worker Threads.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KBUGCHECK_CALLBACK_RECORD

The KBUGCHECK_CALLBACK_RECORD structure is an opaque structure that is used by the KeRegisterBugCheckCallback and KeDeregisterBugCheckCallback routines.

The KBUGCHECK_CALLBACK_RECORD structure is used for bookkeeping by the KeRegisterBugCheckReasonCallback and KeDeregisterBugCheckReasonCallback routines.

The structure must be allocated in resident memory, such as nonpaged pool. Use the KeInitializeCallbackRecord routine to initialize the structure before using it.

Header: Ntddk.h. Include: Ntddk.h.

KBUGCHECK_REASON_CALLBACK_RECORD

The KBUGCHECK_REASON_CALLBACK_RECORD structure is an opaque structure that is used by the KeRegisterBugCheckReasonCallback and KeDeregisterBugCheckReasonCallback routines.

The KBUGCHECK_REASON_CALLBACK_RECORD structure is used for bookkeeping by the KeRegisterBugCheckReasonCallback and KeDeregisterBugCheckReasonCallback routines.

The structure must be allocated in resident memory, such as nonpaged pool. Use the KeInitializeCallbackRecord routine to initialize the structure before using it.

Available on Microsoft Windows XP with Service Pack 1 (SP1), Windows Server 2003, and later versions of the Windows operating system.

Header: Ntddk.h. Include: Ntddk.h.

KDPC

The KDPC structure is an opaque structure that represents a DPC object. Do not set the members of this structure directly. See DPC Objects and DPCs.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KFLOATING_SAVE

The KFLOATING_SAVE structure is an opaque structure that describes the floating-point state that the KeSaveFloatingPointState routine saved.

Use KeRestoreFloatingPointState to restore the floating-point state.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KGUARDED_MUTEX

The KGUARDED_MUTEX structure is an opaque structure that represents a guarded mutex.

Use KeInitializeGuardedMutex to initialize a KGUARDED_MUTEX structure as a guarded mutex.

Guarded mutexes must be allocated from non-paged pool.

For more information about guarded mutexes, see Fast Mutexes and Guarded Mutexes.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KINTERRUPT

A KINTERRUPT structure is an opaque structure that represents an interrupt to the system.

IoConnectInterruptEx provides a pointer to the KINTERRUPT structure for the interrupt when the driver registers an InterruptService or InterruptMessageService routine. The driver uses this pointer when acquiring or releasing the interrupt spin lock for the interrupt. The driver also uses this pointer when unregistering an InterruptService routine.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KLOCK_QUEUE_HANDLE

The KLOCK_QUEUE_HANDLE structure is an opaque structure that describes a queued spin lock. The driver allocates the KLOCK_QUEUE_HANDLE structure, and passes it to KeAcquireInStackQueuedSpinLock and KeAcquireInStackQueuedSpinLockAtDpcLevel to acquire the queued spin lock. Those routines initialize the structure to represent the queued spin lock. The driver passes the structure to KeReleaseInStackQueuedSpinLock and KeReleaseInStackQueuedSpinLockFromDpcLevel when releasing the spin lock.

For more information, see Queued Spin Locks.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KTIMER

The KTIMER structure is an opaque structure that represents a timer object. Do not set the members of this structure directly. For more information, see Timer Objects and DPCs.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

LOOKASIDE_LIST_EX

The LOOKASIDE_LIST_EX structure describes a lookaside list.

typedef struct _LOOKASIDE_LIST_EX {
  ...  // opaque
} LOOKASIDE_LIST_EX, *PLOOKASIDE_LIST_EX;

A lookaside list is a pool of fixed-size buffers that the driver can manage locally to reduce the number of calls to system allocation routines and, thereby, to improve performance. The buffers are of uniform size and are stored as entries in the lookaside list.

Drivers should treat the LOOKASIDE_LIST_EX structure as opaque. Drivers that access structure members or that have dependencies on the locations of these members might not remain portable and interoperable with other drivers.

The following See Also section contains a list of the routines that use this structure.

For more information about lookaside lists, see Using Lookaside Lists.

On 64-bit platforms, this structure must be 16-byte aligned.

Supported starting with Windows Vista.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

NPAGED_LOOKASIDE_LIST

The NPAGED_LOOKASIDE_LIST structure is an opaque structure that describes a lookaside list of fixed-size buffers allocated from nonpaged pool. The system creates new entries and destroys unused entries on the list as necessary. For fixed-size buffers, using a lookaside list is quicker than allocating memory directly.

Use ExInitializeNPagedLookasideList to initialize the lookaside list. Use ExAllocateFromNPagedLookasideList to allocate a buffer from the list, and ExFreeToNPagedLookasideList to return a buffer to the list.

Drivers must always explicitly free any lookaside lists they create before unloading. It is a serious programming error to do otherwise. Use ExDeleteNPagedLookasideList to free the list.

Drivers can also use lookaside lists for paged pool. Starting with Windows 2000, a PAGED_LOOKASIDE_LIST structure describes a lookaside list that contains paged buffers. Starting with Windows Vista, a LOOKASIDE_LIST_EX structure can describe a lookaside list that contains either paged or nonpaged buffers. For more information, see Using Lookaside Lists.

On 64-bit platforms, this structure must be 16-byte aligned.

Supported starting with Windows 2000.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

OBJECT_TYPE

OBJECT_TYPE is an opaque structure that specifies the object type of a handle. For more information, see ObReferenceObjectByHandle.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

PAGED_LOOKASIDE_LIST

The PAGED_LOOKASIDE_LIST structure is an opaque structure that describes a lookaside list of fixed-size buffers allocated from paged pool. The system creates new entries and destroys unused entries on the list as necessary. For fixed-size buffers, using a lookaside list is quicker than allocating memory directly.

Use ExInitializePagedLookasideList to initialize the lookaside list. Use ExAllocateFromPagedLookasideList to allocate a buffer from the list, and ExFreeToPagedLookasideList to return a buffer to the list.

Drivers must always explicitly free any lookaside lists they create before unloading. It is a serious programming error to do otherwise. Use ExDeletePagedLookasideList to free the list.

Drivers can also use lookaside lists for nonpaged pool. Starting with Windows 2000, an NPAGED_LOOKASIDE_LIST structure describes a lookaside list that contains nonpaged buffers. Starting with Windows Vista, a LOOKASIDE_LIST_EX structure can describe a lookaside list that contains either paged or nonpaged buffers. For more information, see Using Lookaside Lists.

On 64-bit platforms, this structure must be 16-byte aligned.

Supported starting with Windows 2000.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

RTL_BITMAP

The RTL_BITMAP structure is an opaque structure that describes a bitmap.

typedef struct _RTL_BITMAP {
  // opaque
} RTL_BITMAP, *PRTL_BITMAP;

Do not directly access the members of this structure. Drivers that have dependencies on member locations or that access member values directly might not remain compatible with future versions of the Windows operating system.

The RTL_BITMAP structure serves as a header for a general-purpose, one-dimensional bitmap of arbitrary length. A driver can use such a bitmap as an economical way to keep track of a set of reusable items. For example, a file system can use bitmaps to track which clusters and sectors on a hard disk have already been allocated to hold file data.

For a list of the RtlXxx routines that use RTL_BITMAP structures, see the following See Also section. The caller of these RtlXxx routines is responsible for allocating the storage for the RTL_BITMAP structure and for the buffer that contains the bitmap. This buffer must begin on a four-byte boundary in memory and must be a multiple of four bytes in length. The bitmap begins at the start of the buffer but can contain any number of bits that will fit in the allocated buffer.

Before supplying an RTL_BITMAP structure as a parameter to an RtlXxx routine, call the RtlInitializeBitMap routine to initialize the structure. The input parameters to this routine are a pointer to a buffer that contains the bitmap, and the size, in bits, of the bitmap. RtlInitializeBitMap does not change the contents of this buffer.

If the caller allocates the storage for the RTL_BITMAP structure and bitmap in paged memory, the caller must be running at IRQL <= APC_LEVEL when it passes a pointer to this structure as a parameter to any of the RtlXxx routines that are listed in the See Also section. If the caller allocates the storage from nonpaged memory (or, equivalently, from paged memory that is locked), the caller can be running at any IRQL when it calls the RtlXxx routine.

Supported in Windows 2000 and later versions of Windows.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

RTL_RUN_ONCE

The RTL_RUN_ONCE structure is an opaque structure that stores the information for a one-time initialization.

Drivers must initialize this structure by calling the RtlRunOnceInitialize routine before passing it to any other RtlRunOnceXxx routines.

Available only on Windows Vista and later versions of the Windows operating system.

Header: Ntddk.h. Include: Ntddk.h.

SECURITY_SUBJECT_CONTEXT

The SECURITY_SUBJECT_CONTEXT structure is an opaque structure that represents the security context within which a particular operation is taking place.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

SLIST_HEADER

An SLIST_HEADER structure is an opaque structure that serves as the header for a sequenced singly linked list. For more information, see Singly and Doubly Linked Lists.

On 64-bit platforms, SLIST_HEADER structures must be 16-byte aligned.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

XSTATE_SAVE

The XSTATE_SAVE structure is an opaque structure that describes the extended processor state information that a kernel-mode driver saves and restores.

typedef struct _XSTATE_SAVE {
  ...  // opaque
} XSTATE_SAVE, *PXSTATE_SAVE;

All members are opaque.

This structure is used by the KeSaveExtendedProcessorState and KeRestoreExtendedProcessorState routines.

Supported in Windows 7 and later versions of the Windows operating system.

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

BugCheckDumpIoCallback
BugCheckSecondaryDumpDataCallback
ExAcquireFastMutex
ExAcquireFastMutexUnsafe
ExAllocateFromLookasideListEx
ExAllocateFromNPagedLookasideList
ExAllocateFromPagedLookasideList
ExAllocateTimer
ExDeletePagedLookasideList
ExFreeToPagedLookasideList
ExInitializePagedLookasideList
ExCancelTimer
ExDeleteLookasideListEx
ExDeleteNPagedLookasideList
ExDeleteTimer
ExFlushLookasideListEx
ExFreeToLookasideListEx
ExFreeToNPagedLookasideList
ExInitializeLookasideListEx
ExInitializeNPagedLookasideList
ExInitializeSListHead
ExInterlockedFlushSList
ExInterlockedPopEntrySList
ExInterlockedPushEntrySList
ExQueryDepthSList
ExReleaseFastMutex
ExReleaseFastMutexUnsafe
ExSetTimer
ExTryToAcquireFastMutex
ExTimerCallback
IoAllocateWorkItem
IoConnectInterruptEx
IoCsqInitialize
IoCsqInitializeEx
IoCsqInsertIrp
IoCsqInsertIrpEx
IoCsqRemoveIrp
IoDisconnectInterruptEx
IoFreeWorkItem
IoInitializeWorkItem
IoRequestDpc
IoUninitializeWorkItem
KeAcquireGuardedMutex
KeAcquireGuardedMutexUnsafe
KeAcquireInStackQueuedSpinLock
KeAcquireInStackQueuedSpinLockAtDpcLevel
KeAcquireInterruptSpinLock
KeCancelTimer
KeInitializeCallbackRecord
KeInitializeGuardedMutex
KeInitializeTimer
KeInitializeTimerEx
KeReadStateTimer
KeRestoreExtendedProcessorState
KeSaveExtendedProcessorState
KeSetTimer
KeSetTimerEx
KeDeregisterBugCheckCallback
KeDeregisterBugCheckReasonCallback
KeInsertQueueDpc
KeRegisterBugCheckCallback
KeRegisterBugCheckReasonCallback
KeReleaseGuardedMutexUnsafe
KeReleaseInStackQueuedSpinLock
KeReleaseInStackQueuedSpinLockFromDpcLevel
KeReleaseInterruptSpinLock
KeRestoreFloatingPointState
KeSaveFloatingPointState
KeSynchronizeExecution
LookasideListAllocateEx
LookasideListFreeEx
ObReferenceObjectByHandle
PsGetCurrentProcess
PsGetProcessCreateTimeQuadPart
PsInitialSystemProcess
PsIsSystemThread
RtlRunOnceBeginInitialize
RtlRunOnceComplete
RtlRunOnceExecuteOnce
RtlRunOnceInitialize
RunOnceInitialization
Run-Down Protection
SeAccessCheck
SeAssignSecurity
SeAssignSecurityEx


Send comments about this topic to Microsoft