WdfFdoInitQueryProperty 函式 (wdffdo.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfFdoInitQueryProperty 方法會擷取指定的裝置屬性。

語法

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

參數

[in] DeviceInit

驅動程式從其 EvtDriverDeviceAdd 回呼函式取得之WDFDEVICE_INIT結構的指標。

[in] DeviceProperty

識別要擷取之裝置屬性 的DEVICE_REGISTRY_PROPERTY型別列舉值。

[in] BufferLength

PropertyBuffer 所指向之緩衝區的大小，以位元組為單位。

[out] PropertyBuffer

呼叫端提供的呼叫端指標，指向接收要求之裝置屬性的呼叫端配置緩衝區。 如果 BufferLength 參數為零，這個指標可以是 NULL。

[out] ResultLength

呼叫端提供的位置，傳回時會包含 WdfFdoInitQueryProperty 儲存在 PropertyBuffer 中之資訊的大小，以位元組為單位。 如果這個方法的傳回值 STATUS_BUFFER_TOO_SMALL，ResultLength 會收到所需的緩衝區大小。

傳回值

如果作業成功，方法會傳回STATUS_SUCCESS。 其他傳回值包括：

傳回碼 Description
STATUS_BUFFER_TOO_SMALL
 提供的緩衝區太小而無法接收資訊。
STATUS_INVALID_PARAMETER_2
 指定的 DeviceProperty 值無效。
STATUS_INVALID_DEVICE_REQUEST
 WDFDEVICE_INIT結構不是從驅動程式的 EvtDriverDeviceAdd 回呼函式取得。
 

方法也可能傳回其他 NTSTATUS值。

備註

在接收裝置屬性數據之前，驅動程式通常必須對 WdfFdoInitQueryProperty 進行初始呼叫，才能取得所需的緩衝區大小。 對於某些屬性，數據大小可以在傳回所需大小的時間和驅動程式再次呼叫此例程的時間之間變更。 因此，驅動程式應該在迴圈內呼叫 WdfFdoInitQueryProperty ，直到傳回狀態未STATUS_BUFFER_TOO_SMALL為止。

最好只有在已知且未變更所需的緩衝區大小時才使用 WdfFdoInitQueryProperty ，因為在此情況下，驅動程式必須只呼叫 WdfFdoInitQueryProperty 一次。 如果必要的緩衝區大小不明或不同，驅動程式應該呼叫 WdfFdoInitAllocAndQueryProperty。

驅動程式只能在呼叫 WdfDeviceCreate 之前呼叫 WdfFdoInitQueryProperty。 如需呼叫 WdfDeviceCreate 的詳細資訊，請參閱 建立 Framework 裝置物件。

呼叫 WdfDeviceCreate 之後，驅動程式可以藉由呼叫 WdfDeviceQueryProperty 來取得裝置屬性資訊。

如需 WdfFdoInitQueryProperty 方法的詳細資訊，請參閱 在函式驅動程式中建立裝置物件。

或者，您可以使用 WdfFdoInitQueryPropertyEx 來存取透過 Unified 屬性模型公開的裝置屬性。

範例

下列程式代碼範例會取得 Unicode 字串，代表裝置列舉值的名稱，如果字串為 “PCI”，則會傳回 TRUE 。

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdffdo.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 合規性規則 DeviceInitAPI (kmdf) 、 DriverCreate (kmdf) 、 KmdfIrql (kmdf ) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另請參閱

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty