DEVICE_CAPABILITIES 結構 (wdm.h)

發行項
05/23/2024

DEVICE_CAPABILITIES結構描述裝置的 PnP 和電源功能。此結構會傳回以回應 IRP_MN_QUERY_CAPABILITIES IRP。

語法

typedef struct _DEVICE_CAPABILITIES {
  USHORT             Size;
  USHORT             Version;
  ULONG              DeviceD1 : 1;
  ULONG              DeviceD2 : 1;
  ULONG              LockSupported : 1;
  ULONG              EjectSupported : 1;
  ULONG              Removable : 1;
  ULONG              DockDevice : 1;
  ULONG              UniqueID : 1;
  ULONG              SilentInstall : 1;
  ULONG              RawDeviceOK : 1;
  ULONG              SurpriseRemovalOK : 1;
  ULONG              WakeFromD0 : 1;
  ULONG              WakeFromD1 : 1;
  ULONG              WakeFromD2 : 1;
  ULONG              WakeFromD3 : 1;
  ULONG              HardwareDisabled : 1;
  ULONG              NonDynamic : 1;
  ULONG              WarmEjectSupported : 1;
  ULONG              NoDisplayInUI : 1;
  ULONG              Reserved1 : 1;
  ULONG              WakeFromInterrupt : 1;
  ULONG              SecureDevice : 1;
  ULONG              ChildOfVgaEnabledBridge : 1;
  ULONG              DecodeIoOnBoot : 1;
  ULONG              Reserved : 9;
  ULONG              Address;
  ULONG              UINumber;
  DEVICE_POWER_STATE DeviceState[POWER_SYSTEM_MAXIMUM];
  SYSTEM_POWER_STATE SystemWake;
  DEVICE_POWER_STATE DeviceWake;
  ULONG              D1Latency;
  ULONG              D2Latency;
  ULONG              D3Latency;
} DEVICE_CAPABILITIES, *PDEVICE_CAPABILITIES;

成員

Size

指定結構的大小，以位元組為單位。此欄位是由傳送 IRP_MN_QUERY_CAPABILITIES 要求的元件所設定。

Version

指定結構的版本，目前為第 1 版。此欄位是由傳送 IRP_MN_QUERY_CAPABILITIES 要求的元件所設定。

DeviceD1

指定裝置硬體是否支援 D1 電源狀態。驅動程式不應該變更此值。

DeviceD2

指定裝置硬體是否支援 D2 電源狀態。驅動程式不應該變更此值。

LockSupported

指定裝置是否支援防止裝置退出的實體裝置鎖定。此成員與從其位置退出裝置有關，而不是從裝置退出卸載式媒體。

EjectSupported

指定當系統處於 PowerSystemWorking 狀態時，裝置是否支援軟體控制的裝置退出。此成員與從其位置退出裝置有關，而不是從裝置退出卸載式媒體。

Removable

指定是否可以從其立即父系動態移除裝置。如果 Removable 設定為 TRUE，則裝置不屬於與其父代相同的實體物件。

例如，如果多功能印表機內的USB複合裝置設定為 TRUE ，複合裝置就不屬於其立即父系的實體物件，例如筆記本電腦內的USB中樞。

在大部分情況下，總線驅動程式不是函式驅動程式，應該判斷裝置的 Removable 參數值。針對 USB 裝置，USB 中樞驅動程式會設定 可移動 參數。函式驅動程式不應修改它。

如果 [卸除式 ] 設定為 TRUE，則裝置會顯示在 [拔除] 或 [退出硬體 ] 程式中，除非 SurpriseRemovalOK 也設定為 TRUE。

DockDevice

指定裝置是否為停駐周邊。

UniqueID

指定裝置的實例識別碼是否為全系統的唯一標識符。如果實例標識碼只在總線範圍內是唯一的，則這個位是清楚的。如需詳細資訊，請參閱裝置識別字串。

SilentInstall

指定裝置管理員是否應該隱藏所有安裝對話方塊，但必要對話方塊除外，例如「找不到相容的驅動程式」。

RawDeviceOK

指定如果沒有函式驅動程式 (，基礎總線的驅動程式是否可以驅動裝置，例如傳遞模式中的 SCSI 裝置) 。此作業模式稱為原始模式。

SurpriseRemovalOK

指定裝置的函式驅動程式是否可以在 Windows 將 IRP_MN_QUERY_REMOVE_DEVICE 傳送至裝置之前，先處理移除裝置的情況。如果 SurpriseRemovalOK 設定為 TRUE，則不論其驅動程式所在的狀態為何，都可以安全地從其立即父代移除裝置。

例如，標準 USB 滑鼠不會在其硬體中維持任何狀態，因此可以隨時安全地移除。不過，無法安全地移除驅動程式快取記憶體中寫入的外部硬碟，而不需要先讓驅動程式將快取排清到硬體。

支援意外移除之 USB 裝置的驅動程式只有在將 IRP 傳回驅動程式堆疊時，才會將此設定為 TRUE 。

WakeFromD0

指定裝置是否可以在處於 D0 狀態時回應外部喚醒訊號。驅動程式不應該變更此值。

WakeFromD1

指定裝置是否可以在處於 D1 狀態時回應外部喚醒訊號。驅動程式不應該變更此值。

WakeFromD2

指定裝置是否可以在處於 D2 狀態時回應外部喚醒訊號。驅動程式不應該變更此值。

WakeFromD3

指定裝置是否可以在處於 D3 狀態時回應外部喚醒訊號。驅動程式不應該變更此值。

HardwareDisabled

設定時，此旗標會指定裝置的硬體已停用。

當這類驅動程式判斷裝置硬體已停用時，裝置的父總線驅動程式或總線篩選驅動程式會設定此旗標。

PnP 管理員會在列舉裝置之後立即傳送一個 IRP_MN_QUERY_CAPABILITIES IRP，並在裝置啟動之後傳送另一個。 PnP 管理員只會在列舉裝置之後立即檢查此位。裝置啟動之後，會忽略此位。

NonDynamic

保留供未來使用。

WarmEjectSupported

保留供未來使用。

NoDisplayInUI

請勿在使用者介面中顯示裝置。如果設定此位，即使裝置存在但無法啟動，裝置也不會顯示在使用者介面中。只有總線驅動程式和相關聯的總線篩選驅動程式應該設定這個位。 (另請參閱 PNP_DEVICE_STATE structure.) 中的 PNP_DEVICE_DONT_DISPLAY_IN_UI 旗標

Reserved1

保留供系統使用。

WakeFromInterrupt

指出驅動程式或 ACPI 是否負責處理喚醒事件。如果設定，驅動程式會負責處理喚醒事件。 ACPI 會在裝置收到IRP_MN_WAIT_WAKE IRP 時使用裝置，但不會連接中斷，請完成 IRP 以通知裝置堆疊喚醒事件。

SecureDevice

指出裝置是否為安全裝置。

ChildOfVgaEnabledBridge

針對 VGA 裝置，指出父網橋是否已設定 VGA 譯碼位。

DecodeIoOnBoot

指出裝置在開機時是否已啟用 IO 譯碼。

Reserved

保留供系統使用。

Address

指定位址，指出裝置在其基礎總線上的位置。

此數位的解譯是總線特定的。如果位址未知，或總線驅動程式不支持位址，則總線驅動程式會將此成員保留為其預設值0xFFFFFFFF。

下列清單描述特定總線驅動程式儲存在其子裝置的 [位址 ] 字段中的資訊：

匯流排	Description
1394	不會提供地址，因為位址是變動的。默認為 0xFFFFFFFF。
EISA	插槽號碼 (0-F) 。
IDE	若為 IDE 裝置，位址會包含目標標識碼和 LUN。若為 IDE 通道，位址為零或一個 (0 = 主要通道，而 1 = 次要通道) 。
ISApnp	不提供位址。默認為 0xFFFFFFFF。
PC Card (PCMCIA)	套接字號碼 (通常會0x00或0x40) 。
PCI	高字的裝置編號，以及低字的函式編號。
SCSI	目標標識碼。
USB	連接埠號碼。

UINumber

指定與可在使用者介面中顯示的裝置相關聯的數位。

此數位通常是使用者感知的插槽編號，例如在面板上的位置旁邊列印的數位，或一些其他數位，可讓使用者更輕鬆地尋找實體裝置。對於沒有這類慣例的公交車，或當 UINumber 未知時，總線驅動程式會將此成員保留為其預設值0xFFFFFFFF。

DeviceState[POWER_SYSTEM_MAXIMUM]

值陣列，表示裝置可針對每個系統電源狀態維護的最電源狀態電源狀態。陣列的 DeviceState[PowerSystemWorking] 元素會對應至 S0 系統狀態。 PowerSystemUnspecified 的專案保留給系統使用。

此陣列中的專案是以父代 devnode 的功能為基礎。一般規則是驅動程序不應該變更這些值。不過，如有必要，驅動程式可以將值從 PowerDeviceD1 降低到 PowerDeviceD2。

如果總線驅動程式無法判斷根列舉裝置的適當裝置電源狀態，則會將 DeviceState[PowerSystemWorking] 設定為 PowerDeviceD0 ，並將所有其他項目設定為 PowerDeviceD3。

SystemWake

指定裝置可以發出喚醒事件訊號的最低電源狀態。 PowerSystemUnspecified 的值表示裝置無法喚醒系統。

總線驅動程式可以從其父代開發節點取得這項資訊。

一般而言，驅動程式不應該變更此值。不過，如有必要，驅動程式可以引發電源狀態，例如，從 PowerSystemHibernate 到 PowerSystemS1，表示其裝置無法從休眠狀態喚醒系統，但可以從較高電源的睡眠狀態喚醒系統。

DeviceWake

指定裝置可發出喚醒事件訊號的最低電源狀態。 PowerDeviceUnspecified 的值表示裝置無法發出喚醒事件的訊號。

D1Latency

以 100 毫秒為單位指定裝置的近似最差案例延遲，以便將裝置從 PowerDeviceD1 狀態傳回至 PowerDeviceD0 狀態。如果裝置不支援 D1 狀態，請將設定為零。

D2Latency

以 100 毫秒為單位指定裝置的近似最差案例延遲，以從 PowerDeviceD2 狀態將裝置傳回 至 PowerDeviceD0 狀態。如果裝置不支援 D2 狀態，請將設定為零。

D3Latency

以 100 毫秒為單位指定裝置的近似最差案例延遲，以便將裝置從 PowerDeviceD3 狀態傳回至 PowerDeviceD0 狀態。如果裝置不支援 D3 狀態，請將設定為零。

備註

總線驅動程式會在此結構中設定適當的值，以回應 IRP_MN_QUERY_CAPABILITIES IRP。總線篩選驅動程式、函式驅動程式和篩選驅動程式可能會改變總線驅動程式所設定的功能。

傳送 IRP_MN_QUERY_CAPABILITIES 要求的驅動程序必須先初始化這個結構 的大小、版本、位址和 UINumber 成員，再傳送 IRP。

如需使用 DEVICE_CAPABILITIES 結構來描述裝置電源功能的詳細資訊，請參閱報告裝置電源功能。

規格需求

需求	值
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)

另請參閱

IRP_MN_QUERY_CAPABILITIES

PNP_DEVICE_STATE

共用方式為

DEVICE_CAPABILITIES 結構 (wdm.h)

語法

成員

備註

規格需求

另請參閱

意見反應

其他資源