Função WdfStringCreate (wdfstring.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfStringCreate cria um objeto de cadeia de caracteres de estrutura e, opcionalmente, atribui uma cadeia de caracteres Unicode especificada ao objeto.

Sintaxe

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

Parâmetros

[in, optional] UnicodeString

Um ponteiro para uma estrutura UNICODE_STRING que contém uma constante de cadeia de caracteres Unicode. A estrutura copia a cadeia de caracteres para o novo objeto de cadeia de caracteres da estrutura. Esse ponteiro é opcional e pode ser NULL.

[in, optional] StringAttributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que contém atributos fornecidos pelo driver para o novo objeto de cadeia de caracteres. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] String

Um ponteiro para um local que recebe um identificador para o novo objeto de cadeia de caracteres.

Valor de retorno

WdfStringCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	WdfStringCreate não foi chamado em IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto de cadeia de caracteres.

Para obter uma lista de outros valores retornados que o método WdfStringCreate pode retornar, consulte Framework Object Creation Errors.

Esse método também pode retornar outros valores NTSTATUS .

Observações

O pai padrão para objetos de cadeia de caracteres da estrutura é o objeto de driver da estrutura do driver. No entanto, a menos que a cadeia de caracteres esteja associada ao driver, o driver deve definir o ParentObject membro da estrutura WDF_OBJECT_ATTRIBUTES para um objeto que represente o escopo da cadeia de caracteres. Normalmente, as cadeias de caracteres são específicas do dispositivo e seu objeto pai deve ser um objeto de dispositivo de estrutura.

Se o driver fornecer EvtCleanupCallback ou EvtDestroyCallback funções de retorno de chamada para o objeto de cadeia de caracteres da estrutura, observe que a estrutura chama essas funções de retorno de chamada em IRQL = PASSIVE_LEVEL.

Para obter mais informações sobre objetos de cadeia de caracteres da estrutura, consulte Usando objetos de cadeia de caracteres.

Exemplos

O exemplo de código a seguir inicializa uma estrutura de WDF_OBJECT_ATTRIBUTES e cria um objeto de cadeia de caracteres de estrutura.

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;
}

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfstring.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString

Compartilhar via