KSPROPERTY_JACK_DESCRIPTION3
The KSPROPERTY_JACK_DESCRIPTION3 property is implemented as a pin-wise property that is accessed by using the filter handle.
In version 22H2 and later Windows operating systems, the associated KSJACK_DESCRIPTION3 structure can be used to specify and change the current configuration of the jack.
Usage Summary Table
| Get | Set | Target | Property descriptor type | Property value type |
|---|---|---|---|---|
Yes |
No |
Pin factory (via filter handle) |
KSMULTIPLE_ITEM followed by an array of KSJACK_DESCRIPTION3 structures |
The property value (instance data) is a KSMULTIPLE_ITEM, followed by an array of KSJACK_DESCRIPTION3 structures.
Return Value
A KSPROPERTY_JACK_DESCRIPTION3 property request returns a KSMULTIPLE_ITEM followed by an array of N KSJACK_DESCRIPTION3 structures, where N = the number of jacks that are associated with the specified bridge pin. The following list shows the items that are returned by the property request.
KSMULTIPLE_ITEM.Size = sizeof(KSMULTIPLE_ITEM) + N * sizeof(KSJACK_DESCRIPTION3)
KSMULTIPLE_ITEM.Count = N
KSJACK_DESCRIPTION3[0]
...
KSJACK_DESCRIPTION3[N-1]
Remarks
Communicating audio device changes using KSJACK_DESCRIPTION3 and KSPROPERTY_JACK_DESCRIPTION3
The Windows audio system caches audio device capabilities during audio endpoint creation. These cached values are for capabilities such as the presence of a HW audio engine, format support, container ID, buffer size characteristics, etc. These cached values are retained for the life of the windows installation. They are refreshed only when the audio driver is updated or during an OS upgrade.
With KSJACK_DESCRIPTION3, the Windows audio system provides a mechanism for the audio driver to request all cached values be discarded and refreshed. The request can be triggered by changes in the audio device capabilities such as resource constraints.
Whenever the driver changes the contents of KSJACK_DESCRIPTION3 at runtime, the driver will trigger the existing KSEVENT_PINCAPS_JACKINFOCHANGE event.
The Windows audio system maintains the last reported ConfigId value cached on the audio endpoint. The ConfigId value is retrieved in response to KSEVENT_PINCAPS_JACKINFOCHANGE event and during normal processing of the audio endpoint at system boot, Audio Endpoint Builder service restart, audio driver update, or interface state changes for the endpoint.
If the retrieved ConfigId value differs from the previously stored value, the Windows audio system will discard all previously cached endpoint capabilities and refresh them.
The recommended usage is to define multiple audio endpoint configurations within the driver that is controlled by the ConfigId (bitmask or enum) value. For example, ConfigId of 1 may indicate the presence of an audio engine node, whereas ConfigId 2 would not report an audio engine node. The ConfigId in use by the driver is shared with the Windows audio system through KSPROPERTY_JACK_DESCRIPTION3 and acts to synchronize the endpoint with the capabilities cached by the Windows audio system.
The value of the ConfigId is opaque to Windows. The audio driver could use a timestamp or incrementing value chosen at run time in place of a bitmask or enum as suggested above. This strategy is not recommended as it may result in unnecessary endpoint refreshes during boot up or interface changes to synchronize the last stored ConfigId value to the newly reported value, even when the endpoint capabilities are unchanged. This approach may also increase the chances of the driver and Windows becoming out of sync, which can result in audio playback failures.
The mechanism used to refresh the cached values on the endpoint when the ConfigId changes is the same as used for Operating System Upgrades and Driver Updates. A new endpoint with a different ID is created which will contain the refreshed cached values that match the new ConfigId settings for the endpoint, user settings are then copied from the old endpoint to the new endpoint, and finally the old endpoint is deleted. For more information, on the audio endpoint migration process in OS upgrades, see Operating System Upgrades.
Requirements
Minimum supported client |
Available in version 22H2 and later Windows operating systems. |
Header |
Ksmedia.h |