Diretiva AddReg do INF

Artigo
06/14/2023

Uma diretiva AddReg faz referência a uma ou mais seções de _add-registry-sections definidas pelo gravador INF* que são usadas para modificar ou criar informações do Registro.

[DDInstall] | 
[DDInstall.HW] | 
[DDInstall.CoInstallers] | 
[ClassInstall32] | 
[ClassInstall32.ntx86] | 
[ClassInstall32.ntia64] | (Windows XP and later versions of Windows)
[ClassInstall32.ntamd64] | (Windows XP and later versions of Windows) 
[ClassInstall32.ntarm] | (Windows 8 and later versions of Windows) 
[ClassInstall32.ntarm64] | (Windows 10 version 1709 and later versions of Windows) 
[install-interface-section] | 
[service-install-section] | 
[event-log-install] | 
[add-interface-section]

AddReg=add-registry-section[,add-registry-section] ...

Cada seção add-registry pode ter entradas para fazer o seguinte:

Adicione novas chaves, possivelmente com entradas de valor inicial, ao registro.
Adicione novas entradas de valor às chaves do Registro existentes.
Modifique as entradas de valor existentes de chaves específicas no registro.

Cada seção add-registry nomeada referenciada por uma diretiva AddReg tem o seguinte formato:

[add-registry-section]
reg-root,[subkey],[value-entry-name],[flags],[value][,[value]]
reg-root,[subkey],[value-entry-name],[flags],[value][,[value]]
 ...

[[add-registry-section.security]
"security-descriptor-string"]

Uma seção add-registry pode ter qualquer número de entradas, cada uma em uma linha separada. Um INF também pode conter uma ou mais seções opcionais add-registry-section.security, cada uma especificando um descritor de segurança que é aplicado a todos os valores do Registro descritos em uma seção add-registry nomeada.

Entradas

reg-root
Identifica a raiz da árvore do Registro para outros valores fornecidos nesta entrada. O valor pode ser um dos seguintes:

HKCR
Abreviação para HKEY_CLASSES_ROOT

HKCU
Abreviação para HKEY_CURRENT_USER

HKLM
Abreviação para HKEY_LOCAL_MACHINE

HKU
Abreviação para HKEY_USERS

HKR
Raiz relativa, na qual as chaves especificadas usando essa abreviação são relativas à chave do Registro associada à seção INF na qual essa diretiva AddReg aparece, conforme indicado na tabela a seguir.

Seção INF que contém a diretiva AddReg	Chave do Registro Referenciada por HKR
Seção *INF DDInstall*	A chave de software do dispositivo
INF DDInstall. Seção HW	A chave de hardware do dispositivo
Seção INF [service-install-section]	A chave serviços
Seção INF [event-log-install]	A chave EventLog
Seção INF [add-interface-section]	A chave do Registro da interface do dispositivo

Observação

O HKR não pode ser usado em uma seção add-registry referenciada de uma seção INF DefaultInstall.

Para obter mais informações sobre informações de driver armazenadas na raiz HKEY_LOCAL_MACHINE , consulte Árvores e Chaves do Registro para Dispositivos e Drivers.

subkey
Esse valor opcional, formado como um token %strkey% definido em uma seção Strings do INF ou como um caminho do Registro sob a raiz reg fornecida (key1\key2\key3...), especifica um dos seguintes:

Uma nova subchave a ser adicionada ao registro no final do caminho do Registro fornecido.
Uma subchave existente na qual os valores adicionais especificados nesta entrada são gravados (possivelmente substituindo o valor de uma entrada de valor nomeado existente da subchave fornecida).
Uma nova subchave a ser adicionada ao registro junto com sua entrada de valor inicial.

value-entry-name
Esse valor opcional nomeia uma entrada de valor existente na subchave fornecida (existente) ou cria o nome de uma nova entrada de valor a ser adicionada na subchave especificada, independentemente de ela já existir ou ser uma nova chave a ser adicionada ao Registro. Esse valor pode ser expresso como "cadeia de caracteres entre aspas" ou como um token %strkey% definido na seção Cadeias de Caracteres do INF. (Se isso for omitido para um valor de tipo de cadeia de caracteres, o valor-entry-name será a entrada de valor "sem nome" padrão para essa chave.)

O sistema operacional dá suporte a algumas palavras-chave especial value-entry-name definidas pelo sistema. Confira o final desta seção Comentários para obter mais informações.

sinalizadores
Esse valor hexadecimal opcional, expresso como uma máscara de bits ORed de valores de sinalizador de palavra baixa e palavra alta definidos pelo sistema, define o tipo de dados para uma entrada de valor e/ou controla a operação de registro de adição.

Os valores de máscara de bits para cada um desses sinalizadores são os seguintes:

0x00000001 (FLG_ADDREG_BINVALUETYPE)
O valor fornecido é dados "brutos". (Esse valor é idêntico ao FLG_ADDREG_TYPE_BINARY.)

0x00000002 (FLG_ADDREG_NOCLOBBER)
Impedir que um determinado valor substitua o valor de uma entrada de valor existente.

0x00000004 (FLG_ADDREG_DELVAL)
Exclua a subchave especificada do registro ou exclua a subchave value-entry-name especificada da subchave do Registro especificada.

0x00000008 (FLG_ADDREG_APPEND)
Acrescente um determinado valor ao de uma entrada de valor nomeado existente. Esse sinalizador só será válido se FLG_ADDREG_TYPE_MULTI_SZ também estiver definido. O valor de cadeia de caracteres especificado não será acrescentado se ele já existir.

0x00000010 (FLG_ADDREG_KEYONLY)
Crie a subchave fornecida, mas ignore qualquer valor fornecido value-entry-name e/ou valor.

0x00000020 (FLG_ADDREG_OVERWRITEONLY)
Redefina para o valor fornecido somente se o valor-entry-name especificado já existir na subchave fornecida.

0x00001000 (FLG_ADDREG_64BITKEY)
(Windows XP e versões posteriores do Windows.) Faça a alteração especificada no registro de 64 bits. Se não for especificado, a alteração será feita no registro nativo.

0x00002000 (FLG_ADDREG_KEYONLY_COMMON)
(Windows XP e versões posteriores do Windows.) Isso é o mesmo que FLG_ADDREG_KEYONLY, mas também funciona em uma del-registry-section de uma diretiva INF DelReg.

0x00004000 (FLG_ADDREG_32BITKEY)
(Windows XP e versões posteriores do Windows.) Faça a alteração especificada no registro de 32 bits. Se não for especificado, a alteração será feita no registro nativo.

0x00000000 (FLG_ADDREG_TYPE_SZ)
A entrada de valor e/ou valor fornecido é do tipo REG_SZ.

Observação

Esse valor é o tipo padrão para uma entrada de valor especificada, portanto, o valor de sinalizadores pode ser omitido de qualquer linha reg-root= em uma seção add-registry que opera em uma entrada de valor desse tipo.

0x00010000 (FLG_ADDREG_TYPE_MULTI_SZ)
A entrada de valor e/ou valor fornecido é do tipo de registro REG_MULTI_SZ. O campo de valor a seguir pode ser uma lista de cadeias de caracteres separadas por vírgulas. Essa especificação não requer nenhum terminador NULL para um determinado valor de cadeia de caracteres.

0x00020000 (FLG_ADDREG_TYPE_EXPAND_SZ)
O valor especificado value-entry-name e /ou é do tipo de registro REG_EXPAND_SZ.

0x00010001 (FLG_ADDREG_TYPE_DWORD)
O valor fornecido value-entry-name e /ou é do tipo de registro REG_DWORD.

0x00020001 (FLG_ADDREG_TYPE_NONE)
O valor especificado value-entry-name e /ou é do tipo de registro REG_NONE.

value
Isso especifica opcionalmente um novo valor para o valor-entry-name especificado a ser adicionado à chave do Registro fornecida. Esse valor pode ser um valor de "substituição" para uma entrada de valor nomeada existente em uma chave existente, um valor a ser acrescentado (valor desinalizador 0x00010008) a uma entrada de valor de tipo REG_MULTI_SZ nomeada existente em uma chave existente, uma nova entrada de valor a ser gravada em uma chave existente ou a entrada de valor inicial para uma nova subchave a ser adicionada ao registro.

A expressão desse valor depende do tipo de registro especificado para o sinalizador, da seguinte maneira:

Um valor de tipo de cadeia de caracteres do Registro pode ser expresso como uma "cadeia de caracteres entre aspas" ou como um token %strkey% definido em uma seção Strings do arquivo INF. Esse valor especificado por INF não precisa incluir um terminador NULL no final de cada cadeia de caracteres.
Um valor de tipo numérico do registro pode ser expresso como um hexadecimal (usando notação 0x) ou número decimal.

security-descriptor-string
Especifica um descritor de segurança, a ser aplicado a todas as entradas do Registro criadas pela seção add-registry-section nomeada. A cadeia de caracteres de descritor de segurança é uma cadeia de caracteres com tokens para indicar o componente de segurança DACL (D:).

Se uma seção add-registry-section.security não for especificada, as entradas do Registro herdarão as configurações de segurança da chave pai.

Se uma seção add-registry-section.security for especificada, as seguintes ACE deverão ser incluídas para que instalações e atualizações de dispositivos e service packs do sistema possam ocorrer:

(A;; GA;;; SY) – concede a todos os acessos ao sistema local.
(A;; GA;;; BA) – concede a todos os acessos a administradores internos.

Não especifique cadeias de caracteres ACE que concedem acesso de gravação a usuários nãoprivilegiados.

Para obter informações sobre cadeias de caracteres de descritor de segurança, consulte Linguagem de definição do descritor de segurança (Windows). Para obter informações sobre o formato das cadeias de caracteres do descritor de segurança, consulte Linguagem de definição do descritor de segurança (Windows).

Para obter mais informações sobre como especificar descritores de segurança, consulte Criando instalações de dispositivo seguro.

Comentários

Uma diretiva AddReg pode ser especificada em qualquer uma das seções mostradas na instrução de sintaxe formal acima. Essa diretiva também pode ser especificada em qualquer uma das seguintes seções definidas pelo gravador INF:

Uma seção service-install-section ou event-log-install referenciada pela diretiva AddService em um INF DDInstall. Seção Serviços.
Uma seção add-interface referenciada pela diretiva AddInterface em um INF DDInstall. Seção Interfaces.
Uma seção install-interface referenciada em uma seção INTERFACEInstall32 do INF.

Cada nome da seção add-registry deve ser exclusivo para o arquivo INF, mas pode ser referenciado por diretivas AddReg em outras seções do mesmo INF. Cada nome de seção deve seguir as regras gerais para definir nomes de seção descritos em Regras gerais de sintaxe para arquivos INF.

Observação

O bit de ordem inferior da palavra baixa em um valor de sinalizador distingue entre dados binários e de caractere.

Para representar um número de um tipo de registro diferente de um dos tipos REG_XXX predefinidos, especifique um novo número de tipo na palavra alta do sinalizador ORed com FLG_ADDREG_BINVALUETYPE em sua palavra baixa.

Os dados desse valor devem ser especificados no formato binário como uma sequência de bytes separados por vírgulas. Por exemplo, para armazenar 16 bytes de dados de um novo tipo de dados do Registro, como 0x38, como uma entrada de valor, a entrada da seção add-registry seria algo semelhante ao seguinte:

HKR,,MYValue,0x00380001,1,0,2,3,4,5,6,7,8,9,A,B,C,D,E,F

Essa técnica pode ser usada para definir novos tipos de registro para valores numéricos, mas não para valores do tipo REG_EXPAND_SZ, REG_MULTI_SZ, REG_NONE ou REG_SZ. Para obter mais informações sobre esses tipos, consulte Tipos de valor do Registro.

Palavras-chave especial value-entry-name

Palavras-chave especiais são definidas para uso nas entradas AddReg do HKR. O formato das entradas que usam essas palavras-chave é o seguinte:

[HKR,,DeviceCharacteristics,0x10001,characteristics] 
[HKR,,DeviceType,0x10001,device-type] 
[HKR,,Security,,security-descriptor-string] 
[HKR,,UpperFilters,0x10000,service-name] 
[HKR,,LowerFilters,0x10000,service-name] 
[HKR,,Exclusive,0x10001,exclusive-device] 
[HKR,,EnumPropPages32,,"prop-provider.dll,provider-entry-point"]
[HKR,,LocationInformationOverride,,"text-string"] 
[HKR,,ResourcePickerTags,,"text-string"] 
[HKR,,ResourcePickerExceptions,,"text-string"] ,

O seguinte descreve as entradas AddReg do HKR que usam estas palavras-chave especiais:

DeviceCharacteristics
Uma entrada DeviceCharacteristics HKR AddReg especifica características para o dispositivo. O valor de características é um valor numérico que é o resultado do uso de OR em um ou mais valores de características de arquivo FILE_*, que são definidos em Wdm.h e Ntddk.h.

Somente os seguintes valores podem ser especificados em um INF:

#define FILE_REMOVABLE_MEDIA            0x00000001
#define FILE_READ_ONLY_DEVICE           0x00000002
#define FILE_FLOPPY_DISKETTE            0x00000004
#define FILE_WRITE_ONCE_MEDIA           0x00000008
#define FILE_DEVICE_SECURE_OPEN         0x00000100

Para obter uma descrição desses valores, consulte IoCreateDevice.

Os valores de características, que são especificados usando uma entrada DeviceCharacteristics , são ORed com aqueles especificados em cada chamada para IoCreateDevice que cria um objeto de dispositivo na pilha do dispositivo. A operação OR ocorre depois que todos os objetos do dispositivo são adicionados, mas antes do dispositivo ser iniciado.

O valor de características (incluindo um valor zero) substitui todas as características de dispositivo de toda a classe especificadas no INF do instalador de classe associado.

Para obter mais informações sobre características do dispositivo, consulte Especificando características do dispositivo.

DeviceType
Uma entrada DeviceType HKR AddReg especifica um tipo de dispositivo para o dispositivo. O tipo de dispositivo é o valor numérico de uma constante FILE_DEVICE_XXX definida em Wdm.h ou Ntddk.h. O valor do sinalizador de 0x10001 especifica que o valor do tipo dispositivo é um REG_DWORD. Para obter mais informações, consulte Especificando tipos de dispositivo.

Um INF do instalador de classe deve especificar o tipo de dispositivo que se aplica a todos, ou quase todos, dos dispositivos na classe . Por exemplo, se os dispositivos na classe forem do tipo FILE_DEVICE_CD_ROM, especifique um tipo de dispositivo de 0x02. Se um INF do dispositivo especificar um valor para DeviceType, ele substituirá o valor definido pelo instalador de classe, se houver. Se a classe ou o dispositivo INF especificar um valor DeviceType , o gerenciador PnP aplicará esse tipo ao PDO (objeto de dispositivo físico) criado pelo driver de barramento do dispositivo.

Segurança
Uma entrada HKR AddReg de segurança especifica um descritor de segurança para o dispositivo. A cadeia de caracteres de descritor de segurança é uma cadeia de caracteres com tokens para indicar o componente de segurança DACL (D:).

Um INF do instalador de classe pode especificar um descritor de segurança para uma classe de dispositivo. Um INF do dispositivo pode especificar um descritor de segurança para um dispositivo individual, substituindo a segurança da classe. Se a classe e/ou o dispositivo INF especificar uma cadeia de caracteres de descritor de segurança, o gerenciador PnP propagará o descritor para todos os objetos do dispositivo ( DOs) para um dispositivo. Isso inclui o FDO (objeto do dispositivo de função), os DOs de filtro opcionais e o PDO.

Para obter informações sobre o formato das cadeias de caracteres do descritor de segurança, consulte a documentação SDK do Microsoft Windows.

Para obter mais informações sobre como especificar descritores de segurança, consulte Criando instalações de dispositivo seguro.

Upperfilters
Uma entrada UpperFilters HKR AddReg especifica um driver de filtro superior PnP. Essa entrada em uma DDInstall. A seção HW define um ou mais drivers de filtro superior específicos do dispositivo. Em uma seção ClassInstall32 , essa entrada define um ou mais drivers de filtro superior em toda a classe.

Lowerfilters
Uma entrada LowerFilters HKR AddReg especifica um driver de filtro inferior PnP. Essa entrada em uma DDInstall. A seção HW define um ou mais drivers de filtro inferior específicos do dispositivo. Em uma seção ClassInstall32 , essa entrada define um ou mais drivers de filtro inferior em toda a classe.

Exclusive
Uma entrada HKR AddRegexclusiva, se ela existir e estiver definida como "1", especifica que o dispositivo é um dispositivo exclusivo. Caso contrário, o dispositivo não será tratado como exclusivo. Para obter mais informações, consulte Especificando o acesso exclusivo a objetos de dispositivo.

EnumPropPages32
Uma entrada EnumPropPages32 HKR AddReg especifica o nome de um arquivo DLL (biblioteca de vínculo dinâmico) que é um provedor de página de propriedades específico do dispositivo. Ele também especifica o nome da função de retorno de chamada ExtensionPropSheetPageProc , conforme implementado pela DLL. Para obter mais informações sobre páginas de propriedades e funções, consulte o Microsoft Windows Software Development Kit (SDK) para Windows 7 e .NET Framework 4.0.

Importante

O nome da função de retorno de chamada DLL e ExtensionPropSheetPageProc deve ser colocado entre aspas (" ").

LocationInformationOverride
(Windows XP e versões posteriores do Windows) Uma entrada LocationInformationOverride HKR AddReg pode ser usada para especificar uma cadeia de caracteres de texto que descreve a localização física de um dispositivo. Ele substitui a cadeia de caracteres LocationInformation que o driver de ônibus do dispositivo fornece em resposta a uma solicitação de IRP_MN_QUERY_DEVICE_TEXT .

ResourcePickerTags
Uma entrada ResourcePickerTags HKR AddReg especifica marcas de seletor de recursos para um dispositivo.

ResourcePickerExceptions
Uma entrada ResourcePickerExceptions HKR AddReg especifica os conflitos de recursos permitidos para um dispositivo.

Exemplos

Uma diretiva AddReg referenciou a seção (SCSI) Miniport_EventLog_AddReg neste exemplo, em uma seção definida pelo gravador INF referenciada pela diretiva AddService em uma DDInstall. Seção de serviços deste INF.

[Miniport_EventLog_AddReg]
HKR,,EventMessageFile,0x00020000,"%%SystemRoot%%\System32\IoLogMsg.dll" 
; double quotation marks delimiters in preceding entry prevent truncation 
; if line wraps
 
HKR,,TypesSupported,0x00010001,7

Observe que você pode especificar valores de sinalizador no formato hexadecimal, conforme mostrado no exemplo, ou pode definir espaços reservados de cadeia de caracteres, como %FLG_ADDREG_TYPE_DWORD% na seção [Strings] de cada arquivo INF.