Condividi tramite

PKEY_AudioEngine_OEMFormat

  • Articolo

In Windows Vista e versioni successive la chiave della proprietà PKEY_AudioEngine_OEMFormat identifica il formato di flusso predefinito per un dispositivo endpoint audio. Sia i dispositivi di rendering che di acquisizione hanno formati predefiniti. Il motore audio globale usa il formato predefinito di un dispositivo per connettersi al dispositivo per l'operazione in modalità condivisa. Il file INF che installa il dispositivo carica il formato predefinito del dispositivo nel Registro di sistema. L'utente può modificare il formato predefinito tramite il pannello di controllo multimediale di Windows (Mmsys.cpl). Windows XP e le versioni precedenti di Windows non supportano la chiave della proprietà PKEY_AudioEngine_OEMFormat .

Un file INF specifica il formato predefinito per un dispositivo endpoint audio nella sezione del Registro di sistema dei componenti aggiuntivi per tale dispositivo. L'esempio INF seguente mostra una sezione del Registro di sistema che carica il formato predefinito per un dispositivo endpoint nel Registro di sistema.

;;
;; 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

L'esempio precedente è tratto dal file Sysfx.inf nell'esempio audio Sysfx in Windows Driver Kit. La sezione Strings di questo file INF contiene le definizioni seguenti.

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"

Nell'esempio precedente il nome della sezione add-registry, OEMSettingsOverride.AddReg, è definito da una direttiva AddReg in una sezione di installazione dell'interfaccia in Sysfx.inf. Nell'esempio precedente vengono aggiunte diverse proprietà del numero di endpoint 0 (identificate dalla stringa "EP\\0") alla voce del Registro di sistema per l'interfaccia del dispositivo. Se un'interfaccia del dispositivo rappresenta un filtro d'onda con più di un endpoint, gli endpoint aggiuntivi sono numerati 1, 2 e così via. Per altre informazioni sulle sezioni di installazione dell'interfaccia, vedere Direttiva INF AddInterface.

Dopo che il file INF ha creato le tre chiavi di proprietà e caricato i valori associati nel Registro di sistema, le applicazioni possono accedere alle proprietà ottenendo l'interfaccia IPropertyStore per il dispositivo endpoint. Il file di intestazione Mmdeviceapi.h in Windows SDK contiene le definizioni C/C++ delle tre chiavi di proprietà. Per altre informazioni su come ottenere l'interfaccia IPropertyStore, vedere la descrizione del metodo IMMDevice::OpenPropertyStore nella documentazione di Windows SDK.

Nell'esempio INF precedente, la chiave della proprietà PKEY_AudioEndpoint_Association identifica il GUID della categoria di pin KS per il dispositivo endpoint. La chiave della proprietà PKEY_AudioEndpoint_ControlPanelProvider identifica il GUID della classe per l'oggetto interfaccia COM che fornisce i valori delle proprietà alla pagina delle proprietà in Mmsys.cpl per il dispositivo endpoint. Per altre informazioni su queste chiavi di proprietà, vedere la documentazione di Windows SDK. Per altre informazioni sui GUID delle categorie di pin KS, vedere Pin Category Property.For more information about KS pin category GUID, see Pin Category Property.

Nell'esempio INF precedente, il valore della proprietà associato alla chiave della proprietà PKEY_AudioEngine_OEMFormat è un valore di REG_BINARY a 48 byte che contiene una rappresentazione serializzata della struttura WAVEFORMATEX o WAVEFORMATEXTENSIBLE che descrive il formato. Per calcolare il valore di dati REG_BINARY da associare alla chiave della proprietà PKEY_AudioEngine_OEMFormat, incorporare la struttura WAVEFORMATEX o WAVEFORMATEXTENSIBLE in una struttura PropVariant e serializzare la struttura PropVariant chiamando la funzione StgSerializePropVariant. Per altre informazioni sulla struttura PropVariant e sulla funzione StgSerializePropVariant , vedere la documentazione di Windows SDK.

L'esempio di codice seguente è un'applicazione console che stampa i dati REG_BINARY visualizzati nell'esempio INF precedente.

//
// 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);
}

La funzione main nell'esempio di codice precedente crea una struttura WAVEFORMATEXTENSIBLE per descrivere il formato predefinito. È possibile modificare la funzione main per creare una struttura WAVEFORMATEX o WAVEFORMATEXTENSIBLE per descrivere il formato predefinito per il dispositivo endpoint.

La funzione PrintSerializedFormat nell'esempio di codice precedente serializza la descrizione del formato e stampa la descrizione del formato serializzata come dati REG_BINARY. È possibile copiare l'output stampato prodotto dalla funzione e incollarlo nel file INF.