Função WdfRegistryQueryMultiString (wdfregistry.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfRegistryQueryMultiString recupera as cadeias de caracteres atribuídas a um valor de registro de várias cadeias de caracteres especificado, cria um objeto de cadeia de caracteres de estrutura para cada cadeia de caracteres e adiciona cada objeto de cadeia de caracteres a uma coleção de objetos especificada.

Sintaxe

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

Parâmetros

[in] Key

Um identificador para um objeto de chave do Registro que representa uma chave aberta do Registro.

[in] ValueName

Um ponteiro para uma estrutura UNICODE_STRING que contém um nome de valor.

[in, optional] StringsAttributes

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

[in] Collection

Um identificador para um objeto de coleção de estruturas fornecido pelo driver.

Valor de retorno

WdfRegistryQueryMultiString 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	WdfRegistryQueryMultiString 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.
STATUS_ACCESS_DENIED	O driver não abriu a chave do Registro com acesso KEY_QUERY_VALUE, KEY_READ ou KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	O tipo de dados do valor do registro especificado pelo parâmetro ValueName não foi REG_MULTI_SZ.
STATUS_OBJECT_NAME_NOT_FOUND	O valor do Registro não estava disponível.
STATUS_RESOURCE_DATA_NOT_FOUND	O valor do Registro existe na chave especificada, mas está vazio.

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

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

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Antes que o driver chame WdfRegistryQueryMultiString, ele deve chamar WdfCollectionCreate para criar um objeto de coleção.

Se o chamador não fornecer um parâmetro StringsAttributes, quaisquer objetos WDFSTRING criados pela estrutura serão, por padrão, pai do WDFDRIVER.

Depois que WdfRegistryQueryMultiString retorna, o driver pode chamar WdfCollectionGetCount para obter o número de cadeias de caracteres recuperadas e WdfCollectionGetItem para obter objetos de cadeia de caracteres da coleção.

Se a coleção contiver objetos antes que o driver chame o método WdfRegistryQueryMultiString, o método não removerá esses objetos nem alterará seus valores de índice. Os novos objetos são acrescentados ao final da coleção.

Para obter uma cadeia de caracteres de um objeto de cadeia de caracteres, o driver pode chamar WdfStringGetUnicodeString.

Para obter mais informações sobre objetos de chave do Registro, consulte Usando o Registro em Framework-Based Drivers.

Exemplos

O exemplo de código a seguir cria um objeto de coleção, inicializa uma estrutura WDF_OBJECT_ATTRIBUTES para que o objeto da coleção seja o pai de todos os objetos de cadeia de caracteres que a estrutura cria para a coleção e recupere as cadeias de caracteres de um valor de registro de várias cadeias de caracteres. Por fim, o exemplo obtém o número de objetos de cadeia de caracteres que a estrutura adicionou à coleção.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

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	wdfregistry.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

WdfCollectionCreate

WdfCollectionGetCount

WdfCollectionGetItem

WdfRegistryQueryMemory

WdfRegistryQueryString

WdfRegistryQueryULong

WdfRegistryQueryUnicodeString

WdfRegistryQueryValue

WdfStringGetUnicodeString

Compartilhar via