MidiEndpointConnection

A MidiEndpointConnection is your application’s connection to one endpoint. You get one from MidiSession.CreateEndpointConnection, and it lasts only as long as that session.

Each connection uses memory for its send and receive buffers, plus a thread to process messages. So a session should usually open only one connection to each endpoint. If you want to split up incoming messages, for example by group or channel, add message processing plugins to that one connection instead of opening more.

The session gives you the connection before it’s open. That way you can attach your event handlers and any message processing plugins before the first message arrives. When you’re ready, call Open(). That connects to the service, sets up the message queues, and starts sending and receiving.

Properties

Static Member Functions

Other Functions

Sending and receiving messages

There are several ways to send messages. Each one suits different languages and different ways of storing message data.

C++ developers, and developers using other languages that can work with COM and pointers, can also use the COM extensions to send and receive messages on an open connection.

Sending one message

Each of these functions sends one message. The message must be one complete, valid Universal MIDI Packet (UMP).

Tip: In every function that takes a timestamp, pass 0 (zero) to skip the scheduler and send the message right away. MidiClock::TimestampConstantSendImmediately is the same value. Any other timestamp is the exact time the service should send the message. The service’s scheduler slows down when it holds thousands of messages, so don’t schedule too many at once, or too far ahead.

Sending several messages in one call

When you send several messages in one call, every message must be complete. Never split one UMP across two calls. If a call holds anything other than whole, valid UMPs, it fails.

Before you build the buffer or list, call GetSupportedMaxMidiWordsPerTransmission to find the most 32-bit MIDI words one call can carry. The number can change, so don’t hard-code it.

These functions send everything at once, without making an extra copy. Every message gets the same timestamp.

These functions copy the data into a new buffer first, and then send it in one call. Every message gets the same timestamp.

This function sends each packet separately, because each one has its own timestamp.

Tip: To learn how WinRT collections work, and how they convert to types like std::vector, see Collections with C++/WinRT.

Sending more data than fits in one call

If a call holds more words than GetSupportedMaxMidiWordsPerTransmission allows, the whole call is rejected and nothing is sent. The result is MidiSendMessageResults.Failed combined with MidiSendMessageResults.TransmissionWordCountExceeded. Because nothing reached the device, it’s safe to try again with a smaller buffer.

Some data is always too big for one call. A System Exclusive 7 packet carries six data bytes in each 64-bit UMP, so a 64 KB bulk dump becomes about 10,900 UMPs, or about 21,800 MIDI words. That will never fit in one call, so your code has to split it up.

When you split a large buffer:

1. Call GetSupportedMaxMidiWordsPerTransmission on the same connection you’re sending to. Don’t hard-code the value, and don’t assume it’s the same for every endpoint or every release.
2. Split only between messages. One UMP must never be spread across two calls.
3. Stop as soon as a call fails. Sending the rest after a failure only makes it harder for the device to recover.
4. Decide ahead of time what to do if only part of the data gets through. The chunks that were accepted have already reached the device. For System Exclusive in particular, a message that was only partly delivered usually means you have to give up and start the whole transfer again.

// Send a large buffer as a series of transmissions, without splitting any UMP.
const uint32_t maxWords = connection.GetSupportedMaxMidiWordsPerTransmission();

uint32_t offset{ 0 };

while (offset < totalWords)
{
    // Gather whole messages until the next one would not fit
    uint32_t chunkWords{ 0 };

    while (offset + chunkWords < totalWords)
    {
        auto packetType = MidiMessageHelper::GetPacketTypeFromMessageFirstWord(words[offset + chunkWords]);

        if (packetType == MidiPacketType::UnknownOrInvalid) return;

        // the MidiPacketType value is also the message length in MIDI words
        const uint32_t messageWords = static_cast<uint32_t>(packetType);

        if (chunkWords + messageWords > maxWords) break;

        chunkWords += messageWords;
    }

    if (chunkWords == 0) return;

    auto sendResult = connection.SendMultipleMessagesWordArray(
        MidiClock::TimestampConstantSendImmediately(), offset, chunkWords, words);

    if (MidiEndpointConnection::SendMessageFailed(sendResult))
    {
        // Any earlier chunks have already reached the device. Do not send the rest.
        break;
    }

    offset += chunkWords;
}

Note for framework and language projection authors: If you wrap this API for another language or app framework, do this splitting inside your wrapper. Don’t make the applications built on your wrapper do it. They usually can’t reach GetSupportedMaxMidiWordsPerTransmission through your wrapper, so they would have to hard-code a limit, and a hard-coded limit isn’t guaranteed to stay correct.

Events

The connection waits for your MessageReceived handler to finish before it hands over the next message, so keep your handler fast.

Applications are usually much faster than devices. But if your handler can’t keep up, the incoming message queue can fill up and cause errors. MIDI 2.0 has no speed limit for devices, and USB 3 and network devices, among others, can send a lot of messages in a very short time.

If you need to do slow work with incoming messages, copy them to your own queue and process them on another thread.

Note: Attach your event handlers and add any message processing plugins before you call Open().

Samples

The “API client basics” samples send and receive messages using the two built-in diagnostic loopback endpoints. To learn more about those endpoints, see Diagnostic endpoints.

• C++ Sample
• C# Sample

Complete code samples available on GitHub