Функция WdfStringCreate (wdfstring.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfStringCreate создает объект строки платформы и при необходимости присваивает объекту указанную строку Юникода.

Синтаксис

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

Параметры

[in, optional] UnicodeString

Указатель на структуру UNICODE_STRING , содержащую строковую константу Юникода. Платформа копирует строку в новый объект строки платформы. Этот указатель является необязательным и может иметь значение NULL.

[in, optional] StringAttributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , которая содержит предоставленные драйвером атрибуты для нового строкового объекта. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] String

Указатель на расположение, которое получает дескриптор нового строкового объекта.

Возвращаемое значение

WdfStringCreate возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	WdfStringCreate не был вызван в IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить строковый объект.

Список других возвращаемых значений, которые может возвращать метод WdfStringCreate , см. в разделе Ошибки создания объектов платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Родительским объектом по умолчанию для строковых объектов платформы является объект драйвера платформы драйвера. Однако если строка не связана с драйвером, драйвер должен задать для элемента ParentObjectструктуры WDF_OBJECT_ATTRIBUTES объект, представляющий область строки. Как правило, строки зависят от устройства, а их родительский объект должен быть объектом устройства платформы.

Если драйвер предоставляет функции обратного вызова EvtCleanupCallback или EvtDegradCallback для объекта строки платформы, обратите внимание, что платформа вызывает эти функции обратного вызова в 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;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия 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

Поделиться через