waveOutOpen (mmeapi.h)

Artikel
03/15/2023

Fungsi waveOutOpen membuka perangkat output waveform-audio yang diberikan untuk pemutaran.

Sintaks

MMRESULT waveOutOpen(
  LPHWAVEOUT      phwo,
  UINT            uDeviceID,
  LPCWAVEFORMATEX pwfx,
  DWORD_PTR       dwCallback,
  DWORD_PTR       dwInstance,
  DWORD           fdwOpen
);

Parameter

phwo

Penunjuk ke buffer yang menerima handel yang mengidentifikasi perangkat output waveform-audio terbuka. Gunakan handel untuk mengidentifikasi perangkat saat memanggil fungsi output waveform-audio lainnya. Parameter ini mungkin NULL jika bendera WAVE_FORMAT_QUERY ditentukan untuk fdwOpen.

uDeviceID

Pengidentifikasi perangkat output waveform-audio untuk dibuka. Ini bisa berupa pengidentifikasi perangkat atau handel perangkat input waveform-audio terbuka. Anda juga dapat menggunakan bendera berikut alih-alih pengidentifikasi perangkat:

Nilai	Makna
WAVE_MAPPER	Fungsi ini memilih perangkat output waveform-audio yang mampu memutar format yang diberikan.

pwfx

Penunjuk ke struktur WAVEFORMATEX yang mengidentifikasi format data waveform-audio yang akan dikirim ke perangkat. Anda dapat membebaskan struktur ini segera setelah meneruskannya ke waveOutOpen.

dwCallback

Menentukan mekanisme panggilan balik. Nilainya harus salah satu dari yang berikut ini:

Penunjuk ke fungsi panggilan balik. Untuk tanda tangan fungsi, lihat waveOutProc.
Handel ke jendela.
Pengidentifikasi utas.
Handel ke peristiwa.
Nilai NULL.

Parameter fdwOpen menentukan bagaimana parameter dwCallback ditafsirkan. Untuk informasi selengkapnya, lihat Keterangan.

dwInstance

Data instans pengguna diteruskan ke mekanisme panggilan balik. Parameter ini tidak digunakan dengan mekanisme panggilan balik jendela.

fdwOpen

Bendera untuk membuka perangkat. Nilai berikut didefinisikan.

Nilai	Makna
CALLBACK_EVENT	Parameter dwCallback adalah handel peristiwa.
CALLBACK_FUNCTION	Parameter dwCallback adalah alamat prosedur panggilan balik.
CALLBACK_NULL	Tidak ada mekanisme panggilan balik. Ini adalah pengaturan default.
CALLBACK_THREAD	Parameter dwCallback adalah pengidentifikasi utas.
CALLBACK_WINDOW	Parameter dwCallback adalah handel jendela.
WAVE_ALLOWSYNC	Jika bendera ini ditentukan, perangkat waveform-audio sinkron dapat dibuka. Jika bendera ini tidak ditentukan saat membuka driver sinkron, perangkat akan gagal dibuka.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Jika bendera ini ditentukan dan parameter uDeviceIDWAVE_MAPPER, fungsi akan membuka perangkat komunikasi default. Bendera ini hanya berlaku ketika uDeviceID sama dengan WAVE_MAPPER. Catatan Membutuhkan Windows 7
WAVE_FORMAT_DIRECT	Jika bendera ini ditentukan, driver ACM tidak melakukan konversi pada data audio.
WAVE_FORMAT_QUERY	Jika bendera ini ditentukan, waveOutOpen meminta perangkat untuk menentukan apakah mendukung format yang diberikan, tetapi perangkat sebenarnya tidak dibuka.
WAVE_MAPPED	Jika bendera ini ditentukan, parameter uDeviceID menentukan perangkat waveform-audio yang akan dipetakan oleh pemeta gelombang.

Mengembalikan nilai

Mengembalikan MMSYSERR_NOERROR jika berhasil atau kesalahan sebaliknya. Kemungkinan nilai kesalahan termasuk yang berikut ini.

Menampilkan kode	Deskripsi
MMSYSERR_ALLOCATED	Sumber daya yang ditentukan sudah dialokasikan.
MMSYSERR_BADDEVICEID	Pengidentifikasi perangkat yang ditentukan berada di luar rentang.
MMSYSERR_NODRIVER	Tidak ada driver perangkat.
MMSYSERR_NOMEM	Tidak dapat mengalokasikan atau mengunci memori.
WAVERR_BADFORMAT	Mencoba membuka dengan format waveform-audio yang tidak didukung.
WAVERR_SYNC	Perangkat sinkron tetapi waveOutOpen dipanggil tanpa menggunakan bendera WAVE_ALLOWSYNC .

Keterangan

Gunakan fungsi waveOutGetNumDevs untuk menentukan jumlah perangkat output waveform-audio yang ada dalam sistem. Jika nilai yang ditentukan oleh parameter uDeviceID adalah pengidentifikasi perangkat, nilai tersebut dapat bervariasi dari nol hingga satu kurang dari jumlah perangkat yang ada. Konstanta WAVE_MAPPER juga dapat digunakan sebagai pengidentifikasi perangkat.

Struktur yang diarahkan oleh pwfx dapat diperluas untuk menyertakan informasi khusus jenis untuk format data tertentu. Misalnya, untuk data PCM, UINT tambahan ditambahkan untuk menentukan jumlah bit per sampel. Gunakan struktur PCMWAVEFORMAT dalam hal ini. Untuk semua format waveform-audio lainnya, gunakan struktur WAVEFORMATEX untuk menentukan panjang data tambahan.

Jika Anda memilih agar jendela atau utas menerima informasi panggilan balik, pesan berikut dikirim ke fungsi prosedur jendela untuk menunjukkan kemajuan output waveform-audio: MM_WOM_OPEN, MM_WOM_CLOSE, dan MM_WOM_DONE.

Mekanisme Panggilan Balik

Parameter dwCallback dan fdwOpen menentukan bagaimana aplikasi diberi tahu tentang kemajuan output waveform-audio.

Jika fdwOpen berisi bendera CALLBACK_FUNCTION , dwCallback adalah penunjuk ke fungsi panggilan balik. Untuk tanda tangan fungsi, lihat waveOutProc. Parameter uMsg dari panggilan balik menunjukkan kemajuan output audio:

Jika fdwOpen berisi bendera CALLBACK_WINDOW , dwCallback adalah handel ke jendela. Jendela menerima pesan berikut, menunjukkan kemajuan:

Jika fdwOpen berisi bendera CALLBACK_THREAD , dwCallback adalah pengidentifikasi utas. Utas menerima pesan yang tercantum sebelumnya untuk CALLBACK_WINDOW.

Jika fdwOpen berisi bendera CALLBACK_EVENT , dwCallback adalah handel ke peristiwa. Peristiwa ini disinyalir setiap kali status buffer bentuk gelombang berubah. Aplikasi dapat menggunakan WaitForSingleObject atau WaitForMultipleObjects untuk menunggu peristiwa. Ketika peristiwa disinyalkan, Anda bisa mendapatkan status buffer bentuk gelombang saat ini dengan memeriksa anggota dwFlags dari struktur WAVEHDR . (Lihat waveOutPrepareHeader.)

Jika fdwOpen berisi bendera CALLBACK_NULL , dwCallback harus NULL. Dalam hal ini, tidak ada mekanisme panggilan balik yang digunakan.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	mmeapi.h (termasuk Windows.h)
Pustaka	Winmm.lib
DLL	Winmm.dll