PKEY_AudioEngine_OEMFormat

Artikel
06/15/2023

In Windows Vista und höher identifiziert der PKEY_AudioEngine_OEMFormat-Eigenschaftsschlüssel das Standardstreamformat für ein Audioendpunktgerät. Sowohl Rendering- als auch Aufzeichnungsgeräte weisen Standardformate auf. Die globale Audio-Engine verwendet das Standardformat eines Geräts, um eine Verbindung mit dem Gerät für den Betrieb im Freigegebenen Modus herzustellen. Die INF-Datei, die das Gerät installiert, lädt das Standardformat des Geräts in die Registrierung. Der Benutzer kann das Standardformat über die Windows-Multimedia-Systemsteuerung (Mmsys.cpl) ändern. Windows XP und frühere Versionen von Windows unterstützen den PKEY_AudioEngine_OEMFormat-Eigenschaftenschlüssel nicht.

Eine INF-Datei gibt das Standardformat für ein Audioendpunktgerät im Abschnitt add-registry für dieses Gerät an. Das folgende INF-Beispiel zeigt einen Add-Registry-Abschnitt, der das Standardformat für ein Endpunktgerät in die Registrierung lädt.

;;
;; Identify endpoint device as a set of speakers.
;; Set default format to 48-kHz, 16-bit stereo.
;; Add endpoint extension property page.
;;
[OEMSettingsOverride.AddReg]
HKR,"EP\\0", %PKEY_AudioEndpoint_Association%,,%KSNODETYPE_SPEAKER%
HKR,"EP\\0", %PKEY_AudioEngine_OEMFormat%, %REG_BINARY%, 41,00,00,00,28,00,00,00,
 FE,FF,02,00,80,BB,00,00,00,EE,02,00,04,00,10,00,16,00,10,00,03,00,00,00,01,00,
 00,00,00,00,10,00,80,00,00,AA,00,38,9B,71
HKR,"EP\\0", %PKEY_AudioEndpoint_ControlPanelProvider%,,%AUDIOENDPOINT_EXT_UI_CLSID

Das vorherige Beispiel stammt aus der Datei Sysfx.inf im Sysfx-Audiobeispiel im Windows Driver Kit. Der Abschnitt Strings dieser INF-Datei enthält die folgenden Definitionen.

PKEY_AudioEndpoint_ControlPanelProvider = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},1"
PKEY_AudioEndpoint_Association          = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2"
PKEY_AudioEngine_OEMFormat              = "{E4870E26-3CC5-4CD2-BA46-CA0A9A70ED04},3"

Im vorherigen Beispiel wird der Name des Add-Registry-Abschnitts OEMSettingsOverride.AddReg durch eine AddReg-Anweisung in einem Abschnitt zur Schnittstelleninstallation in Sysfx.inf definiert. Im vorherigen Beispiel werden dem Registrierungseintrag für die Geräteschnittstelle mehrere Eigenschaften des Endpunkts 0 (identifiziert durch die Zeichenfolge "EP\\0") hinzugefügt. (Wenn eine Geräteschnittstelle einen Wellenfilter mit mehr als einem Endpunkt darstellt, werden die zusätzlichen Endpunkte mit 1, 2 usw. nummeriert.) Weitere Informationen zu Schnittstelleninstallationsabschnitten finden Sie unter INF AddInterface-Direktive.

Nachdem die INF-Datei die drei Eigenschaftenschlüssel erstellt und die zugehörigen Werte in die Registrierung geladen hat, können Anwendungen auf die Eigenschaften zugreifen, indem sie die IPropertyStore-Schnittstelle für das Endpunktgerät abrufen. Die Headerdatei Mmdeviceapi.h im Windows SDK enthält C/C++-Definitionen der drei Eigenschaftenschlüssel. Weitere Informationen zum Abrufen der IPropertyStore-Schnittstelle finden Sie in der Beschreibung der IMMDevice::OpenPropertyStore-Methode in der Windows SDK-Dokumentation.

Im vorherigen INF-Beispiel identifiziert der PKEY_AudioEndpoint_Association-Eigenschaftsschlüssel die KS-Pinkategorie-GUID für das Endpunktgerät. Der PKEY_AudioEndpoint_ControlPanelProvider Eigenschaftenschlüssel identifiziert die Klassen-GUID für das COM-Schnittstellenobjekt, das die Eigenschaftswerte an die Eigenschaftenseite in Mmsys.cpl für das Endpunktgerät bereitstellt. Weitere Informationen zu diesen Eigenschaftenschlüsseln finden Sie in der Dokumentation zum Windows SDK. Weitere Informationen zu KS-Pinkategorie-GUIDs finden Sie unter Anheften der Kategorieeigenschaft.

Im vorherigen INF-Beispiel ist der Eigenschaftswert, der dem PKEY_AudioEngine_OEMFormat-Eigenschaftsschlüssel zugeordnet ist, ein 48-Byte-REG_BINARY-Wert, der eine serialisierte Darstellung der WAVEFORMATEX - oder WAVEFORMATEXTENSIBLE-Struktur enthält, die das Format beschreibt. Um den REG_BINARY Datenwert zu berechnen, der dem PKEY_AudioEngine_OEMFormat-Eigenschaftsschlüssel zugeordnet werden soll, betten Sie die WAVEFORMATEX - oder WAVEFORMATEXTENSIBLE-Struktur in eine PropVariant-Struktur ein, und serialisieren Sie die PropVariant-Struktur , indem Sie die Funktion StgSerializePropVariant aufrufen. Weitere Informationen zur PropVariant-Struktur und der StgSerializePropVariant-Funktion finden Sie in der Dokumentation zum Windows SDK.

Das folgende Codebeispiel ist eine Konsolenanwendung, die die REG_BINARY Daten ausgibt, die im vorherigen INF-Beispiel angezeigt werden.

//
// Embed a WAVEFORMATEXTENSIBLE structure in a PropVariant
// container, and print the PropVariant structure as a
// serialized stream of bytes in REG_BINARY format.
//

#include <stdio.h>
#include <wtypes.h>
#include <propidl.h>
#include <propvarutil.h>
#include <mmreg.h>
#include <ks.h>
#include <ksmedia.h>

void PrintSerializedFormat(WAVEFORMATEX *pWfx)
{
    HRESULT hr;
    PROPVARIANT var;
    SERIALIZEDPROPERTYVALUE* pVal;
    ULONG cb;

    // Create a VT_BLOB from the WAVEFORMATEX structure.
    var.vt = VT_BLOB;
    var.blob.cbSize = sizeof(*pWfx) + pWfx->cbSize;
    var.blob.pBlobData = (BYTE*)pWfx;

    // Serialize the PROPVARIANT structure. The serialized byte stream
    // will eventually be written to the registry as REG_BINARY data.
    hr = StgSerializePropVariant(&var, &pVal, &cb);
    if (SUCCEEDED(hr))
    {
        // Write the binary data to stdout. Format the output so you can
        // copy and paste it directly into the INF file as REG_BINARY data.
        for (UINT i = 0; i < cb; i++)
        {
            BYTE b = ((BYTE*)pVal)[i];
            wprintf(L"%2.2X,", b);
        }

        wprintf(L"\n");
        CoTaskMemFree(pVal);
    }
}

//
// Use a WAVEFORMATEXTENSIBLE structure to specify the format
// for a 48-kHz, 16-bit, (2-channel) stereo audio stream.
//
void main()
{
    WAVEFORMATEXTENSIBLE wfx;

    wfx.Format.wFormatTag = WAVE_FORMAT_EXTENSIBLE;
    wfx.Format.nChannels = 2;
    wfx.Format.nSamplesPerSec = 48000;
    wfx.Format.nAvgBytesPerSec = 4*48000;
    wfx.Format.nBlockAlign = 4;
    wfx.Format.wBitsPerSample = 16;
    wfx.Format.cbSize = sizeof(WAVEFORMATEXTENSIBLE) - sizeof(WAVEFORMATEX);
    wfx.Samples.wValidBitsPerSample = 16;
    wfx.dwChannelMask = 3;
    wfx.SubFormat = KSDATAFORMAT_SUBTYPE_PCM;

    PrintSerializedFormat(&wfx.Format);
}

Die Standard-Funktion im vorherigen Codebeispiel erstellt eine WAVEFORMATEXTENSIBLE-Struktur, um das Standardformat zu beschreiben. Sie können die Standard-Funktion ändern, um eine WAVEFORMATEX- oder WAVEFORMATEXTENSIBLE-Struktur zu erstellen, um das Standardformat für Ihr Endpunktgerät zu beschreiben.

Die PrintSerializedFormat-Funktion im vorherigen Codebeispiel serialisiert die Formatbeschreibung und gibt die serialisierte Formatbeschreibung als REG_BINARY Daten aus. Sie können die von der Funktion erzeugte gedruckte Ausgabe kopieren und in Ihre INF-Datei einfügen.

Freigeben über

PKEY_AudioEngine_OEMFormat

Feedback

Zusätzliche Ressourcen