Merge pull request #259 from microsoft/pete-dev

More documentation

docs/developer-docs/Windows.Devices.Midi2/clock/MidiClock/README.md

@@ -27,4 +27,6 @@ The static functions are for convenience in calculating offsets to a timestamp,
 | OffsetTimestampByMilliseconds(timestampValue, offsetMilliseconds) | Offsets a given timestamp by the provided (signed) number of milliseconds |
 | OffsetTimestampBySeconds(timestampValue, offsetSeconds) | Offsets a given timestamp by the provided (signed) number of seconds |
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiClock.idl)
+## IDL
+
+[MidiClock IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiClock.idl)

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

@@ -51,4 +51,6 @@ When processing the `MessageReceived` event, do so quickly. This event is synchr
 
 > Note: Wire up event handlers and add message processing plugins prior to calling `Open()`. 
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointConnection.idl)
+## IDL
+
+[MidiEndpointConnection IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointConnection.idl)

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

@@ -28,4 +28,6 @@ This is the main class to use when receving MIDI data from a message source such
 | FillByteArray(bytes, startIndex)| Writes the data starting at the zero-based `startIndex`. Some projections pass a copy of all the data, so this may not always be an efficient approach. Returns the number of bytes written. |
 | FillBuffer(buffer, byteOffset)| Writes the data to the buffer starting at byteOffset. Returns the number of bytes written. |
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageReceivedEventArgs.idl)
+## IDL
+
+[MidiMessageReceivedEventArgs IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageReceivedEventArgs.idl)

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

@@ -81,4 +81,6 @@ When a device is first enumerated by the MIDI Service, if it is a UMP-native dev
 | DeviceMatchesFilter(deviceInformation, endpointFilter) | A helper function to compare a device against the filter. |
 | GetAdditionalPropertiesList() | This returns the list of properties which must be requested during enumeration. Typically not needed for applications, as the watcher calls this function |
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointDeviceInformation.idl)
+## IDL
+
+[MidiEndpointDeviceInformation IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointDeviceInformation.idl)

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

@@ -1,4 +1,24 @@
 # MidiEndpointDeviceInformationUpdateEventArgs
 
-(In progress)
+Represents a notification that endpoint properties have been updated
+
+## Functions
+
+| Property | Description |
+| --------------- | ----------- |
+| 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 |
+| UpdatedStreamConfiguration | True if protocol negotiation changed configuration of the endpoint |
+| UpdatedFunctionBlocks | True if any function blocks have been updated |
+| UpdatedUserMetadata | True if any user-supplied metadata fields have been updated |
+| UpdatedAdditionalCapabilities | True if the additional capabilities have been updated |
+| DeviceInformationUpdate | The source `Windows.Devices.Enumeration.DeviceInformationUpdate` object. |
+
+If none of the `UpdatedXX` properties are true, then other properties have been updated.
+
+## IDL
+
+[MidiEndpointDeviceInformationUpdateEventArgs IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointDeviceInformationUpdateEventArgs.idl)
 

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

@@ -1,3 +1,42 @@
 # MidiEndpointDeviceWatcher
 
-(In progress)
+WinRT provides a `Windows.Devices.Enumeration` namespace with a `DeviceWatcher` class. That class is generic to any type of device, and so requires additional work to use with MIDI devices. Because of that, we've wrapped that functionality in the `MidiEndpointDeviceWatcher` class and the related `MidiEndpointDeviceInformation` class.
+
+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.
+
+## Properties
+
+| Function | Description |
+| --------------- | ----------- |
+| Status | The current status. See the `Windows.Devices.Enumeration.DeviceWatcherStatus` enumeration |
+| EnumeratedEndpointDevices | The list of enumerated devices. Provided here for convenience so applications do not need to keep their own list of MIDI devices.  |
+
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| Start() | Begin device enumeration. Wire up event handlers before calling this function.  |
+| Stop() | Stop device enumeration. |
+
+
+## Static Functions
+
+| Static Function | Description |
+| --------------- | ----------- |
+| CreateWatcher(endpointFilter) | Create a watcher which will enumerate devices based on the provided filter |
+
+## Events
+
+| Event | Description |
+| --------------- | ----------- |
+| Added(source, deviceInformation) | A new endpoint has been added.  |
+| Removed(source, deviceInformationUpdate) | An endpoint has been removed. |
+| Updated(source endpointDeviceInformationUpdate) | Properties of an endpoint have been updated. This is much more common than it was with the older MIDI 1.0 APIs due to both in-protocol endpoint information, and user configuration. |
+| EnumerationCompleted(source) | Raised when the initial device enumeration has been completed. Devices may still be added or removed after this event, but use this to decide when you have enough information to display an initial list. |
+| Stopped(source) | Enumeration has been stopped. |
+
+## IDL
+
+[MidiEndpointDeviceWatcher IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiEndpointDeviceWatcher.idl)

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

@@ -2,5 +2,15 @@
 
 (In progress)
 
+## Functions
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageBuilder.idl)
+| Function | Description |
+| --------------- | ----------- |
+| | |
+| | |
+| | |
+| | |
+
+## IDL
+
+[MidiMessageBuilder IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageBuilder.idl)

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

@@ -2,5 +2,16 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageConverter.idl)
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| | |
+| | |
+| | |
+| | |
+
+## IDL
+
+[MidiMessageConverter IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageConverter.idl)
 

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

@@ -2,5 +2,16 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageTranslator.idl)
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| | |
+| | |
+| | |
+| | |
+
+## IDL
+
+[MidiMessageTranslator IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageTranslator.idl)
 

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

@@ -1,4 +1,16 @@
 # MidiMessageUtility
+
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageUtility.idl)
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| | |
+| | |
+| | |
+| | |
+
+## IDL
+
+[MidiMessageUtility IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageUtility.idl)

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

@@ -2,4 +2,15 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiStreamMessageBuilder.idl)
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| | |
+| | |
+| | |
+| | |
+
+## IDL
+
+[MidiStreamMessageBuilder IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiStreamMessageBuilder.idl)

docs/developer-docs/Windows.Devices.Midi2/metadata/MidiFunctionBlock/README.md

@@ -1,5 +1,50 @@
 # MidiFunctionBlock
 
-(In progress)
+The original MIDI 2.0 USB specification includes the concept of a Group Terminal Block. After ratification of that specification, it was found that Group Terminal Blocks were insufficient for two main reasons:
+1. Group Terminal Blocks are USB-specific, and so are not available on other transports like Network or Virtual.
+2. Group Terminal Blocks are static, defined in USB descriptors, and so cannot change during runtime.
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiFunctionBlock.idl)
+Group Terminal Blocks are still available, but function blocks are the preferred approach for defining capapbilities of a device. When both are available, you should use the function block information.
+
+A function block represents a function of a MIDI 2.0 device. A function block may span one or more groups, and if not a static function block, those group numbers may change during operation. For example, a Tone Generator function of a device may need 64 channels to represent its multi-timbral nature. One way it can accomplish this is to declare a function block which spans 4 groups, each of which has 16 channels of data (16x4 = 64).
+
+Function blocks also represent the valid groups for communication with an endpoint. If an endpoint declares 4 function blocks, which together cover only group indexes 0-5, and all of those blocks are marked active, only those groups should be available to users of an application. This helps cut down on clutter caused by always displaying 16 groups.
+
+Function blocks have names which should be displayed to the user along with the group numbers. In the end, the actual addressible entity is the endpoint stream with the group number in the Universal MIDI Packet. But the function block provides context for that group number.
+
+Per the specification, function blocks can span more than one group, and can overlap with each other so that different functions can be available on the same group.
+
+Function blocks are used in the Windwos MIDI Services API in three ways:
+
+1. A property of a MidiEndpointDeviceInformation object, representing function blocks discovered through endpoint discovery. These function blocks are read-only.
+2. The return value of the AsEquivalentFunctionBlock method of the GroupTerminalBlock class. This is a convenience function. These function blocks are read-only
+3. Provided by the application as part of the device definition for a virtual device in app-to-app MIDI. These function blocks are editable before adding them to the device definition.
+
+## Properties
+
+Most properties are 1:1 with the MIDI 2.0 UMP specification section on function blocks. We assemble the name for you and map values to enumerations when possible.
+
+| Property | Description |
+| --------------- | ----------- |
+| IsReadOnly | True if this function block should be treated as read-only. If you attempt to assign a value to a property in a read-only function block, the assignment will silently fail. |
+| Number | The index of the block 0-31. We use "number" here to be consistent with the specification |
+| Name | The assembled name of the function block |
+| IsActive | True if this block is active |
+| Direction | The direction of the block from the block's point of view. |
+| UIHint | A hint which tells you how this block should be treated in a user interface. This should be considered a "soft filter" for display, not a mechanism to keep blocks completely hidden from a user. |
+| Midi10Connection | How to treat this block if it is a MIDI 1.0 connection |
+| FirstGroupIndex | Zero-based index of the first group spanned by this block. |
+| GroupCount | The number of groups spanned. |
+| MidiCIMessageVersionFormat | MIDI CI version format value |
+| MaxSystemExclusive8Streams | The maximum number of System Exclusive 8 streams allowed. Please refer to the UMP specification for how to treat this value. |
+
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| MidiFunctionBlock() | Construct an empty function block |
+| IncludesGroup(group) | Helper function which returns true if this function exists on the supplied group |
+
+## IDL
+
+[MidiFunctionBlock IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiFunctionBlock.idl)

docs/developer-docs/Windows.Devices.Midi2/metadata/MidiGroupTerminalBlock/README.md

@@ -1,5 +1,31 @@
 # MidiGroupTerminalBlock
 
-(In progress)
+A Group Terminal Block is a USB-only feature used to describe the groups on a device. When available, Function Blocks are the preferred mechanism for finding active groups, names, and more, meaning that the Group Terminal Block can typically be ignored in those cases. For more context, please see the documentation for the [MidiFunctionBlock](../MidiFunctionBlock/) type.
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiGroupTerminalBlock.idl)
+> Note: In Windows MIDI Services, we translate MIDI 1.0 device "ports" into individual Group Terminal Blocks. Each virtual cable number in the stream, which used to become a separate input or output port, now maps to a group number. For example, a 5 port MIDI 1.0 device will now show up as a single endpoint with 5 Group Terminal Blocks each spanning a single group. 
+
+## Properties
+
+| Property | Description |
+| --------------- | ----------- |
+| Number | Block number |
+| Name | Name provided by USB. In the case of MIDI 1.0 devices, when available, this is the `iJack` string |
+| Direction | Direction of the block, from the block's point of view |
+| Protocol | Information about the protocol in use. Note that the Jitter Reduction values here should be ignored. Jitter reduction timestamp handling is negotiated through protocol negotiation, and is entirely handled by the service |
+| FirstGroupIndex | The index of the first group spanned by this block |
+| GroupCount | The number of groups spanned |
+| MaxDeviceInputBandwidthIn4KBitsPerSecondUnits | Please see the USB MIDI 2.0 specification for the actual value for this field. |
+| MaxDeviceOutputBandwidthIn4KBitsPerSecondUnits | Please see the USB MIDI 2.0 specification for the actual value for this field. |
+| CalculatedMaxDeviceInputBandwidthBitsPerSecond | Bits-per-second calculated value for the `MaxDeviceInputBandwidthIn4KBitsPerSecondUnits` property |
+| CalculatedMaxDeviceOutputBandwidthBitsPerSecond | Bits-per-second calculated value for the `MaxDeviceOutputBandwidthIn4KBitsPerSecondUnits` property |
+
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| IncludesGroup(group) | Helper function which returns true if this function exists on the supplied group |
+| AsEquivalentFunctionBlock() | Helper function which returns a `MidiFunctionBlock` that is approximately equivalent to this `MidiGroupTerminalBlock`. This is to enable applications to be able to deal with only a single type of block when showing the metadata |
+
+## IDL
+
+[MidiGroupTerminalBlock IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiGroupTerminalBlock.idl)

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

@@ -2,4 +2,6 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiChannelEndpointListener.idl)
+## IDL
+
+[MidiChannelEndpointListener IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiChannelEndpointListener.idl)

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

@@ -2,4 +2,6 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiGroupEndpointListener.idl)
+## IDL
+
+[MidiGroupEndpointListener IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiGroupEndpointListener.idl)

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

@@ -2,4 +2,6 @@
 
 (In progress)
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageTypeEndpointListener.idl)
+## IDL
+
+[MidiMessageTypeEndpointListener IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiMessageTypeEndpointListener.idl)

docs/developer-docs/Windows.Devices.Midi2/session/MidiSession/README.md

@@ -36,4 +36,6 @@ The two static functions are factory-pattern methods for creating a new session.
 
 > Note: If you manually close a MidiEndpointConnection using `IClosable` (or `IDisposable`), it will not be removed from the MidiSession's collection of endpoints. Instead, use the `DisconnectEndpointConnection` method of the session to keep both in sync. For that reason, we do not recommend that you wrap the `CreateEndpointConnection` calls in a using statement.
 
-[IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiSession.idl)
+## IDL
+
+[MidiSession IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiSession.idl)

docs/developer-docs/Windows.Devices.Midi2/session/MidiSessionSettings/README.md

@@ -1,2 +1,7 @@
-# Section in development
+# MidiSessionSettings
 
+MidiSessionSettings are currently unused. We are evaluating keeping this in the API.
+
+## IDL
+
+[MidiSessionSettings IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiSessionSettings.idl)

docs/developer-docs/Windows.Devices.Midi2/virtual-device/MidiStreamConfigurationRequestReceivedEventArgs/README.md

@@ -1,2 +1,7 @@
-# Section in development
+# MidiStreamConfigurationRequestReceivedEventArgs
 
+(in development)
+
+## IDL
+
+[MidiStreamConfigurationRequestReceivedEventArgs IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiStreamConfigurationRequestReceivedEventArgs.idl)

docs/developer-docs/Windows.Devices.Midi2/virtual-device/MidiVirtualEndpointDevice/README.md

@@ -1,2 +1,32 @@
-# Section in development
+# MidiVirtualEndpointDevice
 
+Fully-featured app-to-app MIDI in a MIDI 2.0 world involves connections to a virtual device which must participate in the full MIDI 2.0 protocol, from discovery through protocol negotiation. To support this scenario, the way app-to-app MIDI works in Windows MIDI Services is for an application to define a device and then using the `MidiSession`, construct that device's endpoint. Once the device endpoint is opened, Windows MIDI Services will then construct a second application-visible multi-client endpoint which applications will use to talk to the device app. 
+
+During that conversation, the service will also handle discovery and protocol negotiation with the virtual device just like it would any physical device. 
+
+The `MidiVirtualEndpointDeviceDefinition` class specifies, in an easy to use format, the responses for discovery and protocol negotiation, as well as the properties to use when constructing the device endpoint.
+
+## Properties
+
+| Property | Description |
+| --------------- | ----------- |
+| DeviceDefinition | The MidiVirtualEndpointDeviceDefinition used to create this device. This should be treated as read-only data. |
+| FunctionBlocks | Current list of function blocks for this device. |
+| SuppressHandledMessages | True if the protocol messages handled by this class should be filtered out of the incoming message stream |
+
+## Functions
+
+| Function | Description |
+| --------------- | ----------- |
+| UpdateFunctionBlock | Update the properties of a single function block. The number of actual function blocks cannot change after creation (per the UMP specification) but blocks may be marked as active or inactive. Changes here will result in the MIDI 2.0 function block notification messages being sent out. |
+| UpdateEndpointName | Update the endpoint name, and send out the appropriate endpoint name notification messages. |
+
+## Events
+
+| Event | Description |
+| --------------- | ----------- |
+| StreamConfigurationRequestReceived(device, args) | Raised when this device receives a Stream Configuration Request UMP message. |
+
+## IDL
+
+[MidiVirtualEndpointDevice IDL](https://github.com/microsoft/MIDI/blob/main/src/api/Client/Midi2Client/MidiVirtualEndpointDevice.idl)