Função PcNewRegistryKey (portcls.h)

Artigo
08/07/2023

A função PcNewRegistryKey abre ou cria uma nova chave do Registro e cria um objeto IRegistryKey para representar a chave. O chamador acessa a chave por meio desse objeto.

Sintaxe

PORTCLASSAPI NTSTATUS PcNewRegistryKey(
  [out]           PREGISTRYKEY       *OutRegistryKey,
  [in, optional]  PUNKNOWN           OuterUnknown,
  [in]            ULONG              RegistryKeyType,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  PVOID              DeviceObject,
  [in, optional]  PVOID              SubDevice,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parâmetros

[out] OutRegistryKey

Ponteiro de saída para o objeto de chave do Registro criado por essa função. Esse parâmetro aponta para uma variável de ponteiro alocada por chamador na qual a função gera o ponteiro para o objeto IRegistryKey. O objeto representa a chave do Registro que está sendo aberta ou criada. Especifique um valor de ponteiro NULL nulo válido para esse parâmetro.

[in, optional] OuterUnknown

Ponteiro para a interface IUnknown de um objeto que precisa agregar o objeto OutRegistryKey. A menos que a agregação seja necessária, defina esse parâmetro para NULL.

[in] RegistryKeyType

Especifica o tipo de chave do Registro que o chamador deseja criar ou abrir. Para obter mais informações, consulte a seção Comentários a seguir.

[in] DesiredAccess

Especifica uma máscara de controle de acesso. Esse parâmetro é uma estrutura do tipo ACCESS_MASK. Indica o tipo de acesso que o chamador está solicitando para a chave do Registro que deve ser aberta ou criada. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] DeviceObject

Ponteiro para o objeto de dispositivo do driver do adaptador. Esse ponteiro é convertido para digitar PVOID. Se RegistryKeyType for qualquer valor diferente de GeneralRegistryKey, esse parâmetro deverá apontar para uma estrutura de sistema válida e inicializada do tipo DEVICE_OBJECT. Se o valor de RegistryKeyType for GeneralRegistryKey, a função PcNewRegistryKey não usará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] SubDevice

Especifica o aspecto do dispositivo que deve ser oferecido aos clientes. Os drivers do adaptador devem atribuir o valor NULL a esse parâmetro.

[in, optional] 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, a função não usará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] CreateOptions

Especifica as opções de criação. Pode ser zero se nenhum for desejado. Se RegistryKeyType não estiver GeneralRegistryKey, a função PcNewRegistryKey ignorará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

[out, optional] Disposition

Ponteiro para uma variável que recebe um valor que indica se uma chave foi criada ou uma chave existente foi aberta. Esse parâmetro é opcional e pode ser especificado como NULL. Se RegistryKeyType for qualquer valor diferente de GeneralRegistryKey, a função PcNewRegistryKey ignorará esse parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

PcNewRegistryKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.

Observações

Se o valor do parâmetro RegistryKeyType for GeneralRegistryKey, a função PcNewRegistryKey abrirá uma chave existente ou criará uma nova chave no registro, conforme indicado pelo valor que a função gera por meio do parâmetro disposição. Se a chave for de qualquer tipo diferente de GeneralRegistryKey, a função abrirá uma chave já existente que foi criada anteriormente durante a enumeração do dispositivo Plug and Play.

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

O parâmetro RegistryKeyType deve ser definido 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. Abra a chave especificada se ela já existir ou crie a chave se ela não existir.
DeviceRegistryKey	Abra uma chave existente que contém informações específicas do dispositivo. A chave está localizada sob a chave da instância do dispositivo especificada por DeviceObject.
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 que contém informações de dispositivo ou driver. Isso permite que o driver acesse informações de configuração específicas do perfil de hardware.
DeviceInterfaceRegistryKey	Não usado com PcNewRegistryKey. Consulte IPort::NewRegistryKey para obter detalhes.

Para um RegistryKeyType valor de GeneralRegistryKey, o chamador deve fornecer um valor de parâmetro ObjectAttributes válido e os parâmetros CreateOptions e Disposição 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 Disposição 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 nome da chave e descritor de segurança. Use a macro InitializeObjectAttributes para inicializar a estrutura. No parâmetro Attributes para essa 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 PcNewRegistryKey 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 a nova chave for do tipo GeneralRegistryKey e o ponteiro do descritor de segurança na estrutura ObjectAttributes for NULL ou o ponteiro ACL no descritor de segurança estiver NULL, a nova chave herdará a ACL da chave pai por padrão.

Se a chave for de qualquer tipo diferente de GeneralRegistryKey, a chave manterá a ACL que Plug and Play atribuiu à chave quando ela foi criada durante a enumeração do dispositivo.

A função PcNewRegistryKey é semelhante ao método IPort::NewRegistryKey, exceto que o objeto do dispositivo e o objeto de porta devem ser explicitamente especificados em uma chamada PcNewRegistryKey, mas estão simplesmente implícitos em uma chamada NewRegistryKey. PcNewRegistryKey é usado principalmente por drivers de adaptador. Os drivers de miniporto normalmente chamam NewRegistryKey.

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	O driver do sistema PortCls implementa a função PcNewRegistryKey no Microsoft Windows 98/Me e no Windows 2000 e em sistemas operacionais posteriores.
da Plataforma de Destino	Universal
cabeçalho	portcls.h (inclua Portcls.h)
biblioteca	Portcls.lib
IRQL	PASSIVE_LEVEL