Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Driver

Aplikasi Dukungan Perangkat Keras (HSA) adalah aplikasi khusus perangkat yang dipasangkan dengan titik akhir driver atau RPC (Panggilan Prosedur Jarak Jauh) tertentu.

Untuk mengaitkan aplikasi Store dengan driver, lakukan dengan terlebih dahulu memesan nilai khusus yang disebut kemampuan khusus. Kemudian izinkan akses ke aplikasi yang mengiklankan kemampuan dan memberikan kemampuan kepada pengembang aplikasi. Halaman ini menjelaskan langkah-langkah ini untuk pengembang driver.

Langkah-langkah untuk pengembang aplikasi dijelaskan dalam Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Aplikasi.

HSA adalah salah satu dari tiga prinsip desain "DCH".

Mempertahankan kemampuan kustom

Pertama, cadangkan kemampuan kustom:

Kirim email ke Tinjauan Aplikasi Dukungan Perangkat Keras Microsoft (HSAReview@microsoft.com) dengan informasi berikut:
- Informasi kontak
- Nama perusahaan
- Nama kemampuan (harus unik dan mereferensikan pemilik)
- Sumber daya apa yang perlu diakses oleh kemampuan?
- Masalah keamanan atau privasi apa pun
- Peristiwa data apa yang diproses ke mitra?
  - Apakah peristiwa tersebut mencakup pengidentifikasi pribadi seperti lokasi pengguna, kata sandi, alamat IP, PUID, ID perangkat, CID, nama pengguna, dan data kontak yang tepat?
  - Apakah peristiwa data tetap berada di perangkat pengguna, atau dikirim ke mitra?
- Data apa yang dapat diakses oleh kemampuan Anda?
- Apa manfaatnya bagi pengguna akhir dari kemampuan ini?
- Sertakan ID Penerbit Aplikasi Microsoft Store. Untuk mendapatkannya, buat entri aplikasi kerangka dasar pada halaman Microsoft Store. Untuk informasi selengkapnya tentang cara menservasi PFN Aplikasi Anda, lihat Membuat aplikasi Anda dengan membuat nama.
Jika permintaan disetujui, Microsoft mengirim kembali nama string kemampuan kustom yang unik dalam format CompanyName.capabilityName_PublisherID.

Sekarang Anda dapat menggunakan kemampuan kustom untuk memungkinkan akses ke titik akhir RPC atau driver.

Mengizinkan akses ke titik akhir RPC ke aplikasi UWP menggunakan kemampuan kustom

Untuk mengizinkan akses ke titik akhir RPC ke aplikasi UWP yang memiliki kemampuan kustom, ikuti langkah-langkah berikut:

Panggil DeriveCapabilitySidsFromName untuk mengonversi nama kemampuan kustom menjadi ID keamanan (SID).
Tambahkan SID ke akses Anda yang diizinkan ACE bersama dengan SID lain yang diperlukan untuk pendeskripsi keamanan titik akhir RPC Anda.
Buat titik akhir RPC menggunakan informasi dari Deskriptor Keamanan.

Anda dapat melihat implementasi proses ini dalam kode server RPC dalam sampel Kemampuan Kustom.

Mengizinkan aplikasi UWP mengakses driver menggunakan kemampuan kustom

Untuk mengizinkan akses ke driver ke aplikasi UWP dengan kemampuan kustom, tambahkan beberapa baris ke file INF atau sumber driver.

Dalam file INF, tentukan kemampuan kustom Anda sebagai berikut:

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

Atau terapkan kode ini di 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));

Ganti zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz dengan GUID agar antarmuka dapat diekspos. Ganti CompanyName dengan nama perusahaan Anda, myCustomCapabilityName dengan nama yang unik dalam perusahaan Anda, dan MyStorePubId dengan ID toko penerbit Anda.

Untuk contoh kode driver yang telah diterapkan ini, lihat alat bantu penginstalan paket driver untuk driver universal.

Untuk mengatur properti dalam mode kernel, gunakan kode ini:

#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

Menyiapkan file Deskriptor Kemampuan Kustom (SCCD) yang Ditandatangani

File Deskriptor Kemampuan Kustom (SCCD) yang Ditandatangani adalah file XML yang ditandatangani yang mengotorisasi penggunaan satu atau beberapa kemampuan kustom. Pemilik driver atau titik akhir RPC memberikan kemampuan kustom kepada pengembang aplikasi dengan menyediakan file ini.

Untuk menyiapkan file SCCD, pertama-tama perbarui string kemampuan kustom. Gunakan contoh berikut sebagai titik awal:

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

Selanjutnya, pemilik kemampuan kustom memperoleh Nama Keluarga Paket (PFN) dan hash tanda tangan dari pengembang aplikasi dan memperbarui string-string tersebut dalam file SCCD.

Note

Aplikasi tidak harus ditandatangani langsung dengan sertifikat, tetapi sertifikat yang ditentukan harus menjadi bagian dari rantai sertifikasi yang menandatangani aplikasi.

Setelah menyelesaikan SCCD, pemilik kemampuan mengirimkannya melalui email ke Microsoft untuk ditandatangani. Microsoft mengembalikan SCCD yang ditandatangani kepada pemilik kemampuan.

Pemilik kemampuan kemudian mengirim SCCD ke pengembang aplikasi. Pengembang aplikasi menyertakan SCCD yang ditandatangani dalam manifes aplikasi. Untuk mempelajari apa yang perlu dilakukan pengembang aplikasi, lihat Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Aplikasi.

Membatasi cakupan SCCD

Untuk tujuan pengujian, pemilik kemampuan kustom dapat membatasi penginstalan aplikasi dukungan perangkat keras ke komputer dalam mode pengembang.

Untuk melakukannya, sebelum SCCD ditandatangani oleh Microsoft, tambahkan 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>

SCCD yang ditandatangani yang dihasilkan hanya berfungsi pada perangkat dalam Mode Pengembang.

Mengizinkan aplikasi apa pun menggunakan kemampuan kustom

Sebaiknya tentukan entitas resmi (aplikasi) yang dapat menggunakan kemampuan kustom. Namun, dalam beberapa kasus, Anda mungkin ingin mengizinkan aplikasi apa pun untuk menyertakan SCCD. Mulai Windows 10 versi 1809, Anda dapat melakukan ini dengan menambahkan AllowAny ke elemen Entitas Resmi. Karena praktik terbaiknya adalah mendeklarasikan entitas yang berwenang dalam file SCCD, berikan pertimbangan untuk menggunakan AllowAny saat mengirimkan SCCD Anda untuk ditandatangani oleh 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>

SCCD yang telah ditandatangani yang dihasilkan dapat divalidasi dalam paket aplikasi mana pun.

Beberapa SCCD

Mulai windows 10 versi 1803, aplikasi dapat mendeklarasikan kemampuan kustom dari satu atau beberapa file SCCD. Tempatkan file SCCD di akar paket aplikasi.

Skema XML SCCD

Berikut ini adalah skema XML XSD formal untuk file SCCD. Gunakan skema ini untuk memvalidasi SCCD Anda sebelum mengirimkannya untuk ditinjau. Lihat Cache Skema dan Validasi Dokumen XML untuk informasi tentang mengimpor skema dan memvalidasi dengan 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>

Skema berikut juga valid pada Windows 10, versi 1809. Ini memungkinkan SCCD untuk mendeklarasikan paket aplikasi apa pun menjadi entitas resmi.

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-25