Função CmCallbackGetKeyObjectIDEx (wdm.h)

Artigo
03/08/2023

A rotina CmCallbackGetKeyObjectIDEx recupera o identificador exclusivo e o nome do objeto associados a um objeto de chave do Registro especificado.

Essa rotina está disponível a partir do Windows 8. Em versões anteriores do Windows, use a rotina CmCallbackGetKeyObjectID . Para obter mais informações, consulte a seção Comentários abaixo.

Sintaxe

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

Parâmetros

[in] Cookie

Um valor de cookie que representa o registro do chamador para receber retornos de chamada de filtro do Registro. O driver obteve anteriormente esse valor de cookie da rotina CmRegisterCallback ou CmRegisterCallbackEx .

[in] Object

Um ponteiro para o objeto de chave do Registro. Esse parâmetro é o valor do ponteiro que a rotina de retorno de chamada RegistryCallback do driver recebeu no membro Object de uma das estruturas REG_XXX_KEY_INFORMATION .

Aviso

Em determinadas circunstâncias, as estruturas de notificação de retorno de chamada do Registro podem conter ponteiros de objeto não NULL inválidos. Os drivers de filtragem do Registro não devem passar esses ponteiros para essa rotina. Para obter mais informações, confira Ponteiros de objeto de chave inválidos em notificações do Registro.

[out, optional] ObjectID

Um ponteiro para um local que recebe um ponteiro para o identificador de chave da chave do Registro que Object representa. Esse identificador é exclusivo em todas as chaves do Registro. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários abaixo..

[out, optional] ObjectName

Um ponteiro para um local que recebe um ponteiro para uma estrutura UNICODE_STRING . Essa estrutura contém o nome do objeto de chave do Registro especificado por Object . O nome do objeto é, na verdade, o nome do caminho completo da chave do Registro que o objeto representa. O chamador é responsável por liberar essa estrutura chamando a rotina CmCallbackReleaseKeyObjectIDEx . Esse parâmetro é opcional e pode ser NULL. Para obter mais informações, consulte Comentários.

[in] Flags

Reservado. Defina como zero.

Retornar valor

CmCallbackGetKeyObjectIDEx retornará STATUS_SUCCESS se a operação for bem-sucedida. Os possíveis valores retornados por erro incluem o seguinte código de status:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O parâmetro Cookie, Object ou Flags é inválido.

Comentários

Os drivers podem usar CmCallbackGetKeyObjectIDEx para obter o identificador de chave do Registro, o nome do objeto ou ambos, fornecendo valores não NULL para os parâmetros ObjectID ou ObjectName .

O chamador pode obter o identificador de chave por meio do parâmetro ObjectID . Se dois objetos de chave do Registro representarem a mesma chave do Registro, os identificadores de chave obtidos de CmCallbackGetKeyObjectIDEx para os dois objetos serão idênticos. Se o nome da chave do Registro for alterado, o identificador de chave obtido de CmCallbackGetKeyObjectIDEx não será alterado. O chamador pode usar o identificador de chave para controlar de forma confiável os acessos que são feitos a uma chave do Registro específica por meio de vários objetos de chave e até mesmo entre alterações no nome da chave do Registro.

O chamador pode obter o nome do objeto por meio do parâmetro ObjectName . O armazenamento da estrutura UNICODE_STRING que contém o nome do objeto permanece válido até que o chamador chame CmCallbackReleaseKeyObjectIDEx para liberar a estrutura.

CmCallbackGetKeyObjectIDEx é uma versão aprimorada da rotina CmCallbackGetKeyObjectID , que está disponível a partir do Windows Vista. Os drivers executados em versões do Windows anteriores a Windows 8 devem chamar CmCallbackGetKeyObjectID em vez de CmCallbackGetKeyObjectIDEx. Os drivers executados somente em Windows 8 e versões posteriores do Windows devem chamar CmCallbackGetKeyObjectIDEx em vez de CmCallbackGetKeyObjectID.

CmCallbackGetKeyObjectIDEx tem dois recursos importantes que não estão disponíveis em CmCallbackGetKeyObjectID.

Primeiro, CmCallbackGetKeyObjectIDEx permite que um driver de filtro do Registro controle explicitamente o tempo de vida da estrutura ObjectName . O driver pode chamar CmCallbackReleaseKeyObjectIDEx a qualquer momento para liberar essa estrutura. Por outro lado, o driver não pode liberar explicitamente a estrutura ObjectName recebida de CmCallbackGetKeyObjectID. Essa estrutura é liberada automaticamente quando todos os identificadores para a chave são fechados.

Em segundo lugar, se um driver de filtro do Registro chamar CmCallbackGetKeyObjectID para obter um ponteiro de estrutura ObjectName e, após essa chamada, o nome da chave do Registro for alterado, as chamadas subsequentes para CmCallbackGetKeyObjectID obterão um ponteiro para uma cópia obsoleta da estrutura ObjectName , que contém o nome da chave antiga. A cópia obsoleta dessa estrutura persiste até que todos os identificadores para a chave sejam fechados. Por outro lado, a estrutura ObjectName obtida de CmCallbackGetKeyObjectIDEx sempre contém o nome de chave mais atualizado.

Para obter mais informações sobre drivers de filtro do Registro, consulte Filtrando chamadas do Registro.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL