StorPortEtwLogByteStream 函数 (storport.h)

项目
03/05/2024

StorPortEtwLogByteStream 使用常规用途字节流参数将 Windows (ETW) 事件跟踪记录到指定的通道。

语法

ULONG StorPortEtwLogByteStream(
  [in]           PVOID                      HwDeviceExtension,
  [in, optional] PSTOR_ADDRESS              Address,
  [in]           STORPORT_ETW_EVENT_CHANNEL EventChannel,
  [in]           ULONG                      EventId,
  [in]           PWSTR                      EventDescription,
  [in]           ULONGLONG                  EventKeywords,
  [in]           STORPORT_ETW_LEVEL         EventLevel,
  [in]           STORPORT_ETW_EVENT_OPCODE  EventOpcode,
  [in]           USHORT                     DataLength,
  [in]           PUCHAR                     Data
);

参数

[in] HwDeviceExtension

指向微型端口的设备扩展的指针。

[in, optional] Address

存储单元设备地址。对于适配器设备，此参数为 NULL。

[in] EventChannel

一个STORPORT_ETW_EVENT_CHANNEL值，该值标识要记录事件的 ETW 通道。

[in] EventId

唯一标识事件的微型端口定义的事件 ID。

[in] EventDescription

描述事件的短字符串。 EventDescription 是必需的，并且必须为 <= STORPORT_ETW_MAX_DESCRIPTION_LENGTH 个字符，不包括 NULL 终止符。

[in] EventKeywords

事件分类的关键字标志。如果不需要关键字 (keyword) ，则设置为 0。关键字是以下各项的按位 OR 组合。

值	含义
STORPORT_ETW_EVENT_KEYWORD_IO	事件与设备 IO 操作相关。
STORPORT_ETW_EVENT_KEYWORD_PERFORMANCE	事件与性能相关。
STORPORT_ETW_EVENT_KEYWORD_POWER	该事件与设备电源相关。
STORPORT_ETW_EVENT_KEYWORD_ENUMERATION	事件与设备枚举相关。

[in] EventLevel

事件级别。此值可以指示事件的重要性或严重性。这是以下值之一。

值	含义
StorportEtwLevelLogAlways	无条件地记录事件。无论设置何种筛选器，都会记录事件。
StorportEtwLevelCritical	关键级别事件。
StorportEtwLevelError	错误级别事件。
StorportEtwLevelWarning	警告级别事件。
StorportEtwLevelInformational	信息性事件。
StorportEtwLevelVerbose	提供的详细事件信息。

[in] EventOpcode

事件的操作性质。这是以下值之一。

值	含义
StorportEtwEventOpcodeInfo	常规信息性事件。
StorportEtwEventOpcodeStart	设备或单元正在启动。
StorportEtwEventOpcodeStop	设备或设备正在停止。该事件对应于上一个不成对的开始事件。
StorportEtwEventOpcodeDC_Start	数据收集开始事件。这些是 rundown 事件类型。
StorportEtwEventOpcodeDC_Stop	数据收集停止事件。这些是 rundown 事件类型。
StorportEtwEventOpcodeExtension	扩展事件。
StorportEtwEventOpcodeReply	回复事件。
StorportEtwEventOpcodeResume	设备或单元在暂停后正在恢复。
StorportEtwEventOpcodeSuspend	设备或单元挂起，等待完成其他操作。
StorportEtwEventOpcodeReceive	从另一个组件接收活动的传输。

[in] DataLength

Data 指向的字节流的长度（以字节为单位），其中 1 <= DataLength<= STORPORT_ETW_MAX_BYTE_STREAM_LENGTH。

[in] Data

指向微型端口的自定义 ETW 字节流的指针。

返回值

StorPortEtwLogByteStream 返回以下状态代码之一：

返回代码	说明
STOR_STATUS_SUCCESS	事件已成功记录到指定的 ETW 通道。
STOR_STATUS_INVALID_PARAMETER	参数无效。例如， HwDeviceExtension、 EventDescription 或 Data 为 NULL，DataLength 大于最大名称长度， EventChannel 为无效值。
STOR_STATUS_UNSUCCESSFUL	由于其他内部原因而返回。

注解

微型端口可以调用 StorPortEtwLogByteStream ，以使用常规用途字节流参数将 ETW 事件记录到特定通道。

当微型端口需要记录 StorPortEtwEvent2、StorPortEtwEvent4 或 StorPortEtwEvent8 中允许的上下文时，StorPortEtwLogByteStream 非常有用。例如，微型端口可以将其内部数据结构记录为字节流，然后在报告问题时将其用于诊断目的。