Communicating with desktop apps (Win32), NT services, or drivers

This section describes how your Game Bar widget can communicate with your existing desktop app, windows service, or driver.

Desktop App

If you need your Game Bar widget to communicate with your existing desktop app there are some important issues to consider:

1. How will your desktop app be acquired and installed?
2. How will your desktop app get launched?
3. What communication type will you use?
4. Microsoft Store policy compliance.

All the above issues are simplified if you package your desktop app and include your Game Bar widget in the same package.

Package desktop applications. If your desktop app is packaged, you can choose to deliver it to clients through the Microsoft Store or another method. Further, your Game Bar widget can more easily launch your desktop app, and without the need for any store policy exceptions.

If you choose not to package your desktop app, you can still communicate with it from your Game Bar widget, but there will be the following limitations:

1. You will need a Microsoft Store policy exception to link from your Game Bar widget to a download website for your desktop app.
2. You will need a Microsoft Store policy exception to directly communicate with our desktop app.
3. You will only be able to Protocol launch your desktop app unless you build a packaged full trust process (packaged desktop app) that does the launch of your real desktop app.

Inter-process communication options

Below are the inter-process communication (IPC) options available.

Named pipes

Your desktop app process can create a named pipe and allow access to your UWP app (Game Bar Widget). To allow access grant access to SECURITY_WORLD_SID_AUTHORITY as well as your desired SID (package SID or app capability SID). You can follow the Custom Capability RPC sample for how to construct a security identifier. Note that if you’re using package SID, you don’t need any of the logic used in the sample that converts the Custom Capability to its SID form. You’ll just use the package SID directly.

Remote Procedure Calls (RPC)

Your desktop app process can create an RPC server that your UWP app (Game Bar Widget) can communicate with. To allow access, grant access to SECURITY_WORLD_SID_AUTHORITY as well as your desired SID (package SID or app capability SID). You can follow the Custom Capability RPC sample which demonstrates this. Note that if you’re using package SID, you don’t need any of the logic used in the sample that converts the Custom Capability to its SID form. You’ll just use the package SID directly.

For COM, your desktop app needs to be the server and your UWP Game Bar widget needs to be the client. How your desktop app registers the COM objects depends on whether your desktop app is part of the package or not.

Un-packaged desktop app

If you choose not to package your desktop app, you will need to register your COM objects in the Windows registry when your app is installed.

Packaged desktop app

For a packaged app you will register your COM objects via the appx manifest.

Regardless of your desktop app being packaged or not, while your desktop app process is running, you will register the COM objects as being hosted by your server.

App Services

This option is only available if you package your desktop app.

This API allows communication using a message pattern via a WinRT API. The API supports sending primitive types and binary blobs.

NT Service or Driver

To access an NT Service or Driver, you would follow the method for Hardware Support Apps (UWP apps that access NT Services and/or Drivers). The method for an NT Service is the same as the RPC method described above. For drivers, you will still use device IO control. This topic is discussed on MSDN and channel 9 in more detail.

Communication Channel Security

With many of the methods above, you will need to control access to the endpoint you create on your full trust side (desktop app, NT service, or driver). We recommend one of two ways of allowing access to your Game Bar widget:

1. Package Identity
2. App Capability. Typically, Custom Capability you own

App Capabilities and App Packages both have Security Identifier (SID) representation. Most communication endpoints can have security descriptors which grant access to apps based on these SIDs. In both cases, you need to open access to «Everyone» ( SECURITY_WORLD_SID_AUTHORITY ) in addition to the App Capability or App Package SID.

The simplest way to allow communication between your desktop app and UWP app (Game Bar Extension) will be to set the security identifier to allow the SID of your Package. However if you want your desktop app’s communication endpoint to be protected against side-loaded apps, or more flexible in cases where you may want to change your app’s identity (thus changing the Package SID), you can use a Custom Capability. There is more overhead to creating and managing a Custom Capability, so it is a tradeoff.

Package SID

The Package SID of your app is used to grant your app access to a communication endpoint. You can acquire your app’s Package SID in one of two ways:

1. If you’ve already associated your local app project with its corresponding app entry on partner.microsoft.com, visit partner.microsoft.com, go to your app’s page, then Product management ->Product Identity. You’ll see the SID below the Package Family Name (PFN).
2. After your app is installed, navigate to HKLM\Software\Microsoft\SecurityManager\CapAuthz\ApplicationEx\ . Under this key you’ll see a value called PackageSid .

Custom Capability

To leverage a Custom Capability, you’ll follow the steps that you would for an HSA app. Hardware Support App

Overview of developing Windows applications for USB devices

Summary

• Guidelines for choosing the right programming model
• UWP app and desktop app developer experience

Important APIs

This topic provides guidelines for deciding whether you should write a UWP app or a Windows desktop app to communicate with a USB device.

Windows provides API sets that you can use to write apps that talk to a custom USB devices. The API performs common USB-related tasks such as, finding the device, data transfers.

«Custom device» in this context means, a device for which Microsoft does not provide an in-box class driver. Instead, you can install WinUSB (Winusb.sys) as the device driver.

Choosing a programming model

If you install Winusb.sys, here are the programming model options:

Windows 8.1 provides a new namespace: Windows.Devices.Usb. The namespace cannot be used in earlier version of Windows. Other Microsoft Store resources are here: UWP app.

Before Windows 8.1, apps that were communicating through Winusb.sys, were desktop apps written by using WinUSB Functions. In Windows 8.1, the API set has been extended. Other Windows desktop app resources are here: Windows desktop app.

The strategy for choosing the best programming model depends on various factors.

Will your app communicate with an internal USB device?

The APIs are primarily designed for accessing peripheral devices. The API can also access PC internal USB devices. However access to PC internal USB devices from a UWP app is limited to a privileged app that is explicitly declared in device metadata by the OEM for that PC.

Will your app communicate with USB isochronous endpoints?

If your app transmits data to or from isochronous endpoints of the device, you must write a Windows desktop app. In Windows 8.1, new WinUSB Functions have been added to the API set that allow a desktop app to send data to and receive data from isochronous endpoints.

Is your app a «control panel» type of app?

UWP apps are per-user apps and do not have the ability to make changes outside the scope of each app. For these types of apps, you must write a Windows desktop app.

Is the USB device class supported classes by UWP apps?

Write a UWP app if your device belongs to one these device classes.

• name:cdcControl, classId:02 * *
• name:physical, classId:05 * *
• name:personalHealthcare, classId:0f 00 00
• name:activeSync, classId:ef 01 01
• name:palmSync, classId:ef 01 02
• name:deviceFirmwareUpdate, classId:fe 01 01
• name:irda, classId:fe 02 00
• name:measurement, classId:fe 03 *
• name:vendorSpecific, classId:ff * *

Note If your device belongs to DeviceFirmwareUpdate class, your app must be a privileged app.

If your device does not belong to one the preceding device classes, write a Windows desktop app.

Driver requirement

Driver requirement	UWP app	Windows desktop app
Function driver	Microsoft-provided Winusb.sys (kernel-mode driver).	Microsoft-provided Winusb.sys (kernel-mode driver).
Filter driver	If filter drivers are present, access is limited to privileged apps. The app is declared as privileged apps in device metadata by the OEM.	Filter driver can be present in the kernel mode device stack as long as it doesn’t block access to Winusb.sys.

Code samples

Sample	UWP app	Windows desktop app
Get started with these samples	Custom USB device access sample USB CDC Control sample Firmware Update USB Device sample	Start with the WinUsb Application template included with Microsoft Visual Studio (Ultimate or Professional) Extend the template by using code examples shown in How to Access a USB Device by Using WinUSB Functions.

Development tools

Microsoft Visual Studio 2013

Microsoft Windows Software Development Kit (SDK) for Windows 8.1

Use WinUSB Application template included with Visual Studio (Ultimate or Professional) and Windows Driver Kit (WDK) 8

Download the Windows Driver Kit (WDK)

The WDK is used to develop, test, and deploy Windows drivers.

Runtime requirements

You can run the Windows 10, version 2004 WDK on Windows 7 and later, and use it to develop drivers for these operating systems:

Development tools	UWP app	Windows desktop app
Developer environment

Client OS	Server OS
Windows 10	Windows Server 2019, Windows Server 2016
Windows 8.1	Windows Server 2012 R2
Windows 8	Windows Server 2012
Windows 7	Windows Server 2008 R2 SP1

WDK for Windows 10, version 2004

Step 1: Install Visual Studio 2019

The WDK requires Visual Studio. For more information about system requirements for Visual Studio, see Visual Studio 2019 System Requirements.

The following editions of Visual Studio 2019 support driver development for this release:

When you install Visual Studio 2019, select the Desktop development with C++ workload. The Windows 10 Software Development Kit (SDK) is automatically included, and is displayed in the right-hand Summary pane. Note that the version of the SDK that is compatible with the WDK for Windows 10, version 2004 may not be the default SDK. To select the correct SDK:

In Visual Studio Installer, on the Individual components tab, search for Windows 10 SDK (10.0.19041.0), select this version and continue with install. Note that Visual Studio will automatically install Windows 10 SDK (10.0.19041.1) on your machine.

If you already have Visual Studio 2019 installed, you can install the Windows 10 SDK (10.0.19041.1) by using the Modify button in Visual Studio install.

WDK has Spectre mitigation enabled by default but requires spectre mitigated libraries to be installed with Visual Studio for each architecture you are developing for. Additionally, developing drivers for ARM/ARM64 require the build tools for these architectures to also be installed with Visual Studio. To locate these items you will need to know the latest version of MSVC installed on your system.

To find the latest version of MSVC installed on your system, in Visual Studio Installer go to workload page, on the right pane under installation details, expand Desktop development with C++ and locate the MSVC v142 — VS 2019 C++ x64/x86 build tools (V14.xx) — note where xx should be the highest version available.

With this information (v14.xx), go to Individual components and search for v14.xx. This will return the tool sets for all architectures, including Spectre mitigated libs. Select the driver architecture you are developing for.

For example, searching for v14.25 returns the following:

Step 1.5 Install Refreshed Windows SDK 10.0.19041.685 for Windows 10, version 2004

This SDK is strongly recommended and will eventually be made available through Visual Studio

Step 2: Install Refreshed WDK for Windows 10, version 2004

The WDK Visual Studio extension is included in the default WDK installation.

If you can’t find driver project templates in Visual Studio, the WDK Visual Studio extension didn’t install properly. To resolve this, run the WDK.vsix file from this location: C:\Program Files (x86)\Windows Kits\10\Vsix\VS2019\WDK.vsix.

Enterprise WDK (EWDK) for Windows 10, version 2004

The EWDK is a standalone, self-contained command-line environment for building drivers. It includes the Visual Studio Build Tools, the SDK, and the WDK. The latest public version of the EWDK contains Visual Studio 2019 Build Tools 16.7.0 and MSVC toolset v14.23. To get started, mount the ISO and run LaunchBuildEnv.

The EWDK also requires the .NET Framework version 4.7.2. For more information about other requirements for the .NET Framework, see .NET Framework system requirements.

EWDK with Visual Studio Build Tools

You can use the Visual Studio interface with the build tools provided in the EWDK.

1. Mount the EWDK ISO.
2. Run LaunchBuildEnv.cmd .
3. In the environment created in step 2, type SetupVSEnv, and then press Enter.
4. Launch devenv.exe from the same environment, using the full file path. Example: «C:\Program Files (x86)\Microsoft Visual Studio\2019\\%Community|Professional|Enterprise%\Common7\IDE\devenv.exe»

Note that the Visual Studio major version should match with the version in the EWDK. For example, Visual Studio 2019 works with the EWDK that contain VS16.X build tools.

Driver samples for Windows 10

To download the driver samples, do one of the following:

• Go to the driver samples page on GitHub, click Clone or download, and then click Download ZIP.
• Download the GitHub Extension for Visual Studio, and then connect to the GitHub repositories.
• Browse the driver samples on the Microsoft Samples portal.