Função WdfRegistryQueryMultiString (wdfregistry.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfRegistryQueryMultiString recupera as cadeias de caracteres atualmente 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 do Registro aberta.

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

Retornar valor

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 sob a chave especificada, mas está vazio.

Para obter uma lista de outros valores retornados que o método WdfRegistryQueryMultiString pode retornar, consulte Erros de criação de objeto de estrutura.

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

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

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 , todos os objetos WDFSTRING criados pela estrutura serão, por padrão, pai do WDFDRIVER.

Depois que WdfRegistryQueryMultiString retornar, o driver poderá 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 drivers de Framework-Based.

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 recupera 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
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfregistry.h (include Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)