Endpoint ID Strings
| Previous | Next |
Endpoint ID Strings
In Windows Vista, the system generates endpoint ID strings to identify the audio endpoint devices in the system. An endpoint ID string is a null-terminated wide-character string. The endpoint ID string for a particular audio endpoint device uniquely identifies the device among all audio endpoint devices in the system.
If a system contains two or more identical audio adapter devices, the corresponding audio endpoint devices will have identical friendly names, but each endpoint device will have a unique endpoint ID string. For more information about obtaining the friendly name of an endpoint device, see Device Properties.
After obtaining an IMMDevice interface instance for an audio endpoint device, a client can call the IMMDevice::GetId method to obtain the endpoint ID string for the device. A client can use the endpoint ID string to create an instance of the audio endpoint device at a later time or in a different process by calling the IMMDeviceEnumerator::GetDevice method.
A client can arrange to receive a notification when the status of any audio endpoint device changes. To receive notifications, the client implements an IMMNotificationClient interface and registers that interface with the MMDevice API. When the status of an endpoint device changes, the MMDevice API calls the appropriate method in the client's IMMNotificationClient interface. One of the input parameters to the method is the endpoint ID string that identifies the endpoint device whose status has changed. For more information about IMMNotificationClient, see Device Events.
Legacy audio APIs such as DirectSound and the Windows multimedia functions have their own interfaces for enumerating and identifying audio devices. In Windows Vista, these interfaces have been extended to supply the endpoint ID strings that identify the endpoint devices that underlie the device abstractions presented by the APIs.
During DirectSound device enumeration, DirectSound supplies the endpoint ID string for each device that it enumerates. For more information, see Audio Events for Legacy Audio Applications.
To obtain the endpoint ID string for a legacy waveform device, use the waveOutMessage or waveInMessage function to send a DRV_QUERYFUNCTIONINSTANCEID message to the waveform device driver. For a code example that shows the use of this message, see Device Roles for Legacy Windows Multimedia Applications.
For more information about using the capabilities of the core audio APIs to enhance applications that use legacy audio APIs, see Interoperability with Legacy Audio APIs.
Clients should treat the contents of the endpoint ID string as opaque. That is, clients should not attempt to parse the contents of the string to obtain information about the device. The reason is that the string format is undefined and might change from one implementation of the MMDevice API system module to the next.
The lifetime of an endpoint ID string is tied to the device installation. The endpoint ID string of a device changes if the user upgrades the device driver, or if the user uninstalls the device, and installs it again. However, the endpoint ID string remains unchanged across system restarts, and the endpoint ID string of a USB audio device remains unchanged if the user unplugs the device and plugs it back in.
| Previous | Next |