MidiServiceTransportPluginConfigManager

MidiServiceTransportPluginConfigManager sends configuration to the MIDI service, and saves it. The configuration classes that come with each transport are its main users. The transport in the service has to understand the JSON, or it can’t use it.

Unless you’re writing a new transport, use the methods that take a configuration class, not the ones that take raw JSON. Each transport has configuration classes for the options it knows about.

Important: The JSON that goes to and from the service is an implementation detail, not a contract, and it can change. Don’t build or edit this JSON by hand, and don’t parse what comes back, unless you’re writing a transport yourself.

Static Methods

Static Properties

Sending and saving are different steps

Sending changes the running service. Saving writes the change to the configuration file, so it comes back after a restart. They’re separate calls on purpose, because each one is useful by itself:

• Send without saving to make a change that lasts only until the service restarts, such as connecting a device just for now.
• Save without sending to record a change for a device that isn’t connected right now.

Most tools send first, and save only if the send worked.

What can be saved

SaveUpdate won’t store something that was never meant to be kept. Transport commands are rejected with ErrorNotPersistable, because a command tells the service to do something now, and there’s nothing in it to store. Configurations that only mean something to the app that made them, such as creating a virtual device, are never saved either. A removal, such as MidiServiceEndpointCustomizationRemovalConfig, deletes the entry it names and isn’t stored itself.

Some configurations change an entry that’s already saved, instead of describing a new one. These are MidiLoopbackUpdateConfig, MidiBasicLoopbackUpdateConfig, MidiNetworkHostKnownClientsConfig and MidiRtpHostKnownClientsConfig. If the entry isn’t saved, SaveUpdate returns ErrorEntryNotSaved and writes nothing, so half an entry is never left in the file.

Reading what’s saved

Each transport manager has methods that read what’s saved, such as MidiLoopbackManager.GetSavedLoopbackEntries and MidiNetworkTransportManager.GetSavedHosts. Saved is what’s in the configuration file, and what the service creates the next time it starts. That’s different from what’s running now, which the GetActive and GetConfigured methods report. The GetSaved methods work even when the service isn’t running.

Sending an update config

Passing a MidiLoopbackUpdateConfig or MidiBasicLoopbackUpdateConfig to SendUpdate(configUpdate) does the same thing as the manager’s UpdateLoopback. The result comes back as a MidiServiceConfigResponse.

Merging, not replacing

A saved change is merged with what’s already saved, so you only have to supply the part you changed. Changing the name in an endpoint customization leaves that endpoint’s stored description and image alone.

A merge can’t remove a value. To clear one, write it as empty, instead of leaving it out.

Some configuration classes, such as MidiNetworkClientConnectConfig and MidiBluetoothDeviceConnectConfig, have a Comment property. It’s saved with the entry, so an entry known only by an address still makes sense to a person.

Saving at the same time

Only one program can save at a time. Another program that tries to save waits a short time, and then gets ErrorConfigFileBusy, so it can try again. The service can always read the configuration while a save is happening.

Important: Always change the configuration through this class, or the tools that come with Windows MIDI Services. Don’t read or edit the configuration file yourself. Its format, name, and location can change in any release.

Complete code samples available on GitHub