Método IRegistryKey::NewSubKey (portcls.h)

Artigo
02/07/2025

O método NewSubKey cria uma nova subchave do Registro ou abre uma subchave existente sob a chave representada pelo objeto IRegistryKey.

Sintaxe

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

Parâmetros

[out] RegistrySubKey

Ponteiro de saída para a nova subchave. Esse parâmetro aponta para uma variável de ponteiro alocada por chamador na qual o método grava o ponteiro no novo objeto IRegistryKey. Esse objeto representa a subchave que está sendo aberta ou criada. Especifique um valor de ponteiro NULL nulo válido para esse parâmetro.

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

[in] DesiredAccess

Especifica o tipo de acesso que o chamador requer para a subchave que está sendo aberta ou criada. Esse parâmetro é do tipo ACCESS_MASK. Para obter mais informações, consulte a seção Comentários a seguir.

[in] SubKeyName

Ponteiro para o nome que deve ser atribuído à subchave. Esse parâmetro deve ser um ponteiro nulo de nulo válido para uma estrutura inicializada do tipo UNICODE_STRING.

[in] CreateOptions

Sinalizadores que indicam as opções de criação. Pode ser zero se nenhum for desejado. Esse parâmetro será necessário se o valor de RegistryKeyType for 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.

[out, optional] Disposition

Ponteiro de saída para o valor de disposição. Esse parâmetro aponta para uma variável ULONG alocada pelo chamador na qual o método grava um valor de 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 dele. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

NewSubKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida na saída de um ponteiro de IRegistryKey válido pelo parâmetro RegistrySubKey. Caso contrário, o método retornará um código de erro apropriado.

Observações

O método NewSubKey abrirá a chave do Registro especificada se ela já existir ou criará uma nova chave no registro se ela não existir. O método gera um ponteiro para a interface IRegistryKey da nova chave por meio do parâmetro RegistrySubKey. O método também gera um valor de status por meio do parâmetro Disposição opcional para indicar se a chave foi aberta ou criada.

Os parâmetros DesiredAccess, CreateOptionse Disposição assumem os valores definidos para os parâmetros com os mesmos nomes na chamada PcNewRegistryKey.

O parâmetro DesiredAccess é uma máscara de controle de acesso que especifica o tipo de controle de acesso que o chamador precisa ter para a subchave ao acessá-lo por meio do objeto RegistrySubKey. Essa máscara não deve ser confundida com a ACL (lista de controle de acesso) que controla o acesso dos usuários à subchave do Registro. Quando a função PcNewRegistryKey ou método IPort::NewRegistryKey cria uma chave de registro do tipo GeneralRegistryKey, o parâmetro ObjectAttributes especifica os atributos da chave, incluindo um descritor de segurança que contém a ACL. Quando o método NewSubKey cria uma nova subchave do Registro, no entanto, essa subchave simplesmente herda a ACL de sua chave pai. O método NewSubKey não fornece meios para especificar uma ACL que difere da chave pai.

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