Función waveOutOpen (mmeapi.h)

Artículo
03/15/2023

La función waveOutOpen abre el dispositivo de salida de audio de forma de onda determinado para su reproducción.

Sintaxis

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

Parámetros

phwo

Puntero a un búfer que recibe un identificador que identifica el dispositivo de salida de audio de forma de onda abierto. Use el identificador para identificar el dispositivo al llamar a otras funciones de salida de audio de forma de onda. Este parámetro puede ser NULL si se especifica la marca de WAVE_FORMAT_QUERY para fdwOpen.

uDeviceID

Identificador del dispositivo de salida de audio de forma de onda que se va a abrir. Puede ser un identificador de dispositivo o un identificador de un dispositivo de entrada de audio de forma de onda abierto. También puede usar la marca siguiente en lugar de un identificador de dispositivo:

Valor	Significado
WAVE_MAPPER	La función selecciona un dispositivo de salida de audio de forma de onda capaz de reproducir el formato especificado.

pwfx

Puntero a una estructura WAVEFORMATEX que identifica el formato de los datos de audio de forma de onda que se van a enviar al dispositivo. Puede liberar esta estructura inmediatamente después de pasarla a waveOutOpen.

dwCallback

Especifica el mecanismo de devolución de llamada. Debe tener uno de los siguientes valores:

Puntero a una función de devolución de llamada. Para la firma de la función, consulte waveOutProc.
Identificador a una ventana.
Un identificador de subproceso.
Identificador de un evento.
Valor NULL.

El parámetro fdwOpen especifica cómo se interpreta el parámetro dwCallback . Para obtener más información, vea la sección Comentarios.

dwInstance

Datos de instancia de usuario pasados al mecanismo de devolución de llamada. Este parámetro no se usa con el mecanismo de devolución de llamada de ventana.

fdwOpen

Marcas para abrir el dispositivo. Se definen los valores siguientes.

Valor	Significado
CALLBACK_EVENT	El parámetro dwCallback es un identificador de eventos.
CALLBACK_FUNCTION	El parámetro dwCallback es una dirección de procedimiento de devolución de llamada.
CALLBACK_NULL	No hay ningún mecanismo de devolución de llamada. Esta es la configuración predeterminada.
CALLBACK_THREAD	El parámetro dwCallback es un identificador de subproceso.
CALLBACK_WINDOW	El parámetro dwCallback es un identificador de ventana.
WAVE_ALLOWSYNC	Si se especifica esta marca, se puede abrir un dispositivo de audio de forma de onda sincrónico. Si no se especifica esta marca al abrir un controlador sincrónico, el dispositivo no se podrá abrir.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Si se especifica esta marca y se WAVE_MAPPER el parámetro uDeviceID, la función abre el dispositivo de comunicación predeterminado. Esta marca solo se aplica cuando uDeviceID es igual a WAVE_MAPPER. Nota Requiere Windows 7
WAVE_FORMAT_DIRECT	Si se especifica esta marca, el controlador ACM no realiza conversiones en los datos de audio.
WAVE_FORMAT_QUERY	Si se especifica esta marca, waveOutOpen consulta el dispositivo para determinar si admite el formato especificado, pero el dispositivo no se abre realmente.
WAVE_MAPPED	Si se especifica esta marca, el parámetro uDeviceID especifica un dispositivo de audio de forma de onda al que se asignará el asignador de ondas.

Valor devuelto

Devuelve MMSYSERR_NOERROR si se realiza correctamente o si se produce un error de otro modo. Entre los valores de error posibles se incluyen los siguientes.

Código devuelto	Descripción
MMSYSERR_ALLOCATED	El recurso especificado ya está asignado.
MMSYSERR_BADDEVICEID	El identificador de dispositivo especificado está fuera del intervalo.
MMSYSERR_NODRIVER	No hay ningún controlador de dispositivo presente.
MMSYSERR_NOMEM	No se puede asignar o bloquear la memoria.
WAVERR_BADFORMAT	Se intentó abrir con un formato de audio de forma de onda no admitido.
WAVERR_SYNC	El dispositivo es sincrónico, pero se llamó a waveOutOpen sin usar la marca WAVE_ALLOWSYNC .

Comentarios

Use la función waveOutGetNumDevs para determinar el número de dispositivos de salida de audio de forma de onda presentes en el sistema. Si el valor especificado por el parámetro uDeviceID es un identificador de dispositivo, puede variar de cero a uno menor que el número de dispositivos presentes. La constante WAVE_MAPPER también se puede usar como identificador de dispositivo.

La estructura a la que apunta pwfx se puede extender para incluir información específica del tipo para determinados formatos de datos. Por ejemplo, para los datos PCM, se agrega un UINT adicional para especificar el número de bits por muestra. Use la estructura PCMWAVEFORMAT en este caso. Para todos los demás formatos de audio de forma de onda, use la estructura WAVEFORMATEX para especificar la longitud de los datos adicionales.

Si decide tener información de devolución de llamada de ventana o subproceso, los siguientes mensajes se envían a la función de procedimiento de ventana para indicar el progreso de la salida de audio de forma de onda: MM_WOM_OPEN, MM_WOM_CLOSE y MM_WOM_DONE.

Mecanismo de devolución de llamada

Los parámetros dwCallback y fdwOpen especifican cómo se notifica a la aplicación el progreso de la salida de audio de forma de onda.

Si fdwOpen contiene la marca CALLBACK_FUNCTION , dwCallback es un puntero a una función de devolución de llamada. Para la firma de la función, consulte waveOutProc. El parámetro uMsg de la devolución de llamada indica el progreso de la salida de audio:

Si fdwOpen contiene la marca CALLBACK_WINDOW , dwCallback es un identificador de una ventana. La ventana recibe los siguientes mensajes, lo que indica el progreso:

Si fdwOpen contiene la marca CALLBACK_THREAD , dwCallback es un identificador de subproceso. El subproceso recibe los mensajes enumerados anteriormente para CALLBACK_WINDOW.

Si fdwOpen contiene la marca CALLBACK_EVENT , dwCallback es un identificador de un evento. El evento se señala cada vez que cambia el estado del búfer de forma de onda. La aplicación puede usar WaitForSingleObject o WaitForMultipleObjects para esperar el evento. Cuando se señala el evento, puede obtener el estado actual del búfer de forma de onda comprobando el miembro dwFlags de la estructura WAVEHDR . (Consulte waveOutPrepareHeader).

Si fdwOpen contiene la marca CALLBACK_NULL , dwCallback debe ser NULL. En ese caso, no se usa ningún mecanismo de devolución de llamada.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	mmeapi.h (incluye Windows.h)
Library	Winmm.lib
Archivo DLL	Winmm.dll