WdfStringCreate 函式 (wdfstring.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfStringCreate 方法會建立架構字串物件，並選擇性地將指定的 Unicode 字串指派給物件。

語法

NTSTATUS WdfStringCreate(
  [in, optional] PCUNICODE_STRING       UnicodeString,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringAttributes,
  [out]          WDFSTRING              *String
);

參數

[in, optional] UnicodeString

包含 Unicode 字串常數 之UNICODE_STRING 結構的指標。 架構會將字串複製到新的架構字串物件。 此指標是選擇性的，而且可以是 NULL。

[in, optional] StringAttributes

WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新字串對象的驅動程式提供屬性。 這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] String

接收新字串物件句柄之位置的指標。

傳回值

如果作業成功，WdfStringCreate 會傳回STATUS_SUCCESS。 否則，方法可能會傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_DEVICE_REQUEST

在 IRQL = PASSIVE_LEVEL 未呼叫 WdfStringCreate。
STATUS_INVALID_PARAMETER
 指定了無效的參數。
STATUS_INSUFFICIENT_RESOURCES
 無法設定字串物件。
 

如需 WdfStringCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

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

備註

架構字串對象的預設父系是驅動程式的架構驅動程序物件。 不過，除非字串與驅動程式相關聯，否則驅動程式應該將WDF_OBJECT_ATTRIBUTES結構的ParentObject成員設定為代表字串範圍的物件。 一般而言，字串是裝置特定的，而且其父對象應該是架構裝置物件。

如果您的驅動程式提供 Framework 字串物件的 EvtCleanupCallback 或 EvtDestroyCallback 回 呼函式，請注意，架構會在 IRQL = PASSIVE_LEVEL呼叫這些回呼函式。

如需架構字串物件的詳細資訊，請參閱 使用字串物件。

範例

下列程式代碼範例會初始化 WDF_OBJECT_ATTRIBUTES 結構，然後建立架構字串物件。

NTSTATUS  status;
WDFSTRING  stringHandle = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = pDeviceContext->Device;
status = WdfStringCreate(
                         NULL,
                         &attributes,
                         &stringHandle
                         );
if (!NT_SUCCESS(status)){
    return status;
}

規格需求

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

另請參閱

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString