Aplicativo de suporte de hardware (HSA): etapas para desenvolvedores de drivers
Um aplicativo de suporte de hardware (HSA) é um aplicativo específico do dispositivo que é emparelhado com um driver específico ou ponto de extremidade RPC (Remote Procedure Call).
Para associar um aplicativo da Loja a um driver, primeiro reserve um valor especial chamado recurso personalizado. Em seguida, permita o acesso a aplicativos que anunciam o recurso e fornecem o recurso ao desenvolvedor do aplicativo. Esta página descreve estas etapas para o desenvolvedor do driver.
As etapas para o desenvolvedor do aplicativo são descritas em Hardware Support App (HSA): Steps for App Developers.
HSA é um dos três princípios de design "DCH".
Reservando um recurso personalizado
Primeiro, reserve um recurso personalizado:
Envie um email para o Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) com as seguintes informações:
Informações de contato
Nome da empresa
Nome do recurso (deve ser exclusivo e fazer referência ao proprietário)
Quais recursos o recurso precisa acessar?
Quaisquer preocupações de segurança ou privacidade
Quais eventos de dados serão processados para o parceiro?
Os eventos incluiriam identificadores pessoais, como localizações precisas de usuários, senhas, endereço IP, PUID, ID do dispositivo, CID, nome de usuário e dados de contato)?
Os eventos de dados permanecem no dispositivo dos usuários ou são enviados ao parceiro?
A quais dados sua capacidade fornece acesso?
Qual é o benefício para o usuário final desse recurso?
Inclua a ID do Microsoft Store App Publisher. Para obter um, crie uma entrada de aplicativo esqueleto na página da Microsoft Store. Para obter mais informações sobre como reservar seu PFN de aplicativo, consulte Criar seu aplicativo reservando um nome.
Se a solicitação for aprovada, a Microsoft enviará por email um nome de cadeia de caracteres de recurso personalizado exclusivo no formato CompanyName.capabilityName_PublisherID.
Agora você pode usar o recurso personalizado para permitir o acesso a um ponto de extremidade RPC ou a um driver.
Permitindo acesso a um ponto de extremidade RPC a um aplicativo UWP usando o recurso personalizado
Para permitir o acesso a um ponto de extremidade RPC para um aplicativo UWP que tem o recurso personalizado, execute estas etapas:
Chame DeriveCapabilitySidsFromName para converter o nome do recurso personalizado em uma ID de segurança (SID).
Adicione o SID à ACE de acesso permitido junto com quaisquer outros SIDs necessários para o descritor de segurança do ponto de extremidade RPC.
Crie um ponto de extremidade RPC usando as informações do Descritor de Segurança.
Você pode ver uma implementação do acima no código do servidor RPC no exemplo de capacidade personalizada.
Permitindo acesso a um driver a um aplicativo UWP usando o recurso personalizado
Para permitir o acesso a um driver a um aplicativo UWP com o recurso personalizado, adicione algumas linhas ao arquivo INF ou à origem do driver.
No arquivo INF, especifique seu recurso personalizado da seguinte maneira:
[WDMPNPB003_Device.NT.Interfaces]
AddInterface= {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz},,AddInterfaceSection
[AddInterfaceSection]
AddProperty= AddInterfaceSection.AddProps
[AddInterfaceSection.AddProps]
; DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities
{026e516e-b814-414b-83cd-856d6fef4822}, 8, 0x2012,, "CompanyName.myCustomCapabilityName_MyStorePubId"
Ou, faça o seguinte no driver:
WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = {};
WCHAR customCapabilities[] = L"CompanyName.myCustomCapabilityName_MyStorePubId\0";
WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT(
&PropertyData,
&m_VendorDefinedSubType,
&DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities);
Status = WdfDeviceAssignInterfaceProperty(
m_FxDevice,
&PropertyData,
DEVPROP_TYPE_STRING_LIST,
ARRAYSIZE(customCapabilities),
reinterpret_cast<PVOID>(customCapabilities));
Substitua zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz pelo GUID para a interface a ser exposta. Substitua CompanyName pelo nome da empresa, myCustomCapabilityName por um nome exclusivo da empresa e MyStorePubId pelo ID da loja do editor.
Para obter um exemplo do código de driver mostrado imediatamente acima, consulte o Kit de ferramentas de instalação do pacote de driver para drivers universais.
Para definir a propriedade no modo kernel, use um código como o seguinte:
#if defined(NTDDI_WIN10_RS2) && (NTDDI_VERSION >= NTDDI_WIN10_RS2)
//
// Adding Custom Capability:
//
// Adds a custom capability to device interface instance that allows a Windows
// Store device app to access this interface using Windows.Devices.Custom namespace.
// This capability can be defined either in INF or here as shown below. In order
// to define it from the INF, uncomment the section "OsrUsb Interface installation"
// from the INF and remove the block of code below.
//
static const wchar_t customCapabilities[] = L"microsoft.hsaTestCustomCapability_q536wpkpf5cy2\0";
status = g_pIoSetDeviceInterfacePropertyData(&symbolicLinkName,
&DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities,
0,
0,
DEVPROP_TYPE_STRING_LIST,
sizeof(customCapabilities),
(PVOID)&customCapabilities);
if (!NT_SUCCESS(status)) {
TraceEvents(TRACE_LEVEL_ERROR, DBG_PNP,
"IoSetDeviceInterfacePropertyData failed to set custom capability property %!STATUS!\n", status);
goto Error;
}
#endif
Preparando o arquivo SCCD (Custom Capability Descriptor) assinado
Um arquivo SCCD (Signed Custom Capability Descriptor) é um arquivo XML assinado que autoriza o uso de um ou mais recursos personalizados. O proprietário do driver ou ponto de extremidade RPC concede o recurso personalizado ao desenvolvedor do aplicativo fornecendo esse arquivo.
Para preparar o arquivo SCCD, primeiro atualize a cadeia de caracteres de capacidade personalizada. Use o exemplo a seguir como ponto de partida:
<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2016/sccd" xmlns:s="http://schemas.microsoft.com/appx/2016/sccd">
<CustomCapabilities>
<CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities>
<AuthorizedEntity AppPackageFamilyName="MicrosoftHSATest.Microsoft.SDKSamples.Hsa.CPP_q536wpkpf5cy2" CertificateSignatureHash="ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4"></AuthorizedEntity>
</AuthorizedEntities>
<Catalog>0000</Catalog>
</CustomCapabilityDescriptor>
Em seguida, o proprietário do recurso personalizado obtém o PFN (Nome da Família do Pacote) e o hash de assinatura do desenvolvedor do aplicativo e atualiza essas cadeias de caracteres no arquivo SCCD.
Observação
O aplicativo não precisa ser assinado diretamente com o certificado, mas o certificado especificado deve fazer parte da cadeia de certificados que assina o aplicativo.
Depois de concluir o SCCD, o proprietário do recurso envia-o por e-mail para a Microsoft para assinatura. A Microsoft retorna o SCCD assinado para o proprietário do recurso.
Em seguida, o proprietário do recurso envia o SCCD para o desenvolvedor do aplicativo. O desenvolvedor do aplicativo inclui o SCCD assinado no manifesto do aplicativo. Para saber o que o desenvolvedor de aplicativos precisa fazer, consulte Hardware Support App (HSA): Steps for App Developers.
Limitando o escopo de um SCCD
Para fins de teste, um proprietário de recurso personalizado pode restringir a instalação de um aplicativo de suporte de hardware a computadores no modo de desenvolvedor.
Para fazer isso, antes de obter o SCCD assinado pela Microsoft, adicione DeveloperModeOnly:
<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2016/sccd" xmlns:s="http://schemas.microsoft.com/appx/2016/sccd">
<CustomCapabilities>
<CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities>
<AuthorizedEntity AppPackageFamilyName="MicrosoftHSATest.Microsoft.SDKSamples.Hsa.CPP_q536wpkpf5cy2" CertificateSignatureHash="ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4"></AuthorizedEntity>
</AuthorizedEntities>
<Catalog>0000</Catalog>
<DeveloperModeOnly Value="true" />
</CustomCapabilityDescriptor>
O SCCD assinado resultante funciona apenas em dispositivos no Modo de Desenvolvedor.
Permitindo que qualquer aplicativo use um recurso personalizado
Recomendamos especificar entidades autorizadas (aplicativos) que podem usar um recurso personalizado. Em alguns casos, no entanto, convém permitir que qualquer aplicativo inclua um SCCD. A partir do Windows 10 versão 1809, você pode fazer isso adicionando AllowAny ao elemento AuthorizedEntities. Como a prática recomendada é declarar entidades autorizadas no arquivo SCCD, forneça uma justificativa para usar AllowAny ao enviar seu SCCD para ser assinado pela Microsoft.
<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2018/sccd" xmlns:s="http://schemas.microsoft.com/appx/2018/sccd">
<CustomCapabilities>
<CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities AllowAny="true"/>
<Catalog>0000</Catalog>
</CustomCapabilityDescriptor>
O SCCD assinado resultante será validado em qualquer pacote de aplicativo.
Múltiplos SCCDs
A partir do Windows 10 versão 1803, os aplicativos podem declarar recursos personalizados de um ou mais arquivos SCCD. Coloque os arquivos SCCD na raiz do pacote do aplicativo.
Resumo da sequência de assinatura do SCCD
O diagrama a seguir resume a sequência descrita acima:
Esquema XML SCCD
A seguir está o esquema XSD XML formal para um arquivo SCCD. Use este esquema para validar seu SCCD antes de enviá-lo para revisão. Consulte Cache de esquema e validação de documento XML para obter informações sobre como importar um esquema e validar com o IntelliSense.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="https://www.w3.org/2001/XMLSchema"
targetNamespace="http://schemas.microsoft.com/appx/2016/sccd"
xmlns:s="http://schemas.microsoft.com/appx/2016/sccd"
xmlns="http://schemas.microsoft.com/appx/2016/sccd">
<xs:element name="CustomCapabilityDescriptor" type="CT_CustomCapabilityDescriptor">
<xs:unique name="Unique_CustomCapability_Name">
<xs:selector xpath="s:CustomCapabilities/s:CustomCapability"/>
<xs:field xpath="@Name"/>
</xs:unique>
</xs:element>
<xs:complexType name="CT_CustomCapabilityDescriptor">
<xs:sequence>
<xs:element ref="CustomCapabilities" minOccurs="1" maxOccurs="1"/>
<xs:element ref="AuthorizedEntities" minOccurs="1" maxOccurs="1"/>
<xs:element ref="DeveloperModeOnly" minOccurs="0" maxOccurs="1"/>
<xs:element ref="Catalog" minOccurs="1" maxOccurs="1"/>
<xs:any minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:element name="CustomCapabilities" type="CT_CustomCapabilities" />
<xs:complexType name="CT_CustomCapabilities">
<xs:sequence>
<xs:element ref="CustomCapability" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="CustomCapability">
<xs:complexType>
<xs:attribute name="Name" type="ST_CustomCapability" use="required"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="ST_NonEmptyString">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ST_CustomCapability">
<xs:annotation>
<xs:documentation>Custom capabilities should be a string in the form of Company.capabilityName_PublisherId</xs:documentation>
</xs:annotation>
<xs:restriction base="ST_NonEmptyString">
<xs:pattern value="[A-Za-z0-9][-_.A-Za-z0-9]*_[a-hjkmnp-z0-9]{13}"/>
<xs:minLength value="15"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="AuthorizedEntities" type="CT_AuthorizedEntities" />
<xs:complexType name="CT_AuthorizedEntities">
<xs:sequence>
<xs:element ref="AuthorizedEntity" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="AuthorizedEntity" type="CT_AuthorizedEntity" />
<xs:complexType name="CT_AuthorizedEntity">
<xs:attribute name="CertificateSignatureHash" type="ST_CertificateSignatureHash" use="required"/>
<xs:attribute name="AppPackageFamilyName" type="ST_NonEmptyString" use="required"/>
</xs:complexType>
<xs:simpleType name="ST_CertificateSignatureHash">
<xs:restriction base="ST_NonEmptyString">
<xs:pattern value="[A-Fa-f0-9]+"/>
<xs:minLength value="64"/>
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="DeveloperModeOnly">
<xs:complexType>
<xs:attribute name="Value" type="xs:boolean" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="Catalog" type="ST_Catalog" />
<xs:simpleType name="ST_Catalog">
<xs:restriction base="xs:string">
<xs:pattern value="[A-Za-z0-9\+\/\=]+"/>
<xs:minLength value="4"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
O esquema a seguir também é válido a partir do Windows 10, versão 1809. Ele permite que um SCCD declare qualquer pacote de aplicativo como uma entidade autorizada.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="https://www.w3.org/2001/XMLSchema"
targetNamespace="http://schemas.microsoft.com/appx/2018/sccd"
xmlns:s="http://schemas.microsoft.com/appx/2018/sccd"
xmlns="http://schemas.microsoft.com/appx/2018/sccd">
<xs:element name="CustomCapabilityDescriptor" type="CT_CustomCapabilityDescriptor">
<xs:unique name="Unique_CustomCapability_Name">
<xs:selector xpath="s:CustomCapabilities/s:CustomCapability"/>
<xs:field xpath="@Name"/>
</xs:unique>
</xs:element>
<xs:complexType name="CT_CustomCapabilityDescriptor">
<xs:sequence>
<xs:element ref="CustomCapabilities" minOccurs="1" maxOccurs="1"/>
<xs:element ref="AuthorizedEntities" minOccurs="1" maxOccurs="1"/>
<xs:element ref="DeveloperModeOnly" minOccurs="0" maxOccurs="1"/>
<xs:element ref="Catalog" minOccurs="1" maxOccurs="1"/>
<xs:any minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:element name="CustomCapabilities" type="CT_CustomCapabilities" />
<xs:complexType name="CT_CustomCapabilities">
<xs:sequence>
<xs:element ref="CustomCapability" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="CustomCapability">
<xs:complexType>
<xs:attribute name="Name" type="ST_CustomCapability" use="required"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="ST_NonEmptyString">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ST_CustomCapability">
<xs:annotation>
<xs:documentation>Custom capabilities should be a string in the form of Company.capabilityName_PublisherId</xs:documentation>
</xs:annotation>
<xs:restriction base="ST_NonEmptyString">
<xs:pattern value="[A-Za-z0-9][-_.A-Za-z0-9]*_[a-hjkmnp-z0-9]{13}"/>
<xs:minLength value="15"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="AuthorizedEntities" type="CT_AuthorizedEntities" />
<xs:complexType name="CT_AuthorizedEntities">
<xs:sequence>
<xs:element ref="AuthorizedEntity" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="AllowAny" type="xs:boolean" use="optional"/>
</xs:complexType>
<xs:element name="AuthorizedEntity" type="CT_AuthorizedEntity" />
<xs:complexType name="CT_AuthorizedEntity">
<xs:attribute name="CertificateSignatureHash" type="ST_CertificateSignatureHash" use="required"/>
<xs:attribute name="AppPackageFamilyName" type="ST_NonEmptyString" use="required"/>
</xs:complexType>
<xs:simpleType name="ST_CertificateSignatureHash">
<xs:restriction base="ST_NonEmptyString">
<xs:pattern value="[A-Fa-f0-9]+"/>
<xs:minLength value="64"/>
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="DeveloperModeOnly">
<xs:complexType>
<xs:attribute name="Value" type="xs:boolean" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="Catalog" type="ST_Catalog" />
<xs:simpleType name="ST_Catalog">
<xs:restriction base="xs:string">
<xs:pattern value="[A-Za-z0-9\+\/\=]+"/>
<xs:minLength value="4"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
Confira também
Introdução aos drivers do Windows
Introdução à Plataforma Universal do Windows
UWP (Plataforma Universal do Windows)
Desenvolver aplicativos UWP usando o Visual Studio
Emparelhando um driver com um aplicativo da Plataforma Universal do Windows (UWP)
Empacotar um aplicativo usando o Desktop App Converter (Desktop Bridge)
Aplicativo de exemplo de recurso personalizado
Exemplo de driver de capacidade personalizada
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de