Função PcNewRegistryKey (portcls.h)
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 pelo 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 não NULL 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 como 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 no tipo 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 for 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 se 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.
Retornar valor
PcNewRegistryKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.
Comentários
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 Disposition . Se a chave for de qualquer tipo diferente de GeneralRegistryKey, a função abrirá uma chave já existente que foi criada anteriormente durante Plug and Play enumeração do dispositivo.
Os parâmetros DesiredAccess, ObjectAttributes, CreateOptions e 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 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 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 for 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 atribuída à chave quando ela foi criada durante a enumeração do dispositivo.
A função PcNewRegistryKey é semelhante ao método IPort::NewRegistryKey , exceto pelo fato de 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 é usado principalmente por drivers de adaptador. Em vez disso, 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 |
|---|---|
| Cliente mínimo com suporte | O driver do sistema PortCls implementa a função PcNewRegistryKey no Microsoft Windows 98/Me e no Windows 2000 e em sistemas operacionais posteriores. |
| Plataforma de Destino | Universal |
| Cabeçalho | portcls.h (inclua Portcls.h) |
| Biblioteca | Portcls.lib |
| IRQL | PASSIVE_LEVEL |