Share via

Peran Perangkat untuk Aplikasi DirectSound

  • Artikel

Catatan

MMDevice API mendukung peran perangkat. Namun, antarmuka pengguna di Windows Vista tidak menerapkan dukungan untuk fitur ini. Dukungan antarmuka pengguna untuk peran perangkat mungkin diimplementasikan dalam versi Windows yang akan datang. Untuk informasi selengkapnya, lihat Peran Perangkat di Windows Vista.

 

API DirectSound tidak menyediakan sarana bagi aplikasi untuk memilih perangkat titik akhir audio yang telah ditetapkan pengguna ke peran perangkat tertentu. Namun, di Windows Vista, API audio inti dapat digunakan bersama dengan aplikasi DirectSound untuk mengaktifkan pemilihan perangkat berdasarkan peran perangkat. Dengan bantuan API audio inti, aplikasi dapat mengidentifikasi perangkat titik akhir audio yang ditetapkan ke peran tertentu, mendapatkan GUID perangkat DirectSound untuk perangkat titik akhir, dan memanggil fungsi DirectSoundCreate atau DirectSoundCaptureCreate untuk membuat instans antarmuka IDirectSound atau IDirectSoundCapture yang merangkum perangkat titik akhir. Untuk informasi selengkapnya tentang DirectSound, lihat dokumentasi Windows SDK.

Contoh kode berikut menunjukkan cara mendapatkan GUID perangkat DirectSound untuk perangkat penyajian atau pengambilan yang saat ini ditetapkan ke peran perangkat tertentu:

//-----------------------------------------------------------
// Get the DirectSound or DirectSoundCapture device GUID for
// an audio endpoint device. If flow = eRender, the function
// gets the DirectSound device GUID for the rendering device
// with the specified device role. If flow = eCapture, the
// function gets the DirectSoundCapture device GUID for the
// capture device with the specified device role.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hr)  \
              if (FAILED(hr)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

HRESULT GetDirectSoundGuid(EDataFlow flow, ERole role, GUID* pDevGuid)
{
    HRESULT hr = S_OK;
    IMMDeviceEnumerator *pEnumerator = NULL;
    IMMDevice *pDevice = NULL;
    IPropertyStore *pProps = NULL;

    PROPVARIANT var;
    PropVariantInit(&var);

    if (pDevGuid == NULL)
    {
        return E_POINTER;
    }

    // Get a device enumerator for the audio endpoint
    // devices in the system.
    hr = CoCreateInstance(__uuidof(MMDeviceEnumerator),
                          NULL, CLSCTX_INPROC_SERVER,
                          __uuidof(IMMDeviceEnumerator),
                          (void**)&pEnumerator);
    EXIT_ON_ERROR(hr)

    // Get the endpoint device with the specified dataflow
    // direction (eRender or eCapture) and device role.
    hr = pEnumerator->GetDefaultAudioEndpoint(flow, role,
                                              &pDevice);
    EXIT_ON_ERROR(hr)

    hr = pDevice->OpenPropertyStore(STGM_READ, &pProps);
    EXIT_ON_ERROR(hr)

    // Get the DirectSound or DirectSoundCapture device GUID
    // (in WCHAR string format) for the endpoint device.
    hr = pProps->GetValue(PKEY_AudioEndpoint_GUID, &var);
    EXIT_ON_ERROR(hr)

    // Convert the WCHAR string to a GUID structure.
    hr = CLSIDFromString(var.pwszVal, pDevGuid);
    EXIT_ON_ERROR(hr)

Exit:
    PropVariantClear(&var);
    SAFE_RELEASE(pEnumerator);
    SAFE_RELEASE(pDevice);
    SAFE_RELEASE(pProps);
    return hr;
}

Dalam contoh kode sebelumnya, fungsi GetDirectSoundGuid menerima arah aliran data (eRender atau eCapture) dan peran perangkat (eConsole, eMultimedia, atau eCommunications) sebagai parameter input. Parameter ketiga adalah penunjuk di mana fungsi menulis GUID perangkat yang dapat disediakan aplikasi sebagai parameter input ke fungsi DirectSoundCreate atau DirectSoundCaptureCreate .

Contoh kode sebelumnya mendapatkan GUID perangkat DirectSound dengan:

  • Membuat instans antarmuka IMMDevice yang mewakili perangkat titik akhir audio yang memiliki arah aliran data dan peran perangkat yang ditentukan.
  • Membuka penyimpanan properti perangkat titik akhir audio.
  • Mendapatkan properti PKEY_AudioEndpoint_GUID dari penyimpanan properti. Nilai properti adalah representasi string dari GUID perangkat DirectSound untuk perangkat titik akhir audio.
  • Memanggil fungsi CLSIDFromString untuk mengonversi representasi string GUID perangkat ke struktur GUID. Untuk informasi selengkapnya tentang CLSIDFromString, lihat dokumentasi Windows SDK.

Setelah mendapatkan GUID perangkat dari fungsi GetDirectSoundGuid, aplikasi dapat memanggil DirectSoundCreate atau DirectSoundCaptureCreate dengan GUID ini untuk membuat perangkat rendering atau pengambilan DirectSound yang merangkum perangkat titik akhir audio. Saat DirectSound membuat perangkat dengan cara ini, perangkat selalu menetapkan aliran audio perangkat ke sesi default—sesi audio khusus proses yang diidentifikasi oleh nilai GUID sesi GUID_NULL.

Jika aplikasi memerlukan DirectSound untuk menetapkan aliran ke sesi audio lintas proses atau ke sesi dengan GUID sesi non-NULL, aplikasi harus memanggil metode IMMDevice::Activate untuk membuat objek IDirectSound atau IDirectSoundCapture alih-alih menggunakan teknik yang ditunjukkan dalam contoh kode sebelumnya. Untuk contoh kode yang menunjukkan cara menggunakan metode Aktifkan untuk menentukan sesi audio lintas proses atau GUID sesi non-NULL untuk aliran, lihat Peran Perangkat untuk Aplikasi DirectShow. Contoh kode di bagian itu menunjukkan cara membuat filter DirectShow, tetapi, dengan modifikasi kecil, kode dapat disesuaikan untuk membuat perangkat DirectSound.

Fungsi GetDirectSoundGuid dalam contoh kode sebelumnya memanggil fungsi CoCreateInstance untuk membuat enumerator untuk perangkat titik akhir audio dalam sistem. Kecuali program panggilan sebelumnya disebut fungsi CoInitialize atau CoInitializeEx untuk menginisialisasi pustaka COM, panggilan CoCreateInstance akan gagal. Untuk informasi selengkapnya tentang CoCreateInstance, CoInitialize, dan CoInitializeEx, lihat dokumentasi Windows SDK.

Interoperabilitas dengan API Audio Warisan