Método IPort::NewRegistryKey (portcls.h)

O método NewRegistryKey abre uma chave do Registro existente ou cria uma nova chave no Registro. O método cria um objeto registry-key para representar a chave e gera uma referência a esse objeto para o chamador. Em seguida, o chamador acessa a chave por meio da interface IRegistryKey do objeto.

Sintaxe

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

Parâmetros

OutRegistryKey

Ponteiro para uma variável de ponteiro alocada pelo chamador na qual o método grava a referência no objeto IRegistryKey. Esse objeto representa a chave do Registro que está sendo aberta ou criada. O chamador deve especificar um valor de ponteiro válido e não NULL para esse parâmetro.

OuterUnknown

Ponteiro para a interface IUnknown de um objeto que precisa agregar o objeto de chave do Registro. Esse parâmetro é opcional. Se a agregação não for necessária, especifique esse parâmetro como NULL.

RegistryKeyType

Especifica o tipo de chave do Registro ao qual o chamador está solicitando acesso. Para obter mais informações, consulte a seção Comentários a seguir.

DesiredAccess

Uma máscara de controle de acesso que especifica o tipo de acesso que o chamador requer à chave. Esse parâmetro é do tipo ACCESS_MASK. Para obter mais informações, consulte a seção Comentários a seguir.

ObjectAttributes

Ponteiro para os atributos de objeto da chave que está sendo criada ou aberta. Se RegistryKeyType tiver o valor GeneralRegistryKey, esse parâmetro deverá apontar para uma estrutura de sistema válida e inicializada do tipo OBJECT_ATTRIBUTES com uma cadeia de caracteres ObjectName válida para a chave; caso contrário, o método não usará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

CreateOptions

Sinalizadores que indicam as opções de criação. Pode ser zero se nenhum for desejado. Esse parâmetro será necessário se RegistryKeyType tiver o valor GeneralRegistryKey; caso contrário, o método não usará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

Disposition

Ponteiro para uma variável ULONG alocada pelo chamador na qual o método grava um valor status indicando se uma nova chave foi criada ou se uma chave existente foi aberta. Esse parâmetro é opcional e pode ser especificado como NULL se o chamador não precisar do valor status. O método usará esse parâmetro somente se RegistryKeyType tiver o valor GeneralRegistryKey. O método não usa o parâmetro para nenhum dos outros tipos de chave. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

Esse método retorna NTSTATUS, que contém STATUS_SUCCESS se a chamada foi bem-sucedida. Caso contrário, o método retornará um código de erro apropriado.

Comentários

Os parâmetros DesiredAccess, ObjectAttributes e Disposition assumem os valores definidos para os parâmetros com os mesmos nomes na chamada ZwCreateKey.

Se o parâmetro RegistryKeyType tiver o valor GeneralRegistryKey, o método NewRegistryKey abrirá uma chave do Registro existente ou criará uma nova chave no Registro, conforme indicado pelo valor que o método gera por meio do parâmetro Disposition. Se o tipo de chave for qualquer valor diferente de GeneralRegistryKey, o método abrirá uma chave já existente que foi criada anteriormente durante Plug and Play enumeração do dispositivo.

O chamador deve definir o parâmetro RegistryKeyType como um dos valores de enumeração mostrados na tabela a seguir.

Valor registryKeyType	Significado
GeneralRegistryKey	Forneça acesso genérico a qualquer tipo de chave. Abrirá a chave se ela existir ou criará a chave se não existir.
DeviceRegistryKey	Abra uma chave existente que contém informações específicas do dispositivo.
DriverRegistryKey	Abra uma chave existente que contém informações específicas do driver.
HwProfileRegistryKey	Abra uma chave existente em relação ao perfil de hardware atual para informações de dispositivo ou driver. Isso permite que o driver acesse informações de configuração específicas do perfil de hardware.
DeviceInterfaceRegistryKey	Abra uma chave do Registro existente contendo informações sobre uma instância específica da interface do dispositivo.

Para um valor RegistryKeyType de GeneralRegistryKey, o chamador deve fornecer um valor de parâmetro ObjectAttributes válido e os parâmetros CreateOptions e Disposition são opcionais. Para qualquer outro valor RegistryKeyType, o chamador deve fornecer um valor de parâmetro DeviceObject válido e os parâmetros CreateOptions e Disposition não são usados.

O parâmetro ObjectAttributes aponta para uma estrutura opaca do tipo OBJECT_ATTRIBUTES que contém atributos de objeto, como o nome da chave e o descritor de segurança. Use a macro InitializeObjectAttributes para inicializar a estrutura. No parâmetro Atributos dessa macro, defina o sinalizador OBJ_KERNEL_HANDLE, a menos que você pretenda permitir que aplicativos não seguros no modo de usuário tenham acesso de leitura/gravação à chave do Registro.

O parâmetro DesiredAccess é uma máscara de controle de acesso. Ele especifica o tipo de controle de acesso que o chamador precisa ter para a nova chave do Registro ao acessá-la por meio do objeto OutRegistryKey. Essa máscara não deve ser confundida com a ACL (lista de controle de acesso) que controla o acesso dos usuários à chave do Registro. Ao chamar NewRegistryKey para criar uma chave do Registro do tipo GeneralRegistryKey, o parâmetro ObjectAttributes especifica os atributos da chave, incluindo um descritor de segurança que contém a ACL. No entanto, se o tipo de chave for GeneralRegistryKey e o ponteiro do descritor de segurança na estrutura ObjectAttributes for NULL ou o ponteiro ACL no descritor de segurança for NULL, a nova chave criada pela chamada herdará a ACL da chave pai por padrão.

Se a chave não for do tipo GeneralRegistryKey, a chave manterá a ACL que Plug and Play atribuída à chave quando ela foi criada durante a enumeração do dispositivo.

O método NewRegistryKey é semelhante à função PcNewRegistryKey, exceto que o objeto do dispositivo e o objeto de porta devem ser especificados explicitamente em uma chamada PcNewRegistryKey, mas são simplesmente implícitos em uma chamada NewRegistryKey. PcNewRegistryKey normalmente é chamado por drivers de adaptador. Em vez disso, os drivers de miniporto normalmente chamam NewRegistryKey.

Depois que uma chave do Registro tiver sido criada ou aberta por uma chamada para NewRegistryKey ou PcNewRegistryKey, o método IRegistryKey::NewSubKey poderá ser usado para criar subchaves sob essa chave.

Os parâmetros OutRegistryKey e OuterUnknown seguem as convenções de contagem de referência para objetos COM.

Requisitos

Requisito	Valor
Cabeçalho	portcls.h
IRQL	PASSIVE_LEVEL

Confira também

Iport