WheaFindNextErrorRecordSection function (ntddk.h)

The WheaFindNextErrorRecordSection function allows a caller to iteratively examine the WHEA error record sections within a WHEA error record. Each error record section is formatted as a WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure.

Syntax

NTSTATUS WheaFindNextErrorRecordSection(
  [in]            PWHEA_ERROR_RECORD                    Record,
  [in, out]       ULONG                                 *Context,
  [out]           PWHEA_ERROR_RECORD_SECTION_DESCRIPTOR *SectionDescriptor,
  [out, optional] PVOID                                 *SectionData
);

Parameters

[in] Record

A pointer to a WHEA error record that is formatted as a WHEA_ERROR_RECORD structure.

[in, out] Context

A pointer to a ULONG variable that maintains the current state of the search.

This variable must be initialized to zero before the first call to the WheaFindNextErrorRecordSection function.

[out] SectionDescriptor

The address of a WHEA_ERROR_RECORD_SECTION_DESCRIPTOR pointer.

If the WheaFindNextErrorRecordSection function locates the next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure within the specified WHEA error record, the function sets the SectionDescriptor parameter to the address of that structure within the specified WHEA error record.

[out, optional] SectionData

The address of a PVOID pointer.

If the WheaFindNextErrorRecordSection function locates the next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure within the specified WHEA error record, the function sets the SectionData parameter to the address of the hardware error data associated with that descriptor.

This parameter is optional and must be set to NULL if a pointer to the error record section data is not required.

Return value

WheaFindNextErrorRecordSection returns one of the following NTSTATUS codes:

Return code Description
STATUS_SUCCESS The next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure was found.
STATUS_NOT_FOUND The next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure was not found.
STATUS_INVALID_PARAMETER Either the Record, SectionType, or SectionDescriptor parameters were set to NULL, or the WHEA_ERROR_RECORD data referenced through the Record parameter is invalid.

Remarks

If the Context parameter is set to 0, WheaFindNextErrorRecordSection returns a pointer to the first WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure within a WHEA error record. WheaFindNextErrorRecordSection will also update the Context parameter with state information related to the WHEA_ERROR_RECORD_SECTION_DESCRIPTOR returned through the SectionDescriptor parameter.

On subsequent calls to WheaFindNextErrorRecordSection, the function returns the next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure (if available) within the WHEA error record. If the function locates the next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure, it will update the Context parameter. Otherwise, the function will return STATUS_NOT_FOUND.

In order to locate the first WHEA_ERROR_RECORD_SECTION_DESCRIPTOR within the specified WHEA error record, the caller must set the variable, whose address is passed in the Context parameter, to 0 before the calling. After that, the caller must not modify the variable's value when locating the next WHEA_ERROR_RECORD_SECTION_DESCRIPTOR through subsequent calls to WheaFindNextErrorRecordSection.

Additionally, if WheaFindNextErrorRecordSection returns STATUS_SUCCESS and the caller set the SectionData parameter to the address of a PVOID pointer variable, the function updates the parameter with the address of the hardware error data associated with the specified WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure.

The format of the hardware error data depends upon the SectionType member of the WHEA_ERROR_RECORD_SECTION_DESCRIPTOR structure that is referenced through the SectionDescriptor parameter. For example, if the SectionType member has the value PROCESSOR_GENERIC_ERROR_SECTION_GUID, the hardware error data is formatted as a WHEA_PROCESSOR_GENERIC_ERROR_SECTION structure.

Requirements

Requirement Value
Minimum supported client Supported in Windows 7 and later versions of Windows.
Target Platform Desktop
Header ntddk.h (include Ntddk.h)
IRQL IRQL <= DISPATCH_LEVEL

See also

Error record

WHEA_ERROR_PACKET

WHEA_ERROR_RECORD

WHEA_ERROR_RECORD_SECTION_DESCRIPTOR