waveOutOpen-Funktion (mmeapi.h)

Artikel
08/24/2023

Die waveOutOpen-Funktion öffnet das angegebene Waveform-Audioausgabegerät für die Wiedergabe.

Syntax

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

Parameter

phwo

Zeiger auf einen Puffer, der ein Handle empfängt, das das Offene Signal-Audio-Ausgabegerät identifiziert. Verwenden Sie das Handle, um das Gerät beim Aufrufen anderer Waveform-Audioausgabefunktionen zu identifizieren. Dieser Parameter kann NULL sein, wenn das flag WAVE_FORMAT_QUERY für fdwOpen angegeben ist.

uDeviceID

Bezeichner des zu öffnenden Waveform-Audioausgabegeräts. Dabei kann es sich entweder um einen Gerätebezeichner oder um ein Handle eines Offenwellenform-Audioeingabegeräts handelt. Sie können auch das folgende Flag anstelle eines Gerätebezeichners verwenden:

Wert	Bedeutung
WAVE_MAPPER	Die Funktion wählt ein Waveform-Audioausgabegerät aus, das das angegebene Format wiedergeben kann.

pwfx

Zeiger auf eine WAVEFORMATEX-Struktur , die das Format der an das Gerät zu sendenden Wellenform-Audiodaten identifiziert. Sie können diese Struktur sofort nach der Übergabe an waveOutOpen freigeben.

dwCallback

Gibt den Rückrufmechanismus an. Folgende Werte sind zulässig:

Ein Zeiger auf eine Rückruffunktion. Die Funktionssignatur finden Sie unter waveOutProc.
Das Fensterhandle
Ein Threadbezeichner.
Ein Handle für ein Ereignis.
Der Wert NULL.

Der parameter fdwOpen gibt an, wie der dwCallback-Parameter interpretiert wird. Weitere Informationen finden Sie in den Hinweisen.

dwInstance

Benutzer-instance Daten, die an den Rückrufmechanismus übergeben werden. Dieser Parameter wird nicht mit dem Fensterrückrufmechanismus verwendet.

fdwOpen

Flags zum Öffnen des Geräts. Die folgenden Werte werden definiert.

Wert	Bedeutung
CALLBACK_EVENT	Der dwCallback-Parameter ist ein Ereignishandle.
CALLBACK_FUNCTION	Der dwCallback-Parameter ist eine Rückrufprozeduradresse.
CALLBACK_NULL	Kein Rückrufmechanismus. Dies ist die Standardeinstellung.
CALLBACK_THREAD	Der dwCallback-Parameter ist ein Threadbezeichner.
CALLBACK_WINDOW	Der dwCallback-Parameter ist ein Fensterhandle.
WAVE_ALLOWSYNC	Wenn dieses Flag angegeben ist, kann ein synchrones Waveform-Audiogerät geöffnet werden. Wenn dieses Flag beim Öffnen eines synchronen Treibers nicht angegeben wird, kann das Gerät nicht geöffnet werden.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Wenn dieses Flag angegeben ist und der uDeviceID-ParameterWAVE_MAPPER ist, öffnet die Funktion das Standardkommunikationsgerät. Dieses Flag gilt nur, wenn uDeviceIDgleich WAVE_MAPPER. Hinweis Erfordert Windows 7
WAVE_FORMAT_DIRECT	Wenn dieses Flag angegeben ist, führt der ACM-Treiber keine Konvertierungen für die Audiodaten durch.
WAVE_FORMAT_QUERY	Wenn dieses Flag angegeben ist, fragt waveOutOpen das Gerät ab, um festzustellen, ob es das angegebene Format unterstützt, aber das Gerät ist nicht tatsächlich geöffnet.
WAVE_MAPPED	Wenn dieses Flag angegeben ist, gibt der uDeviceID-Parameter ein Waveform-Audiogerät an, das vom Wave Mapper zugeordnet werden soll.

Rückgabewert

Gibt MMSYSERR_NOERROR zurück, wenn erfolgreich oder andernfalls ein Fehler auftritt. Mögliche Fehlerwerte sind:

Rückgabecode	Beschreibung
MMSYSERR_ALLOCATED	Die angegebene Ressource ist bereits zugeordnet.
MMSYSERR_BADDEVICEID	Der angegebene Gerätebezeichner liegt außerhalb des Bereichs.
MMSYSERR_NODRIVER	Es ist kein Gerätetreiber vorhanden.
MMSYSERR_NOMEM	Speicher kann nicht zugeordnet oder gesperrt werden.
WAVERR_BADFORMAT	Es wurde versucht, mit einem nicht unterstützten Waveform-Audioformat zu öffnen.
WAVERR_SYNC	Das Gerät ist synchron, aber waveOutOpen wurde aufgerufen, ohne das flag WAVE_ALLOWSYNC zu verwenden.

Hinweise

Verwenden Sie die waveOutGetNumDevs-Funktion , um die Anzahl der im System vorhandenen Waveform-Audioausgabegeräte zu bestimmen. Wenn der durch den uDeviceID-Parameter angegebene Wert ein Gerätebezeichner ist, kann er von 0 bis 1 unter der Anzahl der vorhandenen Geräte variieren. Die WAVE_MAPPER Konstante kann auch als Gerätebezeichner verwendet werden.

Die struktur, auf die pwfx verweist, kann erweitert werden, um typspezifische Informationen für bestimmte Datenformate einzuschließen. Beispielsweise wird für PCM-Daten ein zusätzlicher UINT hinzugefügt, um die Anzahl der Bits pro Stichprobe anzugeben. Verwenden Sie in diesem Fall die PCMWAVEFORMAT-Struktur . Verwenden Sie für alle anderen Waveform-Audioformate die WAVEFORMATEX-Struktur , um die Länge der zusätzlichen Daten anzugeben.

Wenn Sie sich dafür entscheiden, dass ein Fenster oder Thread Rückrufinformationen empfängt, werden die folgenden Meldungen an die Fensterprozedurfunktion gesendet, um den Fortschritt der Waveform-Audioausgabe anzugeben: MM_WOM_OPEN, MM_WOM_CLOSE und MM_WOM_DONE.

Rückrufmechanismus

Die Parameter dwCallback und fdwOpen geben an, wie die Anwendung über den Fortschritt der Waveform-Audioausgabe benachrichtigt wird.

Wenn fdwOpen das flag CALLBACK_FUNCTION enthält, ist dwCallback ein Zeiger auf eine Rückruffunktion. Die Funktionssignatur finden Sie unter waveOutProc. Der uMsg-Parameter des Rückrufs gibt den Fortschritt der Audioausgabe an:

Wenn fdwOpen das flag CALLBACK_WINDOW enthält, ist dwCallback ein Handle für ein Fenster. Das Fenster empfängt die folgenden Meldungen, die den Fortschritt angeben:

Wenn fdwOpen das flag CALLBACK_THREAD enthält, ist dwCallback ein Threadbezeichner. Der Thread empfängt die zuvor für CALLBACK_WINDOW aufgeführten Nachrichten.

Wenn fdwOpen das CALLBACK_EVENT-Flag enthält, ist dwCallback ein Handle für ein Ereignis. Das Ereignis wird immer dann signalisiert, wenn sich der Zustand des Wellenformpuffers ändert. Die Anwendung kann WaitForSingleObject oder WaitForMultipleObjects verwenden, um auf das Ereignis zu warten. Wenn das Ereignis signalisiert wird, können Sie den aktuellen Zustand des Wellenformpuffers abrufen, indem Sie den dwFlags-Member der WAVEHDR-Struktur überprüfen. (Siehe waveOutPrepareHeader.)

Wenn fdwOpen das flag CALLBACK_NULL enthält, muss dwCallbackNULL sein. In diesem Fall wird kein Rückrufmechanismus verwendet.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	mmeapi.h (einschließlich Windows.h)
Bibliothek	Winmm.lib
DLL	Winmm.dll