Diretiva INF AddPowerSetting
Uma diretiva AddPowerSetting faz referência a uma ou mais seções que são usadas para modificar ou criar informações de configuração de energia. Cada seção add-power-setting define uma configuração de energia, os valores permitidos para a configuração de energia, o nome amigável da configuração de energia e a descrição da configuração de energia. Uma seção add-power-setting também especifica o valor padrão para cada personalidade do esquema de energia. Para obter mais informações sobre as configurações de energia e as personalidades do esquema de energia, consulte Gerenciando estados de desempenho do dispositivo.
[DDInstall] |
[DDInstall.HW] |
[DDInstall.CoInstallers] |
[ClassInstall32] |
[ClassInstall32.ntx86] |
[ClassInstall32.ntia64] | (Windows Vista)
[ClassInstall32.ntamd64] | (Windows Vista)
[ClassInstall32.ntarm] | (Windows 8 and later versions of Windows)
[ClassInstall32.ntarm64] (Windows 10 version 1709 and later versions of Windows)
AddPowerSetting=add-power-setting-section[,add-power-setting-section]
Em geral, uma seção add-power-setting inclui as seguintes diretivas:
Uma diretiva SubGroup .
Uma diretiva Setting
Uma lista de duas ou mais diretivas Value ou uma diretiva ValueRange .
Um conjunto de seis diretivas Default .
Uma seção add-power-setting-usa uma das duas formas possíveis a seguir:
Se os valores de configurações de energia permitidos puderem ser melhor definidos como um conjunto de dois ou mais valores discretos, use uma lista de diretivas Value para especificar os valores permitidos, da seguinte maneira:
[add-power-setting-section] [SubGroup = {subgroup-guid}] | SubGroup = {subgroup-guid}, subgroup-name, subgroup-description, subgroup-icon Setting = {setting-guid}, [setting-name],[setting-description],[setting-icon] Value = value-index, value-name,[value-description], value-flags, value-data Value = value-index, value-name,[value-description], value-flags, value-data [Value = value-index, value-name,[value-description], value-flags, value-data ... Value = value-index, value-name,[value-description], value-flags, value-data] (Six required Default directives, each one of which has the following form) Default = power-scheme-personality-GUID, AC/DC-index, default-setting-index | default-setting-value ...Se os valores de configurações de energia permitidos puderem ser melhor definidos como uma sequência incrementada de valores inteiros não negativos dentro de um intervalo especificado, use uma diretiva ValueRange para especificar valores permitidos, da seguinte maneira:
[add-power-setting-section] [SubGroup = {subgroup-guid}] | SubGroup = {subgroup-guid}, subgroup-name, subgroup-description, subgroup-icon Setting = {setting-guid}, [setting-name],[setting-description],[setting-icon] ValueRange = range-minimum-value, range-maximum-value, range-increment, [range-unit-label] (Six required Default directives, each one of which has the following form) Default = power-scheme-personality-GUID, AC/DC-index, default-setting-index | default-setting-value ...
Entradas
Observação
Exceto para uma entrada value-data , todas as entradas a seguir que fornecem um valor de cadeia de caracteres podem especificar a cadeia de caracteres de uma das maneiras descritas em Especificando um valor de entrada de cadeia de caracteres AddPowerSetting.
Subgrupo
Um subgrupo agrupa configurações de energia que estão logicamente relacionadas.
Para especificar um subgrupo definido pelo sistema, inclua uma diretiva SubGroup e forneça apenas a entrada de guid de subgrupo . Os subgrupos definidos pelo sistema são representados pelas constantes GUID_Xxx_SUBGROUP e NO_SUBGROUP_GUID, que são definidas em Wdm.h.
Por exemplo, GUID_VIDEO_SUBGROUP representa o subgrupo que contém as configurações de energia de vídeo para uma personalidade de esquema de energia. A constante NO_SUBGROUP_GUID representa uma coleção de configurações que não pertencem logicamente a nenhum subgrupo. Se uma diretiva SubGroup não estiver incluída, a configuração será adicionada por padrão à coleção de configurações que não pertencem logicamente a nenhum subgrupo.
Para definir um novo subgrupo, inclua a diretiva SubGroup e forneça as seguintes entradas necessárias: subgroup-guid, subgroup-name, subgroup-description e subgroup-icon. O GUID do novo subgrupo deve ser exclusivo e as outras entradas devem ser o mais descritivas possível.
subgroup-guid
A entrada necessária fornece o GUID que identifica o subgrupo. O formato dessa entrada é {XXXXXXXX-XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}, em que "X" é um dígito hexadecimal.
Por exemplo, o valor da constante definida pelo sistema GUID_VIDEO_SUBGROUP é {7516B95F-F776-4464-8C53-06167F40CC99}. Esse GUID representa o subgrupo que contém as configurações de energia de vídeo para uma personalidade de esquema de energia.
subgroup-name
Uma cadeia de caracteres que especifica o nome do subgrupo da configuração de energia. Se o subgrupo for um subgrupo definido pelo sistema, essa entrada não deverá ser fornecida. Se o subgrupo for novo, essa entrada será necessária.
subgroup-description
Uma cadeia de caracteres que descreve ao usuário o subgrupo de energia. Se o subgrupo for um subgrupo definido pelo sistema, essa entrada não deverá ser fornecida. Se o subgrupo for novo, essa entrada será necessária.
subgroup-icon
Uma referência a um recurso de ícone. Se o subgrupo for um subgrupo definido pelo sistema, essa entrada não deverá ser fornecida. Se o subgrupo for novo, essa entrada será necessária.
Um recurso de ícone deve ser especificado como um valor de registro neutro em idioma. Para obter informações sobre como especificar um valor de registro neutro em idioma, consulte Especificando um valor de entrada de cadeia de caracteres AddPowerSetting.
Configuração
A diretiva Setting identifica a configuração à qual todas as outras entradas na seção se aplicam. Uma diretiva Setting é necessária em uma seção add-power-setting e só pode haver uma diretiva Setting em uma seção add-power-setting. Se um arquivo INF definir mais de uma configuração, cada configuração deverá ser definida em sua própria seção add-power-setting.
Veja a seguir as entradas associadas a uma diretiva Setting .
setting-guid
Uma entrada necessária que especifica o GUID que representa a configuração de energia. O formato dessa entrada é {XXXXXXXX-XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}, em que cada "X" é um dígito hexadecimal.
Por exemplo, o seguinte é um valor guid personalizado: {BFC0D9E9-549C-483D-AD2A-3D90C98A8B03}.
setting-name
Uma entrada opcional que especifica uma cadeia de caracteres que contém o nome amigável da configuração de energia.
O Power Options no Painel de Controle exibe esse nome amigável para um usuário.
setting-description
Uma entrada opcional que especifica uma cadeia de caracteres que descreve ao usuário a configuração de energia e o efeito que a configuração tem sobre a potência e o desempenho do sistema.
ícone de configuração
Uma entrada opcional que é uma referência a um recurso de ícone. Um recurso de ícone deve ser especificado por um valor de registro neutro em idioma.
Para obter informações sobre como especificar um valor de registro neutro de linguagem, consulte Especificando um valor de entrada de cadeia de caracteres AddPowerSetting.
Valor
Uma diretiva Value define um valor permitido para uma configuração de energia. A diretiva Value deverá ser usada se os valores puderem ser melhor definidos como um conjunto de dois ou mais valores, em que cada valor poderá ter um tipo de dados personalizado específico do valor. Nessa situação, uma seção add-power-setting deve incluir duas ou mais diretivas Value . Um usuário pode selecionar um desses valores no Power Options em Painel de Controle para configurar um esquema de energia.
Se os valores de configuração de energia permitidos puderem ser melhor descritos como um conjunto incrementado de inteiros não negativos dentro de um intervalo, use a diretiva ValueRange em vez da diretiva Value para especificar os valores de configuração de energia permitidos.
value-index
Uma entrada necessária que especifica um valor de índice exclusivo, que é maior ou igual a zero, e que é usado para referenciar o valor de configuração correspondente.
O Power Options no Painel de Controle exibe valores de configuração de energia para um usuário na ordem de seus valores de índice correspondentes, do mais baixo para o mais alto.
value-name
Uma entrada necessária que fornece uma cadeia de caracteres que fornece o nome amigável para o valor de configuração correspondente.
O Power Options no Painel de Controle exibe os nomes amigáveis dos valores de configuração de energia para um usuário.
value-description
Uma entrada opcional que fornece uma cadeia de caracteres que descreve ao usuário o valor da configuração de energia e o efeito que o valor de configuração tem sobre a potência e o desempenho do sistema.
sinalizadores de valor
Uma entrada necessária que especifica o tipo de dados da entrada value-data correspondente, conforme indicado na tabela a seguir.
| Valor de sinalizador | Tipo de dados |
|---|---|
| 0x00000001 | REG_BINARY |
| 0x00010001 | REG_DWORD |
| 0x00000000 | REG_SZ |
value-data
Uma entrada necessária que fornece os dados para o valor de configuração correspondente, cujo formato depende do tipo de dados especificado pela entrada de sinalizadores de valor correspondente, da seguinte maneira:
Um valor REG_BINARY pode ser especificado no formato hexadecimal usando notação 0x ou como uma lista separada por vírgulas de números hexadecimais emparelhados sem a notação 0x.
Por exemplo, as seguintes entradas são equivalentes: 0xFEDCBA9876543210 e a seguinte lista separada por vírgulas de dígitos hexadecimal emparelhados: FE, DC, BA, 98, 76, 54, 32, 10.
Um valor REG_DWORD pode ser especificado no formato hexadecimal (usando notação 0x) ou em formato decimal.
Um valor REG_SZ só pode ser expresso como uma cadeia de caracteres entre aspas duplas ("quoted-string") ou como um token %strkey% definido na seção Cadeias de caracteres INF de um arquivo INF.
Observação
Você não deve usar valores de cadeia de caracteres porque eles não podem ser localizados. Em vez disso, use valores do tipo REG_BINARY ou REG_DWORD.
ValueRange
Use a diretiva ValueRange se os valores de configurações de energia permitidos puderem ser melhor definidos como uma sequência incrementada de valores inteiros não negativos dentro de um intervalo especificado. O power manager valida que uma configuração selecionada por um usuário no Power Options no Painel de Controle é um desses valores permitidos. O conjunto de valores permitidos é determinado por um valor mínimo permitido, um valor máximo permitido e um incremento entre os valores permitidos dentro do intervalo. Um valor será permitido se atender ao seguinte:
range-minimum-value + k*range-increment
em que range-minimum-value é maior ou igual a zero, k e range-increment são maiores ou iguais a um, e o valor é menor ou igual a range-maximum-value. Além disso, range-maximum-value deve ser igual a range-minimum-value + k*range-increment para alguns k.
Por exemplo, para um valor mínimo de intervalo igual a 0, um valor máximo de intervalo igual a 10 e um incremento de intervalo igual a 2, os valores permitidos são os seguintes: 0, 2, 4, 6, 8 e 10.
Se os valores de configuração de energia permitidos puderem ser melhor descritos como uma lista de valores, em que cada valor pode ter um tipo de dados personalizado específico de valor, use a diretiva Value em vez da diretiva ValueRange .
range-minimum-value
Um valor do tipo REG_DWORD que especifica a configuração de energia mínima permitida.
range-maximum-value
Um valor do tipo REG_DWORD que especifica o valor máximo permitido de configuração de energia. O valor máximo deve ser maior ou igual ao valor mínimo e deve ser igual a range-minimum-value + k*range-increment, para algum número inteiro k maior que zero.
incremento de intervalo
Um valor do tipo REG_DWORD maior que zero. Esse valor especifica a diferença entre valores consecutivos dentro do intervalo inclusivo especificado por range-minimum-value e range-maximum-value.
range-unit-label
Uma cadeia de caracteres opcional que descreve o valor da configuração de energia. A cadeia de caracteres, juntamente com setting-name, informa ao usuário que tipo de dados inserir.
Por exemplo, a cadeia de caracteres pode ser usada para especificar as unidades de valor, como "minutos" ou "%" (representando porcentagem).
Default
Há seis diretivas Default que devem ser incluídas em uma seção AddPowerSetting . Uma diretiva Default especifica o valor padrão para uma das três personalidades do esquema de energia definidas pelo sistema que se aplicam a um estado de energia AC e as três personalidades de esquema de energia definidas pelo sistema que se aplicam a um estado de energia dc.
É extremamente importante que os padrões sejam válidos e precisos. Se o usuário não definir manualmente uma configuração de energia, o power manager usará o valor padrão especificado pela diretiva Default .
power-scheme-personality-GUID
Um dos GUIDs a seguir, que identifica o esquema de energia ao qual o valor padrão se aplica.
| Personalidade | GUID |
|---|---|
| Economia de energia | {A1841308-3541-4FAB-BC81-F71556F20B4A} |
| Alto desempenho | {8C5E7FDA-E8BF-4A96-9A85-A6E23A8C635C} |
| Balanced | {381B4222-F694-41F0-9685-FF5BB260DF2E} |
Esses GUIDs são definidos em Wdm.h.
AC/DC-index
Se AC/DC-index for 0, a configuração se aplicará a um estado de energia AC e, se AC/DC-index for 1, a configuração se aplicará a um estado de energia dc. Um valor diferente de 0 ou 1 não é válido.
default-setting-index
Se a diretiva Value for usada para especificar valores permitidos, default-setting-index será o valor da entrada value-index da diretiva Value . Se a diretiva ValueRange for usada para especificar valores permitidos, essa entrada não se aplicará.
default-setting-value
Se a diretiva ValueRange for usada para especificar valores permitidos, default-setting-value será um dos valores permitidos especificados pela diretiva ValueRange . Se a diretiva Value for usada para especificar valores permitidos, essa entrada não se aplicará.
Comentários
Um nome add-power-setting-section deve ser exclusivo em um arquivo INF, mas pode ser referenciado por mais de uma diretiva AddPowerSetting no mesmo arquivo INF. Cada nome de seção deve seguir as regras gerais descritas em Regras gerais de sintaxe para arquivos INF.
O power manager não remove automaticamente as políticas de energia do dispositivo depois que um dispositivo é desinstalado. A instalação ou remoção de configurações de energia, valores e padrões pode ser executada por um co-instalador por meio das rotinas de configuração de energia fornecidas pelo sistema definidas em Powrprof.h. Para obter mais informações sobre essas rotinas de gerenciamento de energia, consulte a referência de gerenciamento de energia fornecida com a documentação do SDK do Microsoft Windows.
Além disso, a ferramenta de linha de comando Powercfg.exe pode ser usada para alterar as configurações de energia. Para obter informações sobre Powercfg.exe, consulte o Centro de Ajuda e Suporte da Microsoft.
Para obter mais informações sobre como usar as extensões .nt, .ntx86, .ntia64, .ntamd64, .ntarm e .ntarm64 definidas pelo sistema, consulte Criando arquivos INF para várias plataformas e sistemas operacionais.
Especificando um valor de entrada de cadeia de caracteres AddPowerSetting
Exceto para entradas de dados de valor do tipo REG_SZ, todos os outros valores de entrada de cadeia de caracteres fornecidos com uma diretiva AddPowerSetting podem ser expressos como uma cadeia de caracteres entre aspas duplas ("quoted-string"), como um token %strkey% definido na seção de cadeia de caracteres INF de um arquivo INF ou como valor de registro neutro em linguagem.
Os valores de registro neutros em idioma são usados para dar suporte à MUI (Interface do Usuário Multilíngue) do Windows e são especificados da seguinte maneira:
"@file-path,-resourceID[;comment]"
As entradas que especificam um valor de registro neutro em idioma são as seguintes:
caminho do arquivo
O caminho totalmente qualificado do arquivo que contém o recurso.
Resourceid
A ID do recurso correspondente. No caso de uma cadeia de caracteres, a resourceID faz referência a uma cadeia de caracteres. No caso de um ícone, a resourceID faz referência a um ícone.
Comentário
Um valor opcional que pode ser usado para auxiliar na depuração ou para fornecer um comentário adicional sobre a configuração. No caso de um recurso de cadeia de caracteres, o power manager não combina nem exibe a cadeia de caracteres de comentário com a cadeia de caracteres de recurso especificada.
Para obter mais informações sobre como especificar valores de registro neutros em idioma, consulte Renderizando cadeias de caracteres de registro e shell.
Exemplos
Os dois exemplos a seguir definem configurações de energia que controlam o brilho de um LCD. O primeiro exemplo mostra como usar a diretiva Value para definir um valor mínimo, médio e máximo de brilho LCD.
// Within a DDinstall or ClassInstall23 section
AddPowerSetting=LCDDim
...
[LCDDim]
SubGroup = {7516B95F-F776-4464-8C53-06167F40CC99}
Setting = {381B4222-F694-41F0-9685-FF5BB260DF2E}, "LCD Brightness", "Controls the brightness of the LCD display"
Value = 0, "Low", "Minimum Brightness", %FLG_ADDREG_TYPE_DWORD%, 0x50
Value = 1, "Medium", "Medium Brightness", %FLG_ADDREG_TYPE_DWORD%, 0x75
Value = 2, "High", "Maximum Brightness", %FLG_ADDREG_TYPE_DWORD%, 0x100
Default = %GUID_MAX_POWER_SAVINGS%, %AC%, 0
Default = %GUID_MAX_POWER_SAVINGS%, %DC%, 0
Default = %GUID_TYPICAL_POWER_SAVINGS%, %AC%, 2
Default = %GUID_TYPICAL_POWER_SAVINGS%, %DC%, 1
Default = %GUID_MIN_POWER_SAVINGS%, %AC%, 2
Default = %GUID_MIN_POWER_SAVINGS%, %DC%, 2
...
[Strings]
GUID_MAX_POWER_SAVINGS = {a1841308-3541-4fab-bc81-f71556f20b4a}
GUID_TYPICAL_POWER_SAVINGS = {381b4222-f694-41f0-9685-ff5bb260df2e}
GUID_MIN_POWER_SAVINGS = {8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c}
AC = 0
DC = 1
FLG_ADDREG_TYPE_DWORD = 0x00010001
O segundo exemplo mostra como usar a diretiva ValueRange para definir um intervalo de valores de brilho LCD permitidos que variam de 0% a 100%, com um incremento de 1% entre os valores permitidos.
// Within a DDinstall or a ClassInstall23 section
AddPowerSetting=LCDDimRange
...
[LCDDimRange]
SubGroup = {7516B95F-F776-4464-8C53-06167F40CC99}
Setting = {381B4222-F694-41F0-9685-FF5BB260DF2E}, "LCD Brightness", "Controls the brightness of the LCD display"
ValueRange = 0, 100, 1, "%"
Default = %GUID_MAX_POWER_SAVINGS%, %AC%, 50
Default = %GUID_MAX_POWER_SAVINGS%, %DC%, 50
Default = %GUID_TYPICAL_POWER_SAVINGS%, %AC%, 95
Default = %GUID_TYPICAL_POWER_SAVINGS%, %DC%, 50
Default = %GUID_MIN_POWER_SAVINGS%, %AC%, 100
Default = %GUID_MIN_POWER_SAVINGS%, %DC%, 100
[Strings]
GUID_MAX_POWER_SAVINGS = {a1841308-3541-4fab-bc81-f71556f20b4a}
GUID_TYPICAL_POWER_SAVINGS = {381b4222-f694-41f0-9685-ff5bb260df2e}
GUID_MIN_POWER_SAVINGS = {8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c}
AC = 0
DC = 1