Приложение поддержки оборудования (HSA): действия для разработчиков драйверов
Приложение поддержки оборудования (HSA) — это приложение для конкретного устройства, которое связано с определенным драйвером или конечной точкой RPC (удаленный вызов процедур ).
Чтобы связать приложение Магазина с драйвером, сначала зарезервируйте специальное значение, называемое пользовательской возможностью. Затем разрешите доступ к приложениям, которые объявляют возможность и предоставляют ее разработчику. На этой странице описаны эти шаги для разработчика драйверов.
Действия для разработчика приложения описаны в разделе Приложение поддержки оборудования (HSA): шаги для разработчиков приложений.
HSA — это один из трех принципов проектирования (DCH) драйверов Windows.
Резервирование пользовательской возможности
Сначала зарезервируйте пользовательскую возможность:
Email Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) со следующими сведениями:
Контактные данные
Название организации
Имя возможности (должно быть уникальным и ссылаться на владельца)
К каким ресурсам требуется доступ для возможностей?
Любые проблемы безопасности или конфиденциальности
Какие события данных будут обрабатываться партнеру?
Будут ли события включать личные идентификаторы, такие как точные расположения пользователей, пароли, IP-адрес, PUID, идентификатор устройства, идентификатор CID, имя пользователя и контактные данные)?
Остаются ли события данных на устройстве пользователей или отправляются партнеру?
К каким данным предоставляет доступ ваша возможность?
В чем преимущество этой возможности для конечного пользователя?
Включите идентификатор издателя приложения Microsoft Store. Чтобы получить ее, создайте запись приложения на странице Microsoft Store. Дополнительные сведения о резервирования PFN приложения см. в статье Создание приложения путем резервирования имени.
Если запрос утвержден, корпорация Майкрософт отправляет по электронной почте уникальное имя строки пользовательской возможности в формате CompanyName.capabilityName_PublisherID.
Теперь можно использовать пользовательскую возможность, чтобы разрешить доступ к конечной точке RPC или драйверу.
Предоставление доступа к конечной точке RPC к приложению UWP с помощью пользовательской возможности
Чтобы разрешить доступ к конечной точке RPC к приложению UWP с настраиваемой возможностью, выполните следующие действия.
Вызовите Метод DeriveCapabilitySidsFromName , чтобы преобразовать имя настраиваемой возможности в идентификатор безопасности (SID).
Добавьте идентификатор безопасности в разрешенный доступ ACE вместе с любыми другими идентификаторами безопасности, необходимыми для дескриптора безопасности конечной точки RPC.
Создайте конечную точку RPC, используя сведения из дескриптора безопасности.
Реализацию выше можно увидеть в коде сервера RPC в примере настраиваемой возможности.
Предоставление доступа к драйверу к приложению UWP с помощью пользовательской возможности
Чтобы разрешить доступ к драйверу к приложению UWP с пользовательской возможностью, добавьте несколько строк в INF-файл или источник драйвера.
В INF-файле укажите пользовательскую возможность следующим образом:
[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"
Или выполните следующие действия в драйвере:
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));
Замените zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz идентификатором GUID для интерфейса, который будет предоставляться. Замените CompanyName именем своей компании, myCustomCapabilityName — уникальным в пределах вашей компании именем, а MyStorePubId — идентификатором вашего магазина издателя.
Пример кода драйвера, показанного непосредственно выше, см. в разделе Набор средств установки пакета драйверов для универсальных драйверов.
Чтобы задать свойство в режиме ядра, используйте следующий код:
#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
Подготовка файла подписанного пользовательского дескриптора возможностей (SCCD)
Подписанный файл пользовательского дескриптора возможностей (SCCD) — это подписанный XML-файл, разрешающий использование одной или нескольких пользовательских возможностей. Владелец драйвера или конечной точки RPC предоставляет разработчику приложения пользовательскую возможность, предоставив этот файл.
Чтобы подготовить SCCD-файл, сначала обновите строку настраиваемой возможности. Используйте следующий пример в качестве отправной точки:
<?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>
Затем владелец настраиваемой возможности получает имя семейства пакетов (PFN) и хэш подписи от разработчика приложения и обновляет эти строки в файле SCCD.
Примечание
Приложение не обязательно подписывается непосредственно сертификатом, но указанный сертификат должен быть частью цепочки сертификатов, подписывающую приложение.
После завершения SCCD владелец возможности отправляет его по электронной почте в корпорацию Майкрософт для подписания. Корпорация Майкрософт возвращает подписанный SCCD владельцу возможности.
Затем владелец возможности отправляет SCCD разработчику приложения. Разработчик приложения включает подписанный SCCD в манифест приложения. Сведения о том, что нужно сделать разработчику приложений, см. в статье Приложение поддержки оборудования (HSA): действия для разработчиков приложений.
Ограничение область SCCD
В целях тестирования владелец пользовательской возможности может ограничить установку приложения поддержки оборудования компьютерами в режиме разработчика.
Для этого перед получением SCCD, подписанного корпорацией Майкрософт, добавьте 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 работает только на устройствах в режиме разработчика.
Разрешение любому приложению использовать пользовательскую возможность
Рекомендуется указать авторизованные сущности (приложения), которые могут использовать пользовательскую возможность. Однако в некоторых случаях может потребоваться разрешить любому приложению включить SCCD. Начиная с Windows 10 версии 1809, это можно сделать, добавив AllowAny в элемент AuthorizedEntities. Так как рекомендуется объявлять авторизованные сущности в файле SCCD, укажите обоснование использования AllowAny при отправке SCCD, подписанного корпорацией Майкрософт.
<?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 будет проверяться в любом пакете приложения.
Несколько SCCD
Начиная с Windows 10 версии 1803, приложения могут объявлять пользовательские возможности из одного или нескольких SCCD-файлов. Поместите SCCD-файлы в корень пакета приложения.
Сводка по последовательности подписывания SCCD
На следующей схеме представлена последовательность, описанная выше.
Схема XML SCCD
Ниже приведена формальная XSD-схема XML для SCCD-файла. Используйте эту схему для проверки SCCD перед отправкой на проверку. Сведения об импорте схемы и проверке с помощью IntelliSense см. в разделе Проверка кэша схем и XML-документов .
<?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>
Следующая схема также допустима с Windows 10, версия 1809. Это позволяет SCCD объявлять любой пакет приложения как авторизованный объект.
<?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>
См. также раздел
начало работы с драйверами Windows
Общие сведения об универсальной платформе Windows
Универсальная платформа Windows (UWP)
Разработка приложений UWP с помощью Visual Studio
Связывание драйвера с приложением универсальная платформа Windows (UWP)
Упаковка приложения с помощью Desktop App Converter (моста для классических приложений)
Пример приложения пользовательской возможности
Пример драйвера настраиваемых возможностей
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по