Aplikacja wsparcia sprzętu (HSA): etapy dla programistów sterowników

Important

Metadane urządzenia są przestarzałe i zostaną usunięte w przyszłej wersji systemu Windows. Aby uzyskać informacje o zastąpieniu tej funkcji, zobacz Driver Package Container Metadata (Metadane kontenera pakietów sterowników).

Aplikacja do obsługi sprzętu (HSA) to aplikacja specyficzna dla urządzenia, która jest sparowana z określonym sterownikiem lub punktem końcowym wywołania procedury zdalnej (RPC).

Aby skojarzyć aplikację ze sklepu ze sterownikiem, najpierw zarezerwuj specjalną wartość nazywaną możliwością niestandardową. Następnie zezwól na dostęp do aplikacji, które reklamują tę funkcję i udostępniają ją twórcy aplikacji. Na tej stronie są opisane kroki dla programisty sterowników.

Kroki dla dewelopera aplikacji opisano w temacie Hardware Support App (HSA): Steps for App Developers (Kroki dla deweloperów aplikacji).

HSA jest jedną z trzech zasad projektowania "DCH".

Rezerwowanie niestandardowej funkcji

Najpierw zarezerwuj niestandardową funkcjonalność:

Wyślij wiadomość e-mail do zespołu przeglądu aplikacji wsparcia sprzętowego firmy Microsoft (HSAReview@microsoft.com) z następującymi informacjami:
- Contact information
- Company name
- Nazwa możliwości (musi być unikatowa i odwoływać się do właściciela)
- Jakie zasoby musi mieć dostęp do możliwości?
- Wszelkie obawy dotyczące bezpieczeństwa lub prywatności
- Jakie zdarzenia danych są przetwarzane dla partnera?
  - Czy zdarzenia obejmują identyfikatory osobiste, takie jak dokładne lokalizacje użytkownika, hasła, adres IP, identyfikator PUID, identyfikator urządzenia, CID, nazwa użytkownika i dane kontaktowe?
  - Czy zdarzenia danych pozostają na urządzeniu użytkownika lub czy są wysyłane do partnera?
- Jakie dane zapewnia Twoja zdolność?
- Jaka jest korzyść dla użytkownika końcowego tej możliwości?
- Podaj identyfikator wydawcy aplikacji ze sklepu Microsoft Store. Aby go uzyskać, utwórz wpis szkieletowy aplikacji na stronie Sklepu Microsoft. Aby uzyskać więcej informacji na temat rezerwowania nazwy PFN aplikacji, zobacz Create your app by reserving a name (Tworzenie aplikacji przez rezerwowanie nazwy).
If the request is approved, Microsoft emails back a unique custom capability string name in the format CompanyName.capabilityName_PublisherID.

Teraz możesz użyć funkcji niestandardowej, aby zezwolić na dostęp do punktu końcowego RPC lub sterownika.

Zezwalanie na dostęp do punktu końcowego RPC dla aplikacji UWP za pomocą funkcji niestandardowej

Aby zezwolić na dostęp do punktu końcowego RPC dla aplikacji platformy UWP, która ma niestandardową funkcjonalność, wykonaj następujące kroki:

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security ID (SID).
Dodaj identyfikator SID do ACE z dozwolonym dostępem wraz z innymi identyfikatorami SID, które są wymagane dla deskryptora zabezpieczeń punktu końcowego RPC.
Utwórz punkt końcowy RPC przy użyciu informacji z deskryptora zabezpieczeń.

Implementację tego procesu można zobaczyć w kodzie serwera RPC w przykładzie Custom Capability.

Zezwalanie na dostęp sterownika urządzenia do aplikacji UWP przy użyciu funkcji niestandardowej.

Aby umożliwić sterownikowi dostęp do aplikacji UWP z niestandardową funkcją, dodaj kilka wierszy do pliku INF lub do kodu źródłowego sterownika.

W pliku INF określ swoje możliwości niestandardowe w następujący sposób:

[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"

Lub zaimplementuj ten kod w sterowniku:

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));

Zastąp zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz element identyfikatorem GUID interfejsu, aby uwidocznić. Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store ID.

Aby zapoznać się z przykładem tego zaimplementowanego kodu sterownika, zobacz zestaw narzędzi instalacyjnych pakietu sterowników dla sterowników uniwersalnych.

Aby ustawić właściwość w trybie jądra, użyj następującego kodu:

#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

Przygotowywanie pliku deskryptora możliwości niestandardowych podpisanych (SCCD)

Podpisany plik deskryptora możliwości niestandardowych (SCCD) to podpisany plik XML, który autoryzuje użycie co najmniej jednej funkcji niestandardowej. Właściciel sterownika lub punktu końcowego RPC przyznaje deweloperowi aplikacji możliwość niestandardową, udostępniając ten plik.

Aby przygotować plik SCCD, najpierw zaktualizuj ciąg możliwości niestandardowej. Użyj następującego przykładu jako punktu wyjścia:

<?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>

Następnie właściciel niestandardowej funkcji uzyskuje nazwę rodziny pakietów (PFN) i skrót podpisu od programisty aplikacji i aktualizuje te ciągi w pliku SCCD.

Note

Aplikacja nie musi być podpisana bezpośrednio przy użyciu certyfikatu, ale określony certyfikat musi być częścią łańcucha certyfikatów, który podpisuje aplikację.

Po ukończeniu SCCD właściciel kompetencji przesyła go do firmy Microsoft w celu podpisania. Firma Microsoft zwraca podpisany identyfikator SCCD do właściciela możliwości.

Właściciel możliwości wysyła następnie SCCD do dewelopera aplikacji. Deweloper aplikacji umieszcza podpisane SCCD w manifeście aplikacji. Aby dowiedzieć się, co deweloper aplikacji musi zrobić, zobacz Zasady dla deweloperów aplikacji wspierających sprzęt (HSA): Kroki dla deweloperów aplikacji.

Ograniczanie zakresu SCCD

W celach testowych właściciel możliwości niestandardowych może ograniczyć instalację aplikacji do obsługi sprzętu na komputerach w trybie dewelopera.

To do so, before getting the SCCD signed by Microsoft, add 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>

The resulting signed SCCD works only on devices in Developer Mode.

Zezwalanie dowolnej aplikacji na korzystanie z możliwości niestandardowych

Zalecamy określenie autoryzowanych jednostek (aplikacji), które mogą korzystać z możliwości niestandardowych. W niektórych przypadkach możesz jednak zezwolić dowolnej aplikacji na dołączenie SCCD. Starting in Windows 10 version 1809, you can do this by adding AllowAny to the AuthorizedEntities element. Because the best practice is to declare authorized entities in the SCCD file, please provide a justification for using AllowAny when submitting your SCCD to be signed by 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>

Wynikowy podpisany identyfikator SCCD jest ważny w każdym pakiecie aplikacji.

Multiple SCCDs

Począwszy od systemu Windows 10 w wersji 1803, aplikacje mogą deklarować możliwości niestandardowe z co najmniej jednego pliku SCCD. Umieść pliki SCCD w katalogu głównym pakietu aplikacji.

Schemat XML SCCD

Poniżej znajduje się formalny schemat XSD XML dla pliku SCCD. Użyj tego schematu, aby zweryfikować SCCD przed przesłaniem go do przeglądu. See Schema Cache and XML Document validation for info on importing a schema and validating with 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>

Poniższy schemat jest również prawidłowy w systemie Windows 10 w wersji 1809. Umożliwia ona SCCD zadeklarowanie dowolnego pakietu aplikacji jako autoryzowanej jednostki.

<?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>

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-07-24