| Namespace | Windows.Devices.Midi2.Enumeration |
|---|---|
| Type Name | MidiEndpointDeviceInformation |
| Type | WinRT Runtime Class |
| Implements | IStringable |
| IDL | MidiEndpointDeviceInformation.idl |
| Library |
This class is a specialized equivalent of the DeviceInformation WinRT class. It handles requesting all of the additional properties necessary for MIDI devices, and also goes a step further to retrieve parent device information so that applications can display the endpoints and parent devices in context.
We’ve heard from developers that we did not provide sufficient information about devices in the past, so we created this class and the associated properties to remedy that. We also heard that Async calls were a non-starter for most DAW applications, so everything in this class is synchronous. Finally, because we don’t want apps to have to rely upon static port names like they have had to with the WinMM API, there are plenty of properties available here which can be used to identify a UMP endpoint.
Note
Rather than the
FindAllorCreateFrom...methods, theMidiEndpointDeviceWatcheris a better way to retrieve a list of endpoints because you can then keep the watcher open in a background thread, and be notified of property changes, device add/remove, etc. You can find example code for using theMidiEndpointDeviceWatcherin thesamplesfolder in the MIDI repo on GitHub.
When displaying endpoint devices to users, you’ll typically want to stick to the defaults: StandardNativeUniversalMidiPacketFormat | StandardNativeMidi1ByteFormat which is helpfully combined into AllStandardEndpoints value of the MidiEndpointDeviceInformationFilters type. You do not want to ever show the Diagnostic Ping in any typical application, and you are unlikely to need to show the system-wide Diagnostic Loopback singletons unless you are specifically offering a diagnostic capability. Finally, you don’t want to show the Virtual Device Responder endpoints because those should be reserved only for the “device” application in app-to-app MIDI.
When a device is first enumerated by the MIDI Service, if it is a UMP-native device, we will attempt endpoint discovery and protocol negotiation. During that, we request all endpoint information and all function block information. The received data is then cached in the device properties so that applications do not need to perform this process themselves. This process completes either when a short timeout is hit, or all requested information has been received. Only at that point are MIDI 1.0 API ports created for the MIDI 2.0 device.
For more information about the Endpoint Discovery and Protocol Negotiation aspect of MIDI 2.0, please see the MIDI 2.0 UMP specification at the MIDI Association web site.
| Property | Source | Description |
|---|---|---|
EndpointDeviceId |
Windows | The endpoint device interface id. This is sometimes called “the SWD” in short-hand because it’s the string that uniquely identifies the software device interface that represents the endpoint. |
Name |
Various | This is the name which should be displayed in any application. It calculates the correct name based on the hierarchy of possible names, including a user-specified name. Always respect the user’s choice here. The name could be changed at any time and should not be relied upon to be constant from session to session, or even within a single session. |
ContainerId |
Windows | The device container GUID. |
DeviceInstanceId |
Windows | The device instance id of the endpoint. |
EndpointPurpose |
Windows | The purpose of the endpoint. This is used primarily for filtering. |
ParentDeviceInstanceId |
Windows | The device instance id of the parent device. |
DeclaredEndpointInfoLastUpdateTime |
Discovery | The time of the last update for endpoint information discovered in-protocol |
DeclaredDeviceIdentityLastUpdateTime |
Discovery | The time of the last update for device identity information discovered in-protocol |
DeclaredStreamConfigurationLastUpdateTime |
Protocol Negotiation | The time of the last update from protocol negotiation |
DeclaredFunctionBlocksLastUpdateTime |
Discovery | The time of the last update of function blocks |
Midi1PortNamingApproach |
User/Config | The naming approach used when generating MIDI 1.0 port names for this endpoint. |
IsMidi1PortCreationEnabled |
Config | True if MIDI 1.0 API port creation is enabled for this endpoint. |
IsMuted |
Config | True if this endpoint is muted (all MIDI communication suppressed). |
Properties |
Windows | Returns the raw device properties for this endpoint. The property values and their ids are not something an application should rely upon – they are an implementation detail subject to change, and are not part of the contract with apps. Instead, all of the interesting/useful properties have been broken out in other ways with strong types. |
| Static Property | Description |
|---|---|
EndpointInterfaceClass |
The class GUID which appears at the end of the Endpoint Ids |
| Function | Description |
|---|---|
GetDeclaredEndpointInfo() |
Returns a MidiDeclaredEndpointInfo structure with the currently stored endpoint discovery information |
GetDeclaredDeviceIdentity() |
Returns a MidiDeclaredDeviceIdentity structure with the currently stored device identity information |
GetDeclaredStreamConfiguration() |
Returns a MidiDeclaredStreamConfiguration structure with the currently stored stream configuration |
GetDeclaredFunctionBlocks() |
Returns a snapshot of the currently stored function blocks |
GetGroupTerminalBlocks() |
Returns the currently stored group terminal blocks (USB devices only) |
GetUserSuppliedInfo() |
Returns a MidiEndpointUserSuppliedInfo structure with the currently stored user-supplied information |
GetTransportSuppliedInfo() |
Returns a MidiEndpointTransportSuppliedInfo with the currently stored transport-supplied information |
GetParentDeviceInformation() |
Retrieves the parent MidiParentDeviceInformation type. |
GetContainerDeviceInformation() |
Gets the device container information as a Windows.Devices.Enumeration.DeviceInformation with appropriate properties |
GetNameTable() |
Returns all the candidate names for MIDI 1.0 API ports created from this UMP endpoint. This is primarily used by the Settings app to enable changing the name of future-created ports. |
| Static Property | Description |
|---|---|
EndpointInterfaceClass |
The class GUID which appears at the end of the Endpoint Ids |
| Static Function | Description |
|---|---|
CreateFromEndpointDeviceId(endpointDeviceId) |
Creates a new MidiEndpointDeviceInformation object from the specified endpoint device id |
FindAll() |
Searches for all endpoint devices and returns a list in the default sort order |
FindAll(sortOrder) |
Searches for all endpoint devices and returns a list in the specified sort order |
FindAll(sortOrder, endpointFilter) |
Searches for all endpoint devices which match the filter, and returns a list in the specified sort order. |
FindAllForContainer(containerId) |
Returns all endpoint devices in the specified device container. |
DeviceMatchesFilter(deviceInformation, endpointFilter) |
A helper function to compare a device against the filter. |
GetAdditionalPropertiesList() |
Returns the list of properties which must be requested during enumeration. Typically not needed for applications, as the watcher calls this function |
Windows MIDI Services is an open source project with all source available on GitHub. We have a great community on Discord as well. Between GitHub and Discord, you should find the information you are looking for.
