funzione waveOutOpen (mmeapi.h)

Articolo
08/24/2023

La funzione waveOutOpen apre il dispositivo di output waveform-audio specificato per la riproduzione.

Sintassi

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

Parametri

phwo

Puntatore a un buffer che riceve un handle che identifica il dispositivo di output open waveform-audio. Usare l'handle per identificare il dispositivo quando si chiamano altre funzioni di output waveform-audio. Questo parametro potrebbe essere NULL se il flag di WAVE_FORMAT_QUERY è specificato per fdwOpen.

uDeviceID

Identificatore del dispositivo di output waveform-audio da aprire. Può essere un identificatore di dispositivo o un handle di un dispositivo di input audio a onda aperta. È anche possibile usare il flag seguente anziché un identificatore di dispositivo:

Valore	Significato
WAVE_MAPPER	La funzione seleziona un dispositivo di output waveform-audio in grado di riprodurre il formato specificato.

pwfx

Puntatore a una struttura WAVEFORMATEX che identifica il formato dei dati waveform-audio da inviare al dispositivo. È possibile liberare questa struttura immediatamente dopo averla passata a waveOutOpen.

dwCallback

Specifica il meccanismo di callback. Il valore deve essere uno dei seguenti:

Puntatore a una funzione di callback. Per la firma della funzione, vedere waveOutProc.
Handle di una finestra.
Identificatore di thread.
Handle a un evento.
Valore NULL.

Il parametro fdwOpen specifica come viene interpretato il parametro dwCallback . Per altre informazioni, vedere la sezione Osservazioni.

dwInstance

Dati dell'istanza utente passati al meccanismo di callback. Questo parametro non viene usato con il meccanismo di callback della finestra.

fdwOpen

Contrassegni per l'apertura del dispositivo. I valori seguenti sono definiti.

Valore	Significato
CALLBACK_EVENT	Il parametro dwCallback è un handle di eventi.
CALLBACK_FUNCTION	Il parametro dwCallback è un indirizzo della routine di callback.
CALLBACK_NULL	Nessun meccanismo di callback. Si tratta dell'impostazione predefinita.
CALLBACK_THREAD	Il parametro dwCallback è un identificatore di thread.
CALLBACK_WINDOW	Il parametro dwCallback è un handle di finestra.
WAVE_ALLOWSYNC	Se questo flag è specificato, è possibile aprire un dispositivo waveform-audio sincrono. Se questo flag non viene specificato durante l'apertura di un driver sincrono, il dispositivo non verrà aperto.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Se questo flag viene specificato e il parametro uDeviceID è WAVE_MAPPER, la funzione apre il dispositivo di comunicazione predefinito. Questo flag si applica solo quando uDeviceID è uguale a WAVE_MAPPER. Nota Richiede Windows 7
WAVE_FORMAT_DIRECT	Se questo flag viene specificato, il driver ACM non esegue conversioni nei dati audio.
WAVE_FORMAT_QUERY	Se questo flag viene specificato, waveOutOpen esegue una query sul dispositivo per determinare se supporta il formato specificato, ma il dispositivo non viene effettivamente aperto.
WAVE_MAPPED	Se questo flag viene specificato, il parametro uDeviceID specifica un dispositivo waveform-audio a cui eseguire il mapping da parte del mapper wave.

Valore restituito

Restituisce MMSYSERR_NOERROR se ha esito positivo o un errore in caso contrario. I valori di errore possibili includono quanto segue.

Codice restituito	Descrizione
MMSYSERR_ALLOCATED	La risorsa specificata è già allocata.
MMSYSERR_BADDEVICEID	L'identificatore del dispositivo specificato non è compreso nell'intervallo.
MMSYSERR_NODRIVER	Non è presente alcun driver di dispositivo.
MMSYSERR_NOMEM	Impossibile allocare o bloccare la memoria.
WAVERR_BADFORMAT	Tentativo di apertura con un formato waveform-audio non supportato.
WAVERR_SYNC	Il dispositivo è sincrono ma waveOutOpen è stato chiamato senza usare il flag di WAVE_ALLOWSYNC .

Commenti

Usare la funzione waveOutGetNumDevs per determinare il numero di dispositivi di output waveform-audio presenti nel sistema. Se il valore specificato dal parametro uDeviceID è un identificatore del dispositivo, può variare da zero a uno minore del numero di dispositivi presenti. La costante WAVE_MAPPER può essere usata anche come identificatore del dispositivo.

La struttura a cui punta pwfx può essere estesa per includere informazioni specifiche del tipo per determinati formati di dati. Ad esempio, per i dati PCM, viene aggiunto un valore UINT aggiuntivo per specificare il numero di bit per esempio. Usare la struttura PCMWAVEFORMAT in questo caso. Per tutti gli altri formati waveform-audio, usare la struttura WAVEFORMATEX per specificare la lunghezza dei dati aggiuntivi.

Se si sceglie di avere una finestra o un thread ricevono informazioni di callback, i messaggi seguenti vengono inviati alla funzione della routine della finestra per indicare lo stato di avanzamento dell'output audio waveform: MM_WOM_OPEN, MM_WOM_CLOSE e MM_WOM_DONE.

Meccanismo di callback

I parametri dwCallback e fdwOpen specificano come l'applicazione riceve una notifica sullo stato di avanzamento dell'output waveform-audio.

Se fdwOpen contiene il flag CALLBACK_FUNCTION , dwCallback è un puntatore a una funzione di callback. Per la firma della funzione, vedere waveOutProc. Il parametro uMsg del callback indica lo stato di avanzamento dell'output audio:

Se fdwOpen contiene il flag CALLBACK_WINDOW , dwCallback è un handle in una finestra. La finestra riceve i messaggi seguenti, che indica lo stato di avanzamento:

Se fdwOpen contiene il flag CALLBACK_THREAD , dwCallback è un identificatore di thread. Il thread riceve i messaggi elencati in precedenza per CALLBACK_WINDOW.

Se fdwOpen contiene il flag CALLBACK_EVENT , dwCallback è un handle per un evento. L'evento viene segnalato ogni volta che lo stato del buffer waveform cambia. L'applicazione può usare WaitForSingleObject o WaitForMultipleObjects per attendere l'evento. Quando l'evento viene segnalato, è possibile ottenere lo stato corrente del buffer della forma onda controllando il membro dwFlags della struttura WAVEHDR . Vedere waveOutPrepareHeader.

Se fdwOpen contiene il flag CALLBACK_NULL , dwCallback deve essere NULL. In questo caso, non viene usato alcun meccanismo di callback.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	mmeapi.h (includere Windows.h)
Libreria	Winmm.lib
DLL	Winmm.dll