Merge pull request #292 from microsoft/pete-dev

Additional batch of updates for Dev Preview 5

build/staging/version/BundleInfo.wxi

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

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

@@ -23,7 +23,7 @@ You can learn more about high-resolution timestamps in Windows at [https://aka.m
 | `TimestampFrequency` | Returns the number of timestamp ticks per second. This is calculated the first time it is called, and then cached for future calls. |
 | `TimestampConstantSendImmediately` | Returns the constant to use when you want to send messages immediately and bypass outgoing message scheduling. Developers may use this value or simply provide `0` in place of the timestamp when sending messages.  |
 
-## Static Functions
+## Static Functions for Conversion
 
 The static functions are for convenience in calculating offsets to a timestamp, and for converting between units.
 
@@ -32,6 +32,13 @@ The static functions are for convenience in calculating offsets to a timestamp,
 | `ConvertTimestampToMicroseconds(timestampValue)` | Converts the provided timestamp to microseconds |
 | `ConvertTimestampToMilliseconds(timestampValue)` | Converts the provided timestamp to milliseconds |
 | `ConvertTimestampToSeconds(timestampValue)` | Converts the provided timestamp to seconds |
+
+## Static Functions for Offset
+
+When scheduling messages, you may want to use a more convenient time units. These functions make that easy.
+
+| Static Function | Description |
+| --------------- | ----------- |
 | `OffsetTimestampByTicks(timestampValue, offsetTicks)` | Offsets a given timestamp by the provided (signed) number of ticks |
 | `OffsetTimestampByMicroseconds(timestampValue, offsetMicroseconds)` | Offsets a given timestamp by the provided (signed) number of microseconds |
 | `OffsetTimestampByMilliseconds(timestampValue, offsetMilliseconds)` | Offsets a given timestamp by the provided (signed) number of milliseconds |

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

@@ -32,9 +32,10 @@ This is the main class to use when receving MIDI data from a message source such
 | `FillMessage64(message)` | Adds the data to the provided MidiMessage64 runtimeclass. The reference behavior is projection-dependent. Returns true if the provided type matches the expected packet type and the data has been written. |
 | `FillMessage96(message)` | Adds the data to the provided MidiMessage96 runtimeclass. The reference behavior is projection-dependent. Returns true if the provided type matches the expected packet type and the data has been written. |
 | `FillMessage128(message)` | Adds the data to the provided MidiMessage128 runtimeclass. The reference behavior is projection-dependent. Returns true if the provided type matches the expected packet type and the data has been written. |
-| `FillWordArray(words, 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 words written. |
-| `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. |
+| `FillWordArray(startIndex, words)`| 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 words written. |
+| `FillByteArray(startIndex, bytes)`| 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(byteOffset, buffer)`| Writes the data to the buffer starting at byteOffset. Returns the number of bytes written. |
+| `AppendWordsToList(wordList)`| Adds the message words to the end of the provided list, and returns the number of words added. |
 
 ## IDL
 

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

@@ -24,7 +24,7 @@ When a device is first enumerated by the MIDI Service, if it is a UMP-native dev
 
 | Property | Source | Description |
 | --------------- | ------ | ----------- |
-| `Id` | Windows | The endpoint device interface id |
+| `Id` | 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. |
 | `ContainerId` | Windows | The device container |
 | `DeviceInstanceId` | Windows | The device instance id without the interface information | 
 | `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. |
@@ -34,8 +34,8 @@ When a device is first enumerated by the MIDI Service, if it is a UMP-native dev
 | `ProductInstanceId` | MIDI 2.0 | Property of the same name discovered by MIDI 2.0 in-protocol endpoint information. |
 | `SpecificationVersionMajor` | MIDI 2.0 | Discovered UMP version |
 | `SpecificationVersionMinor` | MIDI 2.0 | Discovered UMP version |
-| `SupportsMidi10Protocol` | MIDI 2.0 | Discovered protocol support |
-| `SupportsMidi20Protocol` | MIDI 2.0 | Discovered protocol support |
+| `SupportsMidi10Protocol` | MIDI 2.0 | Discovered protocol support. For all devices, this defaults to true. |
+| `SupportsMidi20Protocol` | MIDI 2.0 | Discovered protocol support. For UMP-native devices, this defaults to true. |
 | `ConfiguredToReceiveJRTimestamps | MIDI 2.0 | Note that JR timestamps are handled entirely in the service and are not sent back down to the client. |
 | `ConfiguredToSendJRTimestamps | MIDI 2.0 | Note that JR timestamps are handled entirely in the service and are not sent back down to the client. |
 | `DeviceIdentitySystemExclusiveId` | MIDI 2.0 | Device Identity information
@@ -47,6 +47,8 @@ When a device is first enumerated by the MIDI Service, if it is a UMP-native dev
 | `TransportId` | Windows | The Id of the transport abstraction that manages this endpoint |
 | `TransportMnemonic` | Windows | A short abbreviation for the transport. This can be used as a transport identifier. |
 | `TransportSuppliedSerialNumber` | Windows | iSerialNumber, when available in USB, and other ids from other transports. |
+| `TransportSuppliedVendorId` | Windows | For a USB device, this is the VID of the parent device |
+| `TransportSuppliedProductId` | Windows | For a USB device, this is the PID of the parent device |
 | `ManufacturerName` | Windows | The name of the manufacturer of the device, if available |
 | `SupportsMultiClient` | Windows | True if this endpoint supports multi-client use |
 | `NativeDataFormat` | Windows | Because the driver and service handle data format translation, it's not immediately obvious if the device is natively UMP or natively Byte Stream. This property provides that information |

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

@@ -10,15 +10,22 @@ has_children: false
 
 This interface is implemented by the rich MidiMessageXX runtime class types. It may also be used as the interface for message-specific classes you create yourself.
 
+## Properties
+
 | Property | Description |
 | -------- | ----------- |
 | `Timestamp` | 64 bit timestamp set by the receiving transport in the case of incoming messages, or by the sender in the case of outgoing messages |
 | `MessageType` | A [MidiMessageType enumeration value](./MidiMessageTypeEnum.md) which represents the 4 bit MIDI Message type 0x0 - 0xF as defined by the MIDI UMP standard. |
 | `PacketType` | A [MidiPacketType enumeration value](./MidiPacketTypeEnum.md) which can be cast to an int to get the number of 32-bit words in the message packet |
 
+## Functions
+
 | Function | Description |
 | -------- | ----------- |
 | `PeekFirstWord()` | Provides access to the first word of data, even if the message type and size is not yet known by the API user |
+| `GetAllWords()` | Returns all the message words as a list of 32-bit words |
+| `AppendAllMessageWordsToList(targetList)` | Appends all the message words from this message to the target list, and returns the count of words added. |
+| `FillBuffer(byteOffset, targetList)` | Adds the message bytes to the buffer starting at the specified offset, and returns the count of bytes added. |
 
 ## IDL
 

docs/index.md

@@ -5,10 +5,18 @@ has_children: true
 ---
 # Windows MIDI Services
 
+Windows MIDI Services is an open source project, which has been developed with input and feedback from the community. 
+
 > [Source repo and developer releases on GitHub](https://aka.ms/midirepo)
 
 > [Discord Server for discussion about this project](https://aka.ms/mididiscord)
 
+## Get started
+
+While we're in developer preview, get started by downloading and installing the latest release from GitHub here:
+
+- [Latest Developer Releases](https://github.com/microsoft/MIDI/releases)
+
 ## NAMM Show 2024 Presentation
 
 [![Pete's Windows MIDI Services Presentation at NAMM Show 2024](https://img.youtube.com/vi/-pe29zIVUCA/mqdefault.jpg)](https://www.youtube.com/watch?v=-pe29zIVUCA)
@@ -25,7 +33,7 @@ has_children: true
 * **UMP-Centric**. The new API fully embraces MIDI 2.0 and the Universal MIDI Packet format and handles all required translation in the service and driver. This makes the app model simple while ensuring all your existing devices continue to work.
 * **Open Source**. The source code is open and available to everyone under a permissive license. Not sure how something works? Want to create a transport but aren't sure how we did it? Want to investigate a bug or contribute a feature? The code is there for you to explore.
 
-Note: Additionally MIDI CI functionality, which does not technically require OS support, will be coming after version 1.0. We intend to add helpers for profiles, property exchange, MUID tracking, and more. In the meantime, applications can send and receive MIDI CI messages without anything in their way, using custom code or third-party libraries. MIDI CI is just MIDI 1.0-compatible SysEx.
+> Note: Additionally MIDI CI functionality, which does not technically require OS support, will be coming after version 1.0. We intend to add helpers for profiles, property exchange, MUID tracking, and more. In the meantime, applications can send and receive MIDI CI messages without anything in their way, using custom code or third-party libraries. MIDI CI is just MIDI 1.0-compatible SysEx.
 
 ## Developer Samples
 

samples/cpp-winrt/api-client-basics/api-client-basics.vcxproj

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project DefaultTargets="Build" ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.props" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.props')" />
+  <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props')" />
   <Import Project="packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props" Condition="Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props')" />
   <PropertyGroup Label="Globals">
     <CppWinRTOptimized>true</CppWinRTOptimized>
@@ -150,15 +150,15 @@
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
     <Import Project="packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets" Condition="Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets')" />
-    <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.targets" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.targets')" />
+    <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets')" />
   </ImportGroup>
   <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
     <PropertyGroup>
       <ErrorText>This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them.  For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
     </PropertyGroup>
     <Error Condition="!Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props'))" />
     <Error Condition="!Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets'))" />
-    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.props'))" />
-    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.3-0157\build\native\Windows.Devices.Midi2.targets'))" />
+    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props'))" />
+    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets'))" />
   </Target>
 </Project>

samples/cpp-winrt/api-client-basics/main.cpp

@@ -93,9 +93,9 @@ int main()
 
     auto ump32 = MidiMessageBuilder::BuildMidi1ChannelVoiceMessage(
         MidiClock::Now(), // use current timestamp
-        5,      // group 5
+        MidiGroup(5),      // group 5
         Midi1ChannelVoiceMessageStatus::NoteOn,     // 9
-        3,      // channel 3
+        MidiChannel(3),      // channel 3
         120,    // note 120 - hex 0x78
         100);   // velocity 100 hex 0x64
 
@@ -104,7 +104,7 @@ int main()
     std::cout << "Sending single UMP..." << std::endl;
 
     auto ump = ump32.as<IMidiUniversalPacket>();
-    auto sendResult = sendEndpoint.SendMessagePacket(ump);          // could also use the SendWords methods, etc.
+    auto sendResult = sendEndpoint.SendSingleMessagePacket(ump);          // could also use the SendWords methods, etc.
 
     std::cout << std::endl << " ** Wait for the sent UMP to arrive, and then press enter to cleanup. **" << std::endl;
 

samples/cpp-winrt/api-client-basics/packages.config

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <packages>
   <package id="Microsoft.Windows.CppWinRT" version="2.0.240111.5" targetFramework="native" />
-  <package id="Windows.Devices.Midi2" version="1.0.0-preview.3-0157" targetFramework="native" />
+  <package id="Windows.Devices.Midi2" version="1.0.0-preview.5-0185" targetFramework="native" />
 </packages>

samples/cpp-winrt/api-client-send-speed/api-client-send-speed.vcxproj

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project DefaultTargets="Build" ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.props" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.props')" />
+  <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props')" />
   <Import Project="packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props" Condition="Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props')" />
   <PropertyGroup Label="Globals">
     <CppWinRTOptimized>true</CppWinRTOptimized>
@@ -150,15 +150,15 @@
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">
     <Import Project="packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets" Condition="Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets')" />
-    <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.targets" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.targets')" />
+    <Import Project="packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets" Condition="Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets')" />
   </ImportGroup>
   <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
     <PropertyGroup>
       <ErrorText>This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them.  For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
     </PropertyGroup>
     <Error Condition="!Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.props'))" />
     <Error Condition="!Exists('packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Microsoft.Windows.CppWinRT.2.0.240111.5\build\native\Microsoft.Windows.CppWinRT.targets'))" />
-    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.props'))" />
-    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0168\build\native\Windows.Devices.Midi2.targets'))" />
+    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.props'))" />
+    <Error Condition="!Exists('packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets')" Text="$([System.String]::Format('$(ErrorText)', 'packages\Windows.Devices.Midi2.1.0.0-preview.5-0185\build\native\Windows.Devices.Midi2.targets'))" />
   </Target>
 </Project>