Merge pull request #261 from microsoft/pete-dev

More docs updates

build/staging/version/BundleInfo.wxi

@@ -1,4 +1,4 @@
 <Include>
   <?define SetupVersionName="Developer Preview 5" ?>
-  <?define SetupVersionNumber="1.0.24038.0027" ?>
+  <?define SetupVersionNumber="1.0.24038.0149" ?>
 </Include>

docs/config-json.md

@@ -22,14 +22,14 @@ JSON is typically case-sensitive for all keys. The Windows.Data.Json parser used
 "{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
         {
             "_comment": "KS MIDI (USB etc.)"
-        },
+        }
 ```
 and
 ```json
 "{26fa740d-469c-4d33-beb1-3885de7d6df1}":
         {
             "_comment": "KS MIDI (USB etc.)"
-        },
+        }
 ```
 
 ## Schema
@@ -61,7 +61,6 @@ Here's an example of a bare-bones file, with sections for three different transp
         {
             "_comment": "Virtual MIDI"
         }
-
     },
     "endpointProcessingPluginSettings":
     {
@@ -83,7 +82,7 @@ The basics of this are identical for each transport. We'll use KS (USB) as an ex
         "userSuppliedName" : "Pete's Kontrol S61",
         "userSuppliedDescription" : "This is my most favorite MIDI 2.0 controller in the whole world!"
     }
-    ...
+
 },
 ```
 
@@ -108,25 +107,7 @@ This is not an exhaustive list, because the transport and processing plugins may
 
 ### Virtual MIDI 
 
-Virtual MIDI includes three different sections inside its transport bucket.
-
-```json
-"{8FEAAD91-70E1-4A19-997A-377720A719C1}":
-{
-    "_comment": "Virtual MIDI",
-    "add":
-    {
-    },
-    "update":
-    {
-    },
-    "remove":
-    {
-
-    }
-
-}
-```
+TODO: Provide examples for this
 
 For the persistent configuration file, typically "add" is all that is specified, as it doesn't make sense to update or remove endpoints or routing on service start.
 

docs/developer-docs/Windows.Devices.Midi2/connections/README.md

@@ -5,4 +5,20 @@ parent: Windows.Devices.Midi2 API
 has_children: true
 ---
 
-# Connection APIs
+# Connecting to a MIDI Endpoint
+
+In Windows MIDI Services, once you have opened a session, you will typically open one or more connections to device endpoints. The session class contains methods which return an initialized, but not open, connection to the specified endpoint.
+
+The remainder of your interaction for sending and receiving data is with the `MidiEndpointConnection` class.
+
+All endpoints in Windows MIDI Services send and receive messages using the Universal MIDI Packet format. Any required translation (for MIDI 1.0 devices, for example) is handled in the service and/or in the USB driver.
+
+Workflow
+
+1. Open a session
+2. Using an endpoint id discovered through enumeration or another mechanism, create an endpoint connection
+3. Wire up to the connection any event handlers or message processors 
+4. Open the connection
+5. Send and receive messages
+6. Using the session, disconnect the connection when you are done with it.
+

docs/developer-docs/Windows.Devices.Midi2/enumeration/MidiEndpointDeviceInformationUpdateEventArgs.md

@@ -14,7 +14,7 @@ Represents a notification that endpoint properties have been updated
 
 | Property | Description |
 | --------------- | ----------- |
-| `Id | Id of the endpoint which has been updated  |
+| `Id` | Id of the endpoint which has been updated  |
 | `UpdatedName` | True if the name properties have been updated  |
 | `UpdatedEndpointInformation` | True if the in-protocol endpoint information has been updated |
 | `UpdatedDeviceIdentity` | True if the in-protocol device identity information has been updated |

docs/developer-docs/Windows.Devices.Midi2/enumeration/MidiEndpointDeviceWatcher.md

@@ -12,7 +12,7 @@ WinRT provides a `Windows.Devices.Enumeration` namespace with a `DeviceWatcher`
 
 This is the class applications should use when they want to find devices, and also be notified when devices are added or removed, or when properties like function blocks or device names change.
 
-Create a MidiEndpointDeviceWatcher on a background thread, and use the internal list of Endpoints as your source of record for device properties.
+Create a `MidiEndpointDeviceWatcher` on a background thread, and use the internal list of Endpoints as your source of record for device properties.
 
 ## Properties
 

docs/developer-docs/Windows.Devices.Midi2/enumeration/README.md

@@ -5,4 +5,13 @@ parent: Windows.Devices.Midi2 API
 has_children: true
 ---
 
-# Enumeration APIs
+# Enumerating Endpoints
+
+Windows MIDI Services provides detailed information about each MIDI endpoint on the system. In addition to ids and names, you can also get user metadata, function blocks, group terminal blocks, in-protocol properties, the parent device and container, and much more.
+
+There are two ways to enumerate endpoint devices.
+
+1. Static enumeration using the `MidiEndpointDeviceInformation` class. This is a snapshot in time and is not updated when in-protocol information is updated, or the user has specified new properties like the name. This approach is really only useful in the simplest of scenarios, as it does not handle device connects and disconnects after the initial enumeration.
+2. Dynamic enumeration using the `MidiEndpointDeviceWatcher`. When you set up a watcher on a background thread, you will be notified when any new endpoints are connected to the system, or any existing endpoints are disconnected. You will also be alerted when properties change on an enumerated device. For example, when new function block information is sent in-protocol, the properties are updated and an event is raised. For these reasons, the device watcher approach is the approach any non-trival application should use to list and track MIDI endpoints.
+
+> Note that you can enumerate endpoint devices using the stock `Windows.Devices.Enumeration.DeviceInformation` and `Windows.Devices.Enumeration.DeviceWatcher` classes. However, those classes do not automatically request the extended property set needed for MIDI, do not translate the binary properties like the group terminal blocks and function blocks, and also do not automatically resolve the relationship with the parent device.

docs/developer-docs/Windows.Devices.Midi2/message-utilities/README.md

@@ -7,3 +7,6 @@ has_children: true
 
 # Message Utilities
 
+There are many open source and internal libraries that can be used for creating and parsing message data. For a functional MIDI API, however, we did have to create a number of these ourselves, and so surface them in the API so that you may take advantage of them in your own code.
+
+For other open source MIDI libraries, visit the official site [midi2.dev](https://midi2.dev), run by members of the MIDI Association. The Windows MIDI Services service and API code uses some of this open source internally.

docs/developer-docs/Windows.Devices.Midi2/messages/IMidiUniversalPacket.md

@@ -20,5 +20,7 @@ This interface is implemented by the rich MidiMessageXX runtime class types. It
 | -------- | ----------- |
 | `PeekFirstWord()` | Provides access to the first word of data, even if the message type and size is not yet known by the API user |
 
+## IDL
+
 [IMidiUniversalPacket IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/IMidiUniversalPacket.idl)
 

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessage128.md

@@ -24,4 +24,6 @@ Includes all functions and properties in `IMidiUniversalPacket`, as well as:
 | `MidiMessage128()` | Default constructor |
 | `MidiMessage128(timestamp, word0, word1, word2, word3)` | Construct a new message with a timestamp and all 32 bit MIDI words |
 
+## IDL
+
 [MidiMessage128 IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessage128.idl)

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessage32.md

@@ -21,4 +21,6 @@ Includes all functions and properties in `IMidiUniversalPacket`, as well as:
 | `MidiMessage32()` | Default constructor |
 | `MidiMessage32(timestamp, word0)` | Construct a new message with a timestamp and 32 bit MIDI word |
 
+## IDL
+
 [MidiMessage32 IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessage32.idl)

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessage64.md

@@ -22,5 +22,7 @@ Includes all functions and properties in `IMidiUniversalPacket`, as well as:
 | `MidiMessage64()` | Default constructor |
 | `MidiMessage64(timestamp, word0, word1)` | Construct a new message with a timestamp and all 32 bit MIDI words |
 
+## IDL
+
 [MidiMessage64 IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessage64.idl)
 

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessage96.md

@@ -23,5 +23,7 @@ Includes all functions and properties in `IMidiUniversalPacket`, as well as:
 | `MidiMessage96()` | Default constructor |
 | `MidiMessage96(timestamp, word0, word1, word2)` | Construct a new message with a timestamp and all 32 bit MIDI words |
 
+## IDL
+
 [MidiMessage96 IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessage96.idl)
 

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessageStruct.md

@@ -17,4 +17,6 @@ has_children: false
 | `Word2` | Third 32-bit MIDI word |
 | `Word3` | Fourth 32-bit MIDI word |
 
+## IDL
+
 [MidiMessageStruct IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageStruct.idl)

docs/developer-docs/Windows.Devices.Midi2/messages/MidiMessageTypeEnum.md

@@ -29,4 +29,6 @@ The values correspond directly to the "mt" field in the MIDI UMP packet and may
 | `FutureReservedE128` | `0xE` | Reserved for future use by the MIDI standards bodies |
 | `Stream128` | `0xF` | 128-bit stream message, including endpoint discovery and function block messages |
 
+## IDL
+
 [MidiMessageType IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageTypeEnum.idl)

docs/developer-docs/Windows.Devices.Midi2/messages/MidiPacketTypeEnum.md

@@ -18,4 +18,6 @@ The values correspond to the number of 32-bit MIDI words in the packet.
 | `UniversalMidiPacket96` | `3` | 96-bit (3 words) Universal MIDI Packet |
 | `UniversalMidiPacket128` | `4` | 128-bit (4 words) Universal MIDI Packet |
 
+## IDL
+
 [MidiPacketType IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiPacketTypeEnum.idl)

docs/developer-docs/Windows.Devices.Midi2/messages/README.md

@@ -7,7 +7,7 @@ has_children: true
 
 # Messages
 
-Windows MIDI Services messages are all sent and received in Universal MIDI Packet (UMP) format. a UMP is made up of 1-4 32 bit MIDI words, sized in 32 bit, 64 bit, 96 bit, and 128 bit packets. The first four bits of the packet are the message type, and from that, you can identify the type and size of message which follows.
+Windows MIDI Services messages are all sent and received in Universal MIDI Packet (UMP) format, even if the device is a bytestream MIDI 1.0 device (we do the translation for you). a UMP is made up of 1-4 32 bit MIDI words, sized in 32 bit, 64 bit, 96 bit, and 128 bit packets. The first four bits of the packet are the message type, and from that, you can identify the type and size of message which follows.
 
 ## Words
 

docs/developer-docs/Windows.Devices.Midi2/processing-plugins/IMidiEndpointMessageProcessingPlugin.md

@@ -8,7 +8,29 @@ has_children: false
 
 # IMidiEndpointMessageProcessingPlugin
 
-(In progress)
+This interface is implemented by any type which can be an endpoint processing plugin in the client API. These plugins are used to process or manipulate messages coming from an endpoint. 
+
+Microsoft provides several plugins in the API, including the `MidiVirtualEndpointDevice`, the `MidiChannelEndpointListener`, and the `MidiGroupEndpointListener`. All of these types implement the `IMidiEndpointMessageProcessingPlugin` interface and operate in the same way.
+
+The main part of message processing is the `ProcessIncomingMessage` callback.
+
+## Properties
+
+| Property | Description |
+| ---- | ---- |
+| `Id` | Generated GUID for this plugin instance. This is needed if you want to remove the plugin from the endpoint connection |
+| `Name` | Optional application-supplied name for this plugin instance. |
+| `Tag` | Optional application-supplied arbitrary data to associate with this plugin instance |
+| `IsEnabled` | True if the plugin is enabled and should participate in message processing |
+
+## Functions
+
+| Function | Description |
+| ---- | ---- |
+| `Initialize(endpointConnection)` | Called by the endpoint connection. Perform any setup code which requires the endpoint connection pointer here. |
+| `OnEndpointConnectionOpened()` | Callback when the endpoint connection is opened. If the plugin is added after the endpoint connection has already been opened, this is called immediately. |
+| `ProcessIncomingMessage(args, skipFurtherListeners, skipMainMessageReceivedEvent)` | Callback for processing an incoming message. If the code sets `skipFurtherListeners` to true, any plugins after this one will not be called. If the code sets `skipMainMessageReceivedEvent` to true, the endpoint's MessageReceived event will not be called for this message. Note: this callback is synchronous, so code in this should execute quickly and return immediately when complete. |
+| `Cleanup()` | Called when the endpoint is tearing down |
 
 ## IDL
 

docs/developer-docs/Windows.Devices.Midi2/processing-plugins/MidiChannelEndpointListener.md

@@ -8,7 +8,24 @@ has_children: false
 
 # MidiChannelEndpointListener
 
-(In progress)
+This class acts as a filter. Incoming messages with the specified group and channel will be provided through the `MessageReceived` event. Other messages will be ignored.
+
+In addition to the properties and methods in `IMidiEndpointMessageProcessingPlugin`, and the MessageReceived event from `IMidiMessageReceivedEventSource` the class provides the following:
+
+## Properties
+
+| Property | Description |
+| ---- | ---- |
+| `IncludeGroup` | The `MidiGroup` that this listener will listen to. |
+| `IncludeChannels` | The channels that this listener will listen to on the group. |
+| `PreventCallingFurtherListeners` | True if this plugin should prevent further listeners from processing a message that is in-scope for this processor. |
+| `PreventFiringMainMessageReceivedEvent` | True if this plugin should prevent the endpoint's `MessageReceived` event from firing if the message was in-scope for this plugin. |
+
+## Functions
+
+| Property | Description |
+| ---- | ---- |
+| `MidiChannelEndpointListener()` | Construct a new instance of this type |
 
 ## IDL
 

docs/developer-docs/Windows.Devices.Midi2/processing-plugins/MidiGroupEndpointListener.md

@@ -8,7 +8,25 @@ has_children: false
 
 # MidiGroupEndpointListener
 
-(In progress)
+This class acts as a filter. Incoming messages with the specified group will be provided through the `MessageReceived` event. Other messages will be ignored.
+
+For a MIDI 1.0 device, where the ports (virtual MIDI cables) have been mapped to UMP groups, this class can provide the equivalent of a MIDI 1.0 port to an application, ignoring all other inputs and operating only on the included groups.
+
+In addition to the properties and methods in `IMidiEndpointMessageProcessingPlugin`, and the MessageReceived event from `IMidiMessageReceivedEventSource` the class provides the following:
+
+## Properties
+
+| Property | Description |
+| ---- | ---- |
+| `IncludeGroups` | The list of `MidiGroup` numbers that this listener will listen to. |
+| `PreventCallingFurtherListeners` | True if this plugin should prevent further listeners from processing a message that is in-scope for this processor. |
+| `PreventFiringMainMessageReceivedEvent` | True if this plugin should prevent the endpoint's `MessageReceived` event from firing if the message was in-scope for this plugin. |
+
+## Functions
+
+| Property | Description |
+| ---- | ---- |
+| `MidiGroupEndpointListener()` | Construct a new instance of this type |
 
 ## IDL
 

docs/developer-docs/Windows.Devices.Midi2/processing-plugins/MidiMessageTypeEndpointListener.md

@@ -8,7 +8,25 @@ has_children: false
 
 # MidiMessageTypeEndpointListener
 
-(In progress)
+This class acts as a filter. Incoming messages with the specified message type will be provided through the `MessageReceived` event. Other messages will be ignored. In this way, the listener can be set up to, for example, only pay attention to MIDI 2.0 Channel Voice messages, leaving stream messages and System Exclusive by the wayside.
+
+In addition to the properties and methods in `IMidiEndpointMessageProcessingPlugin`, and the MessageReceived event from `IMidiMessageReceivedEventSource` the class provides the following:
+
+## Properties
+
+| Property | Description |
+| ---- | ---- |
+| `IncludeMessageTypes` | The list of `MidiMessageType` values that this listener will listen to. |
+| `PreventCallingFurtherListeners` | True if this plugin should prevent further listeners from processing a message that is in-scope for this processor. |
+| `PreventFiringMainMessageReceivedEvent` | True if this plugin should prevent the endpoint's `MessageReceived` event from firing if the message was in-scope for this plugin. |
+
+## Functions
+
+| Property | Description |
+| ---- | ---- |
+| `MidiGroupEndpointListener()` | Construct a new instance of this type |
+
+
 
 ## IDL
 

docs/developer-docs/Windows.Devices.Midi2/service/MidiService.md

@@ -31,8 +31,7 @@ The ping does not tell you if a specific transport or device is in a bad state.
 
 Here's an example of ping responses through the MIDI console app
 
-```
-```
+![MIDI Console Ping](./console-ping.png)
 
 ## A note on updating runtime configuration
 

docs/developer-docs/Windows.Devices.Midi2/service/MidiServiceMessageProcessingPluginInformation.md

@@ -8,3 +8,10 @@ has_children: false
 
 # MidiServiceMessageProcessingPluginInformation
 
+(section in progress)
+
+## IDL
+
+[MidiSessionMidiServiceMessageProcessingPluginInformationInformation IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiServiceMessageProcessingPluginInformation.idl)
+
+

docs/developer-docs/Windows.Devices.Midi2/service/MidiServiceTransportPluginInformation.md

@@ -6,5 +6,10 @@ grand_parent: Windows.Devices.Midi2 API
 has_children: false
 ---
 
+# MidiServiceTransportPluginInformation
 
-# MidiServiceTransportPluginInformation
+(section in progress)
+
+## IDL
+
+[MidiServiceTransportPluginInformation IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiServiceTransportPluginInformation.idl)

docs/developer-docs/Windows.Devices.Midi2/service/MidiSessionConnectionInformation.md

@@ -8,7 +8,7 @@ has_children: false
 
 # MidiSessionConnectionInformation
 
-This class represents an open connection in a Windows MIDI Services session. 
+This class represents an open connection in a Windows MIDI Services session. This is an informational class only for reporting system-wide connection usage. 
 
 ## Static Functions
 

docs/developer-docs/Windows.Devices.Midi2/service/MidiSessionInformation.md

@@ -21,6 +21,14 @@ This class represents an open Windows MIDI Services session.
 | `StartTime` | The date and time the session was created |
 | `Connections` | A list of `MidiSessionConnectionInformation` objects detailing the connections currently open for this session |
 
+## Example
+
+The Windows MIDI Services Console app uses the `MidiSessionInformation` `MidiSessionConnectionInformation` and the `MidiService` class to display active sessions.
+
+![Console midi enum sessions](./console-enum-sessions.png)
+
+In this case, you can see three open sessions. The process name and process id are on the left. The session name is in the text on the right, after the word "Session", and the start time is the date and time in green. Finally, the list of connections for each session is underneath the session information.
+
 ## IDL
 
 [MidiSessionInformation IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiSessionInformation.idl)