Application de Support Matériel (HSA) : Étapes pour les Développeurs de Pilotes
Une application de support matériel (HSA) est une application spécifique à l’appareil associée à un pilote spécifique ou à un point de terminaison RPC (Appel de procédure distante).
Pour associer une application Store à un pilote, réservez d’abord une valeur spéciale appelée fonctionnalité personnalisée. Ensuite, autorisez l’accès aux applications qui publient la fonctionnalité et fournissent la fonctionnalité au développeur d’applications. Cette page décrit ces étapes pour le développeur de pilotes.
Les étapes du développeur d’applications sont décrites dans l’application de support matériel (HSA) : étapes pour les développeurs d’applications.
HSA est l’un des trois principes de conception « DCH ».
Réserver une fonctionnalité personnalisée
Tout d’abord, réservez une fonctionnalité personnalisée :
Envoyez un e-mail à la révision des applications de support matériel Microsoft (HSAReview@microsoft.com) avec les informations suivantes :
Informations de contact
Nom de la société
Nom de la fonctionnalité (doit être unique et référencer le propriétaire)
Quelles sont les ressources dont la fonctionnalité a besoin pour accéder ?
Tout problème de sécurité ou de confidentialité
Quels événements de données seront traités pour le partenaire ?
Les événements incluent-ils des identificateurs personnels tels que des emplacements utilisateur précis, des mots de passe, une adresse IP, puID, un ID d’appareil , CID, un nom d’utilisateur et des données de contact précises) ?
Les événements de données restent-ils sur l’appareil des utilisateurs ou sont-ils envoyés au partenaire ?
Quelles données votre fonctionnalité permet-elle d’accéder ?
Quel est l’avantage pour l’utilisateur final de cette fonctionnalité ?
Incluez l’ID d’éditeur d’application du Microsoft Store. Pour en obtenir une, créez une entrée d’application squelette sur la page du Microsoft Store. Pour plus d’informations sur la réservation de votre PFN d’application, consultez Créer votre application en réservant un nom.
Si la demande est approuvée, Microsoft renvoie un nom de chaîne de capacité personnalisée unique au format CompanyName.capabilityName_PublisherID.
Vous pouvez maintenant utiliser la fonctionnalité personnalisée pour autoriser l’accès à un point de terminaison RPC ou à un pilote.
Autoriser l’accès à un point de terminaison RPC à une application UWP à l’aide de la fonctionnalité personnalisée
Pour autoriser l’accès à un point de terminaison RPC à une application UWP qui a la fonctionnalité personnalisée, procédez comme suit :
Appelez DeriveCapabilitySidsFromName pour convertir le nom de la fonctionnalité personnalisée en ID de sécurité (SID).
Ajoutez le SID à votre accès ACE autorisé, ainsi que les autres SID nécessaires pour le descripteur de sécurité de votre point de terminaison RPC.
Créez un point de terminaison RPC à l’aide des informations du descripteur de sécurité.
Vous pouvez voir une implémentation du code serveur RPC ci-dessus dans l’exemple de fonctionnalité personnalisée.
Autoriser l’accès à un pilote à une application UWP à l’aide de la fonctionnalité personnalisée
Pour autoriser l’accès à un pilote à une application UWP avec la fonctionnalité personnalisée, ajoutez quelques lignes au fichier INF ou à la source du pilote.
Dans le fichier INF, spécifiez votre fonctionnalité personnalisée comme suit :
[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 effectuez les opérations suivantes dans le pilote :
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));
Remplacez zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz par le GUID de l’interface à exposer. Remplacez CompanyName par le nom de votre société, myCustomCapabilityName par un nom unique au sein de votre entreprise et MyStorePubId par votre ID de magasin d’éditeurs.
Pour obtenir un exemple de code de pilote affiché immédiatement ci-dessus, consultez le kit de ressources d’installation du package de pilotes pour les pilotes universels.
Pour définir la propriété en mode noyau, utilisez du code comme suit :
#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
Préparation du fichier de descripteur de capacité personnalisée signé (SCCD)
Un fichier de descripteur de capacité personnalisée signé (SCCD) est un fichier XML signé autorisant l’utilisation d’une ou plusieurs fonctionnalités personnalisées. Le propriétaire du pilote ou du point de terminaison RPC accorde la fonctionnalité personnalisée au développeur d’applications en fournissant ce fichier.
Pour préparer le fichier SCCD, commencez par mettre à jour la chaîne de fonctionnalité personnalisée. Utilisez l’exemple suivant comme point de départ :
<?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>
Ensuite, le propriétaire de la fonctionnalité personnalisée obtient le nom de famille de package (PFN) et le hachage de signature du développeur de l’application et met à jour ces chaînes dans le fichier SCCD.
Remarque
L’application ne doit pas être signée directement avec le certificat, mais le certificat spécifié doit faire partie de la chaîne de certificats qui signe l’application.
Une fois le SCCD terminé, le propriétaire de la fonctionnalité l’envoie par e-mail à Microsoft pour la signature. Microsoft retourne le SCCD signé au propriétaire de la fonctionnalité.
Le propriétaire de la fonctionnalité envoie ensuite le SCCD au développeur de l’application. Le développeur de l’application inclut le SCCD signé dans le manifeste de l’application. Pour savoir ce que le développeur d’applications doit faire, consultez l’application de support matériel (HSA) : étapes pour les développeurs d’applications.
Limitation de l’étendue d’un SCCD
À des fins de test, un propriétaire de fonctionnalité personnalisée peut limiter l’installation d’une application de prise en charge matérielle aux ordinateurs en mode développeur.
Pour ce faire, avant d’obtenir le SCCD signé par Microsoft, ajoutez 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>
Le SCCD signé obtenu fonctionne uniquement sur les appareils en mode développeur.
Autoriser n’importe quelle application à utiliser une fonctionnalité personnalisée
Nous vous recommandons de spécifier des entités autorisées (applications) qui peuvent utiliser une fonctionnalité personnalisée. Dans certains cas, toutefois, vous souhaiterez peut-être autoriser n’importe quelle application à inclure un SCCD. À compter de Windows 10 version 1809, vous pouvez le faire en ajoutant AllowAny à l’élément AuthorizedEntities. Étant donné que la meilleure pratique consiste à déclarer des entités autorisées dans le fichier SCCD, veuillez fournir une justification pour utiliser AllowAny lors de l’envoi de votre SCCD à signer par 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>
Le SCCD signé obtenu valide dans n’importe quel package d’application.
Plusieurs SCCD
À compter de Windows 10 version 1803, les applications peuvent déclarer des fonctionnalités personnalisées à partir d’un ou plusieurs fichiers SCCD. Placez les fichiers SCCD à la racine du package d’application.
Résumé de la séquence de signature SCCD
Le diagramme suivant résume la séquence décrite ci-dessus :
Schéma XML SCCD
Voici le schéma XSD XML formel pour un fichier SCCD. Utilisez ce schéma pour valider votre SCCD avant de l’envoyer pour révision. Consultez la validation du cache de schéma et du document XML pour plus d’informations sur l’importation d’un schéma et la validation avec 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>
Le schéma suivant est également valide à partir de Windows 10, version 1809. Il permet à un SCCD de déclarer tout package d’application comme entité autorisée.
<?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>
Voir aussi
Prise en main des pilotes Windows
Introduction à la plateforme Windows universelle
Plateforme Windows universelle (UWP)
Développer des applications UWP à l’aide de Visual Studio
Association d’un pilote à une application plateforme Windows universelle (UWP)
Développer des applications UWP
Empaqueter une application à l’aide de Desktop App Converter (Pont du bureau)
Exemple d’application de fonctionnalité personnalisée
Exemple de pilote de fonctionnalité personnalisée
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour