Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit aa03ac2

Browse files
authoredApr 21, 2024··
Merge pull request #325 from microsoft/pete-dev
Doc and sample updates
2 parents 0e8744f + 73e9e8f commit aa03ac2

File tree

17 files changed

+187
-166
lines changed

17 files changed

+187
-166
lines changed
 

‎docs/api/README.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ The Windows.Devices.Midi2 types are documented in these pages.
1010

1111
Typical API workflow:
1212

13+
1. **Check for Windows MIDI Services availability**. Windows MIDI Services is not available on older versions of Windows, or on devices like Xbox, Hololens, and others. The first step is to make a call to check for availability of the services on Windows. If Windows MIDI Services is not available, you may want to fall back to an older MIDI API, or simply inform the user and terminate the application.
1314
1. **Create a new session**, with an appropriate name. The name will be visible to users and so should be meaningful. Each application may open more than one session at a time (for example, different songs in a DAW, or different tabs in a browser). A single session manages the lifetime of the connections opened through it.
1415
2. **Connect to an endpoint**. Typically, you'll get the endpoint's id through the enumeration functions.
1516
3. **Wire up a MidiMessageReceived event handler**. This is how you will receive incoming messages from the endpoint. Messages are received individually, with one event per message.
@@ -20,6 +21,10 @@ Typical API workflow:
2021

2122
Enumeration is how you discover endpoints and get notified of endpoints when they are added, updated, or removed. For the best user experience, keep a `MidiEndpointDeviceWatcher` running in a background thread so you can monitor device removal, and property updates (name, function blocks, etc.)
2223

24+
## Service
25+
26+
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service. This is also where you can check to see if Windows MIDI Services is available on this PC.
27+
2328
## Session
2429

2530
Interaction with a MIDI Endpoint always starts with creating a session.
@@ -52,6 +57,3 @@ A virtual device is the mechanism through which app-to-app MIDI works through th
5257

5358
There are several simple or basic types used in Windows MIDI Services. These types provide formatting and validation to help ensure applications display data in similar ways.
5459

55-
## Service
56-
57-
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service.

‎docs/api/service/MidiService.md

+27-34
Original file line numberDiff line numberDiff line change
@@ -8,57 +8,50 @@ has_children: false
88

99
# MidiService
1010

11+
## Remarks
12+
1113
The MidiService class contains a number of static functions which enable working with the service outside of a specific session.
1214

13-
## Static Functions : Reporting
15+
### Service Health
1416

15-
| Static Function | Description |
16-
|---|---|
17-
| `GetInstalledTransportPlugins()` | Returns a list of `MidiServiceTransportPluginInformation` representing all service transport plugins (also called Abstractions) |
18-
| `GetInstalledMessageProcessingPlugins()` | Returns a list of `MidiServiceMessageProcessingPluginInformation` objects representing all service message processing plugins (also called Transforms) |
19-
| `GetActiveSessions()` | Returns a list of `MidiSessionInformation` detailing all active Windows MIDI Services sessions on this PC. |
17+
| `IsAvailable()` | Returns true of Windows MIDI Services is available on this PC. Calling this function is typically the first step in using Windows MIDI Services in your application. |
18+
| `PingService(UInt8)` | Send the specified count of ping messages to the ping endpoint and report on the status and time. Return if the responses are not received in an internally calculated timeout period. |
19+
| `PingService(UInt8, UInt32)` | Send the specified count of ping messages to the ping endpoint and report on the status and time. Return if responses are not received in the specified timeout period (milliseconds). |
2020

21-
## Static Functions : Loopback Endpoints
22-
23-
| Static Function | Description |
24-
|---|---|
25-
| `CreateTemporaryLoopbackEndpoints(associationId, endpointA, endpointB)` | Create a pair of loopback endpoints which will live until removed through the API or the service is restarted. |
26-
| `RemoveTemporaryLoopbackEndpoints(associationId)` | Remove a pair of temporary loopback endpoints. |
21+
Pinging the Windows service uses the same mechanism as sending any UMP message. The actual message sent is a prioprietary message. (At the time this was created, there was no standard MIDI 2.0 UMP ping message). The message itself is sent to the diagnostics endpoint in the service, which is implemented like any other transport. Therefore, the speed of the pings here and the success of the ping process is a reasonable indicator of service, cross-process queue, and client API health.
2722

28-
Applications creating endpoints for app-to-app MIDI should generally use the Virtual Device support built into the API. However, applications may need to create lightweight loopback endpoints without the protocol negotiation, MIDI 2.0 discovery process, and lifetime management provided by the Virtual Device support. For those scenarios, we have a simple loopback endpoint type.
23+
The diagnostic ping endpoint does not understand any other type of message, and should not be used by applications other than through the ping functions here.
2924

30-
Loopback endpoints created by the user and stored in the configuration file will persist after the service is restarted or the PC rebooted. Loopback endpoints created through this API call are temporary, and will disappear if the service is restarted. In both cases, this feature requires that the loopback endpoint transport is installed and enabled.
25+
The ping does not tell you if a specific transport or device is in a bad state. For example, if a specific USB MIDI device has crashed, this ping message will still work because it is not sent out over USB.
3126

32-
## Static Functions : Runtime Configuration
27+
Here's an example of ping responses through the MIDI console app
3328

34-
| Static Function | Description |
35-
|---|---|
36-
| `UpdateTransportPluginConfiguration(configurationUpdate)` | Sends an update to the service to be used by a transport plugin ("Abstraction") |
37-
| `UpdateProcessingPluginConfiguration(configurationUpdate)` | Sends an update to the service to be used by a message processing plugin ("Transform") |
29+
![MIDI Console Ping](./console-ping.png)
3830

39-
For plugins which support updates at runtime, developers of those plugins should create configuration WinRT types which implement the required configuration interfaces, and create the JSON that is used in the service. In this way, third-party service transport and message processing plugins can be created and configured without changes to the API.
31+
### Reporting
4032

41-
> Note: In version 1 of the API, only transports can be configured at runtime. We're working on enabling configuration of message processing plugins. The API is a no-op.
33+
| `GetInstalledTransportPlugins()` | Returns a list of `MidiServiceTransportPluginInformation` representing all service transport plugins (also called Abstractions) |
34+
| `GetInstalledMessageProcessingPlugins()` | Returns a list of `MidiServiceMessageProcessingPluginInformation` objects representing all service message processing plugins (also called Transforms) |
35+
| `GetActiveSessions()` | Returns a list of `MidiSessionInformation` detailing all active Windows MIDI Services sessions on this PC. |
4236

43-
## Static Functions : Service Health
37+
### Loopback Endpoints
4438

45-
| Static Function | Description |
46-
|---|---|
47-
| `PingService(pingCount)` | Send one or more ping messages to the ping endpoint and report on the status and time. Return if the responses are not received in a calculated timeout period. |
48-
| `PingService(pingCount, timeoutMilliseconds)` | Send one or more ping messages to the ping endpoint and report on the status and time. Return if responses are not received in the specified timeout period. |
39+
| `CreateTemporaryLoopbackEndpoints(Guid, MidiServiceLoopbackEndpointDefinition, MidiServiceLoopbackEndpointDefinition)` | Create a pair of loopback endpoints which will live until removed through the API or the service is restarted. |
40+
| `RemoveTemporaryLoopbackEndpoints(Guid)` | Remove a pair of temporary loopback endpoints when provided their association Id Guid. |
4941

50-
### The ping process
42+
Applications creating endpoints for app-to-app MIDI should generally use the Virtual Device support built into the API. However, applications may need to create lightweight loopback endpoints without the protocol negotiation, MIDI 2.0 discovery process, and lifetime management provided by the Virtual Device support. For those scenarios, we have a simple loopback endpoint type.
5143

52-
Pinging the Windows service uses the same mechanism as sending any UMP message. The actual message sent is a prioprietary message. (At the time this was created, there was no standard MIDI 2.0 UMP ping message). The message itself is sent to the diagnostics endpoint in the service, which is implemented like any other transport. Therefore, the speed of the pings here and the success of the ping process is a reasonable indicator of service, cross-process queue, and client API health.
44+
Loopback endpoints created by the user and stored in the configuration file will persist after the service is restarted or the PC rebooted. Loopback endpoints created through this API call are temporary, and will disappear if the service is restarted. In both cases, this feature requires that the loopback endpoint transport is installed and enabled.
5345

54-
The diagnostic ping endpoint does not understand any other type of message, and should not be used by applications other than through the ping functions here.
46+
### Runtime Configuration
5547

56-
The ping does not tell you if a specific transport or device is in a bad state. For example, if a specific USB MIDI device has crashed, this ping message will still work because it is not sent out over USB.
48+
| `UpdateTransportPluginConfiguration(IMidiServiceTransportPluginConfiguration)` | Sends an update to the service to be used by a transport plugin ("Abstraction") |
49+
| `UpdateProcessingPluginConfiguration(IMidiServiceMessageProcessingPluginConfiguration)` | Sends an update to the service to be used by a message processing plugin ("Transform") |
5750

58-
Here's an example of ping responses through the MIDI console app
51+
For plugins which support updates at runtime, developers of those plugins should create configuration WinRT types which implement the required configuration interfaces, and create the JSON that is used in the service. In this way, third-party service transport and message processing plugins can be created and configured without changes to the API.
5952

60-
![MIDI Console Ping](./console-ping.png)
53+
> Note: In version 1 of the API, only transports can be configured at runtime. We're working on enabling configuration of message processing plugins. The API is a no-op.
6154
62-
## IDL
55+
## See also
6356

64-
[MidiService IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiService.idl)
57+
[MidiService IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiService.idl)

‎docs/api/service/README.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,4 @@ has_children: true
77

88
# Service
99

10-
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service.
11-
10+
The MidiService class is a utility class which provides access to health and status information related to the MidiSrv Service. This is also where you can check to see if Windows MIDI Services is available on this PC.

‎docs/api/simple-types/MidiChannel.md

+11-15
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,29 @@ has_children: false
88

99
# MidiChannel
1010

11-
The MidiChannel class is used to provide formatting and data validation for MIDI 1.0 and MIDI 2.0 channels.
11+
## Remarks
12+
13+
The `MidiChannel` class is used to provide formatting and data validation for MIDI 1.0 and MIDI 2.0 channels. For clarity, the 0-15 value used in all messages is the `Index` and the 1-16 value those are mapped to for user display, is the `NumberForDisplay`.
14+
15+
## Constructors
16+
17+
| `MidiChannel` | Create an empty MidiChannel object (Index 0) |
18+
| `MidiChannel(UInt8)` | Create a MidiChannel with the specified channel Index (0-15) |
1219

1320
## Properties
1421

15-
| Property | Description |
16-
| --------------- | ----------- |
1722
| `Index` | The data value, or channel Index (0-15) |
1823
| `NumberForDisplay` | The number that should be displayed in any UI. (1-16) |
1924

2025
## Static Properties
2126

22-
| Static Property | Description |
23-
| --------------- | ----------- |
2427
| `LabelShort` | Returns the localized abbreviation. For example, "Ch" in English. |
2528
| `LabelFull` | Returns the localized full name. For example, "Channel" in English. |
2629

27-
## Functions
28-
29-
| Function | Description |
30-
| --------------- | ----------- |
31-
| `MidiChannel()` | Constructs an empty `MidiChannel` |
32-
| `MidiChannel(index)` | Constructs a `MidiChannel` with the specified index |
30+
## Static Methods
3331

34-
## Static Functions
32+
| `IsValidChannelIndex(UInt8)` | Verifies that the provided index is valid (between 0 and 15) |
3533

36-
| Static Function | Description |
37-
| --------------- | ----------- |
38-
| `IsValidChannelIndex(index)` | Verifies that the provided index is valid (between 0 and 15) |
34+
## See also
3935

4036
[MidiChannel IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiChannel.idl)

‎docs/api/simple-types/MidiGroup.md

+12-16
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,29 @@ has_children: false
88

99
# MidiGroup
1010

11-
The `MidiGroup` class is used to provide formatting and data validation for UMP (Universal MIDI Packet) groups.
11+
## Remarks
12+
13+
The `MidiGroup` class is used to provide formatting and data validation for MIDI 2.0 groups. For clarity, the 0-15 value used in all messages is the `Index` and the 1-16 value those are mapped to for user display, is the `NumberForDisplay`.
14+
15+
## Constructors
16+
17+
| `MidiGroup` | Create an empty MidiGroup object (Index 0) |
18+
| `MidiChannel(UInt8)` | Create a MidiChannel with the specified channel Index (0-15) |
1219

1320
## Properties
1421

15-
| Property | Description |
16-
| --------------- | ----------- |
17-
| `Index` | The data value, or group Index (0-15) |
22+
| `Index` | The data value, or channel Index (0-15) |
1823
| `NumberForDisplay` | The number that should be displayed in any UI. (1-16) |
1924

2025
## Static Properties
2126

22-
| Static Property | Description |
23-
| --------------- | ----------- |
2427
| `LabelShort` | Returns the localized abbreviation. For example, "Gr" in English. |
2528
| `LabelFull` | Returns the localized full name. For example, "Group" in English. |
2629

27-
## Functions
28-
29-
| Function | Description |
30-
| --------------- | ----------- |
31-
| `MidiGroup()` | Constructs an empty `MidiGroup` |
32-
| `MidiGroup(index)` | Constructs a `MidiGroup` with the specified index |
30+
## Static Methods
3331

34-
## Static Functions
32+
| `IsValidGroupIndex(UInt8)` | Verifies that the provided index is valid (between 0 and 15) |
3533

36-
| Static Function | Description |
37-
| --------------- | ----------- |
38-
| `IsValidGroupIndex(index)` | Verifies that the provided index is valid (between 0 and 15) |
34+
## See also
3935

4036
[MidiGroup IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiGroup.idl)

‎docs/api/simple-types/MidiUniqueId.md

+21-22
Original file line numberDiff line numberDiff line change
@@ -8,43 +8,42 @@ has_children: false
88

99
# MidiUniqueId
1010

11-
The `MidiUniqueId` class is used to provide formatting and data validation for MIDI-CI MUID types used in Function Blocks and MIDI CI transactions.
11+
## Remarks
12+
13+
The `MidiUniqueId` class is used to provide formatting and data validation for MIDI-CI MUID (MIDI Unique Id) types used in Function Blocks and MIDI CI transactions.
1214

1315
In the specification, Byte1 is the LSB and Byte4 is the MSB. We follow that convention here.
1416

17+
## Constructors
18+
19+
| `MidiUniqueId()` | Constructs an empty `MidiUniqueId` |
20+
| `MidiUniqueId(UInt32)` | Constructs the `MidiUniqueId` from the given 28 bit integer |
21+
| `MidiUniqueId(UInt8, UInt8, UInt8, UInt8)` | Constructs a `MidiUniqueId` with the specified seven-bit bytes |
22+
1523
## Properties
1624

17-
| Property | Description |
18-
| --------------- | ----------- |
19-
| `Byte1` | The data value for byte 1 of the MUID |
20-
| `Byte2` | The data value for byte 2 of the MUID |
21-
| `Byte3` | The data value for byte 3 of the MUID |
22-
| `Byte4` | The data value for byte 4 of the MUID |
25+
| `Byte1` | The data value for byte 1 of the MUID (LSB) |
26+
| `Byte2` | The data value for byte 2 of the MUID (second-most LSB) |
27+
| `Byte3` | The data value for byte 3 of the MUID (second-most MSB) |
28+
| `Byte4` | The data value for byte 4 of the MUID (MSB) |
2329
| `As28BitInteger` | The data value converted to a 28 bit integer |
24-
| `IsBroadcast` | True if this is the broadcast MUID value |
25-
| `IsReserved` | True if this is the reserved MUID value |
30+
| `IsBroadcast` | True if this is the broadcast MUID value from the MIDI CI specification |
31+
| `IsReserved` | True if this is the reserved MUID value from the MIDI CI specification |
2632

2733
## Static Properties
2834

2935
| Static Property | Description |
3036
| --------------- | ----------- |
31-
| `LabelShort` | Returns the localized abbreviation. |
32-
| `LabelFull` | Returns the localized full name. |
33-
34-
## Functions
35-
36-
| Function | Description |
37-
| --------------- | ----------- |
38-
| `MidiUniqueId()` | Constructs an empty `MidiUniqueId` |
39-
| `MidiUniqueId(integer28bit)` | Constructs the `MidiUniqueId` from the given 28 bit integer |
40-
| `MidiUniqueId(byte1, byte2, byte3, byte4)` | Constructs a `MidiUniqueId` with the specified bytes |
37+
| `LabelShort` | Returns the localized abbreviation for use in UI. |
38+
| `LabelFull` | Returns the localized full name for use in UI. |
4139

42-
## Static Functions
40+
## Static Methods
4341

4442
| Function | Description |
4543
| --------------- | ----------- |
46-
| `CreateBroadcast()` | Constructs a broadcast `MidiUniqueId` |
47-
| `CreateRandom()` | Constructs a random `MidiUniqueId` |
44+
| `CreateBroadcast()` | Constructs a broadcast `MidiUniqueId` per the MIDI CI specification |
45+
| `CreateRandom()` | Constructs a random `MidiUniqueId` per the MIDI CI specification |
4846

47+
## See also
4948

5049
[MidiUniqueId IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiUniqueId.idl)

‎docs/api/simple-types/README.md

-1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,3 @@ has_children: true
88
# Simple Types
99

1010
There are several simple or basic types used in Windows MIDI Services. These types provide formatting and validation to help ensure applications display data in similar ways.
11-
There was a problem loading the remainder of the diff.

0 commit comments

Comments
 (0)
Please sign in to comment.