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

Artigo
08/07/2023

O NewSubKey método 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 pelo 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 não NULL 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 não NULL 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 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.

Retornar valor

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

Comentários

O NewSubKey método 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 status por meio do parâmetro disposição opcional para indicar se a chave foi aberta ou criada.

Os parâmetros DesiredAccess, CreateOptions e Disposition 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 o método IPort::NewRegistryKey cria 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, quando o NewSubKey método cria uma nova subchave do Registro, essa subchave simplesmente herda a ACL de sua chave pai. O NewSubKey método não fornece meios para especificar uma ACL diferente da chave pai.

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