Metode IAudioClient::IsFormatSupported (audioclient.h)

Artikel
02/26/2024

Metode IsFormatSupported menunjukkan apakah perangkat titik akhir audio mendukung format aliran tertentu.

Sintaks

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

Parameter

[in] ShareMode

Mode berbagi untuk format aliran. Melalui parameter ini, klien menunjukkan apakah klien ingin menggunakan format yang ditentukan dalam mode eksklusif atau mode bersama. Klien harus mengatur parameter ini ke salah satu nilai enumerasi AUDCLNT_SHAREMODE berikut:

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

Arahkan ke format aliran yang ditentukan. Parameter ini menunjuk ke deskriptor format yang dialokasikan penelepon jenis WAVEFORMATEX atau WAVEFORMATEXTENSIBLE. Klien menulis deskripsi format ke struktur ini sebelum memanggil metode ini. Untuk informasi tentang WAVEFORMATEX dan WAVEFORMATEXTENSIBLE, lihat dokumentasi Windows DDK.

[out] ppClosestMatch

Arahkan ke variabel pointer tempat metode menulis alamat struktur WAVEFORMATEX atau WAVEFORMATEXTENSIBLE . Struktur ini menentukan format yang didukung yang paling dekat dengan format yang ditentukan klien melalui parameter pFormat . Untuk mode bersama (yaitu, jika parameter ShareMode AUDCLNT_SHAREMODE_SHARED), atur ppClosestMatch untuk menunjuk ke variabel penunjuk non-NULL yang valid. Untuk mode eksklusif, atur ppClosestMatch ke NULL. Metode mengalokasikan penyimpanan untuk struktur. Pemanggil bertanggung jawab untuk membebaskan penyimpanan, ketika tidak lagi diperlukan, dengan memanggil fungsi CoTaskMemFree . Jika panggilan IsFormatSupported gagal dan ppClosestMatch bukan NULL, metode mengatur *ppClosestMatch ke NULL. Untuk informasi tentang CoTaskMemFree, lihat dokumentasi Windows SDK.

Menampilkan nilai

Menampilkan kode	Deskripsi
S_OK	Berhasil dan perangkat titik akhir audio mendukung format aliran yang ditentukan.
S_FALSE	Berhasil dengan kecocokan terdekat dengan format yang ditentukan.
AUDCLNT_E_UNSUPPORTED_FORMAT	Berhasil tetapi format yang ditentukan tidak didukung dalam mode eksklusif.

Jika operasi gagal, kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, nilai yang diperlihatkan dalam tabel berikut.

Menampilkan kode	Deskripsi
E_POINTER	Parameter pFormat adalah NULL, atau ppClosestMatch adalah NULL dan ShareMode AUDCLNT_SHAREMODE_SHARED.
E_INVALIDARG	Parameter ShareMode adalah nilai selain AUDCLNT_SHAREMODE_SHARED atau AUDCLNT_SHAREMODE_EXCLUSIVE.
AUDCLNT_E_DEVICE_INVALIDATED	Perangkat titik akhir audio telah dicabut, atau perangkat keras audio atau sumber daya perangkat keras terkait telah dikonfigurasi ulang, dinonaktifkan, dihapus, atau tidak tersedia untuk digunakan.
AUDCLNT_E_SERVICE_NOT_RUNNING	Layanan audio Windows tidak berjalan.

Keterangan

Metode ini menyediakan cara bagi klien untuk menentukan, sebelum memanggil IAudioClient::Initialize, apakah mesin audio mendukung format aliran tertentu.

Untuk mode eksklusif, IsFormatSupported mengembalikan S_OK jika perangkat titik akhir audio mendukung format yang ditentukan pemanggil, atau mengembalikan AUDCLNT_E_UNSUPPORTED_FORMAT jika perangkat tidak mendukung format. Parameter ppClosestMatch dapat berupa NULL. Jika bukan NULL, metode menulis NULL ke *ppClosestMatch.

Untuk mode bersama, jika mesin audio mendukung format yang ditentukan pemanggil, IsFormatSupported mengatur *ppClosestMatch ke NULL dan mengembalikan S_OK. Jika mesin audio tidak mendukung format yang ditentukan pemanggil tetapi mendukung format serupa, metode mengambil format serupa melalui parameter ppClosestMatch dan mengembalikan S_FALSE. Jika mesin audio tidak mendukung format yang ditentukan pemanggil atau format serupa, metode mengatur *ppClosestMatch ke NULL dan mengembalikan AUDCLNT_E_UNSUPPORTED_FORMAT.

Dalam mode bersama, mesin audio selalu mendukung format campuran, yang dapat diperoleh klien dengan memanggil metode IAudioClient::GetMixFormat . Selain itu, mesin audio mungkin mendukung format serupa yang memiliki laju sampel dan jumlah saluran yang sama dengan format campuran tetapi berbeda dalam representasi nilai sampel audio. Mesin audio mewakili nilai sampel secara internal sebagai angka floating-point, tetapi jika format yang ditentukan pemanggil mewakili nilai sampel sebagai bilangan bulat, mesin audio biasanya dapat mengonversi antara nilai sampel bilangan bulat dan representasi floating-point internalnya.

Mesin audio mungkin dapat mendukung berbagai format mode bersama yang lebih luas jika paket penginstalan untuk perangkat audio menyertakan objek pemrosesan audio (APO) efek lokal (LFX) yang dapat menangani konversi format. LFX APO adalah modul perangkat lunak yang melakukan pemrosesan khusus perangkat dari aliran audio. Penyusun grafik audio di layanan audio Windows menyisipkan APO LFX ke dalam aliran antara setiap klien dan mesin audio. Ketika klien memanggil metode IsFormatSupported dan metode menentukan bahwa APO LFX diinstal untuk digunakan dengan perangkat, metode mengarahkan kueri ke LFX APO, yang menunjukkan apakah mendukung format yang ditentukan pemanggil.

Misalnya, APO LFX tertentu mungkin menerima aliran suara surround 6 saluran dari klien dan mengonversi aliran ke format stereo yang dapat dimainkan melalui headphone. Biasanya, LFX APO hanya mendukung format klien dengan laju sampel yang cocok dengan laju sampel format campuran.

Untuk informasi selengkapnya tentang API, lihat Objek Pemrosesan Audio Windows. Untuk informasi selengkapnya tentang metode IsFormatSupported , lihat Format Perangkat.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	audioclient.h

Lihat juga

Antarmuka IAudioClient

IAudioClient::GetMixFormat

IAudioClient::Initialize

Bagikan melalui