Função waveOutOpen (mmeapi.h)

Artigo
08/24/2023

A função waveOutOpen abre o dispositivo de saída waveform-audio especificado para reprodução.

Sintaxe

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

Parâmetros

phwo

Ponteiro para um buffer que recebe um identificador que identifica o dispositivo de saída de áudio de forma de onda aberta. Use o identificador para identificar o dispositivo ao chamar outras funções de saída de áudio de forma de onda. Esse parâmetro poderá ser NULL se o sinalizador WAVE_FORMAT_QUERY for especificado para fdwOpen.

uDeviceID

Identificador do dispositivo de saída waveform-audio a ser aberto. Pode ser um identificador de dispositivo ou um identificador de um dispositivo de entrada de áudio de forma de onda aberta. Você também pode usar o seguinte sinalizador em vez de um identificador de dispositivo:

Valor	Significado
WAVE_MAPPER	A função seleciona um dispositivo de saída waveform-audio capaz de reproduzir o formato determinado.

pwfx

Ponteiro para uma estrutura WAVEFORMATEX que identifica o formato dos dados de áudio de forma de onda a serem enviados para o dispositivo. Você pode liberar essa estrutura imediatamente depois de passá-la para waveOutOpen.

dwCallback

Especifica o mecanismo de retorno de chamada. O valor deve ser um dos seguintes:

Um ponteiro para uma função de retorno de chamada. Para a assinatura da função, consulte waveOutProc.
Um identificador para uma janela.
Um identificador de thread.
Um identificador para um evento.
O valor NULL.

O parâmetro fdwOpen especifica como o parâmetro dwCallback é interpretado. Para obter mais informações, consulte Comentários.

dwInstance

Dados de instância de usuário passados para o mecanismo de retorno de chamada. Esse parâmetro não é usado com o mecanismo de retorno de chamada de janela.

fdwOpen

Sinalizadores para abrir o dispositivo. Os valores a seguir são definidos.

Valor	Significado
CALLBACK_EVENT	O parâmetro dwCallback é um identificador de evento.
CALLBACK_FUNCTION	O parâmetro dwCallback é um endereço de procedimento de retorno de chamada.
CALLBACK_NULL	Nenhum mecanismo de retorno de chamada. Essa é a configuração padrão.
CALLBACK_THREAD	O parâmetro dwCallback é um identificador de thread.
CALLBACK_WINDOW	O parâmetro dwCallback é um identificador de janela.
WAVE_ALLOWSYNC	Se esse sinalizador for especificado, um dispositivo de áudio de forma de onda síncrona poderá ser aberto. Se esse sinalizador não for especificado ao abrir um driver síncrono, o dispositivo não será aberto.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Se esse sinalizador for especificado e o parâmetro uDeviceID for WAVE_MAPPER, a função abrirá o dispositivo de comunicação padrão. Esse sinalizador só se aplica quando uDeviceID é igual a WAVE_MAPPER. Nota Requer o Windows 7
WAVE_FORMAT_DIRECT	Se esse sinalizador for especificado, o driver do ACM não executará conversões nos dados de áudio.
WAVE_FORMAT_QUERY	Se esse sinalizador for especificado, waveOutOpen consultará o dispositivo para determinar se ele dá suporte ao formato determinado, mas o dispositivo não está realmente aberto.
WAVE_MAPPED	Se esse sinalizador for especificado, o parâmetro uDeviceID especificará um dispositivo de áudio de forma de onda a ser mapeado pelo mapeador de ondas.

Valor retornado

Retorna MMSYSERR_NOERROR se tiver êxito ou um erro de outra forma. Os valores de erro possíveis incluem o seguinte.

Código de retorno	Descrição
MMSYSERR_ALLOCATED	O recurso especificado já está alocado.
MMSYSERR_BADDEVICEID	O identificador de dispositivo especificado está fora do intervalo.
MMSYSERR_NODRIVER	Nenhum driver de dispositivo está presente.
MMSYSERR_NOMEM	Não é possível alocar ou bloquear memória.
WAVERR_BADFORMAT	Tentativa de abrir com um formato de áudio de forma de onda sem suporte.
WAVERR_SYNC	O dispositivo é síncrono, mas waveOutOpen foi chamado sem usar o sinalizador WAVE_ALLOWSYNC .

Comentários

Use a função waveOutGetNumDevs para determinar o número de dispositivos de saída waveform-audio presentes no sistema. Se o valor especificado pelo parâmetro uDeviceID for um identificador de dispositivo, ele poderá variar de zero a um menor que o número de dispositivos presentes. A constante WAVE_MAPPER também pode ser usada como um identificador de dispositivo.

A estrutura apontada por pwfx pode ser estendida para incluir informações específicas de tipo para determinados formatos de dados. Por exemplo, para dados pcm, um UINT extra é adicionado para especificar o número de bits por exemplo. Use a estrutura PCMWAVEFORMAT nesse caso. Para todos os outros formatos de áudio de forma de onda, use a estrutura WAVEFORMATEX para especificar o comprimento dos dados adicionais.

Se você optar por ter uma janela ou informações de retorno de chamada de recebimento de thread, as seguintes mensagens serão enviadas para a função de procedimento de janela para indicar o progresso da saída de áudio de forma de onda: MM_WOM_OPEN, MM_WOM_CLOSE e MM_WOM_DONE.

Mecanismo de retorno de chamada

Os parâmetros dwCallback e fdwOpen especificam como o aplicativo é notificado sobre o progresso da saída waveform-audio.

Se fdwOpen contiver o sinalizador CALLBACK_FUNCTION , dwCallback será um ponteiro para uma função de retorno de chamada. Para a assinatura da função, consulte waveOutProc. O parâmetro uMsg do retorno de chamada indica o progresso da saída de áudio:

Se fdwOpen contiver o sinalizador CALLBACK_WINDOW , dwCallback será um identificador para uma janela. A janela recebe as seguintes mensagens, indicando o progresso:

Se fdwOpen contiver o sinalizador CALLBACK_THREAD , dwCallback será um identificador de thread. O thread recebe as mensagens listadas anteriormente para CALLBACK_WINDOW.

Se fdwOpen contiver o sinalizador CALLBACK_EVENT , dwCallback será um identificador para um evento. O evento é sinalizado sempre que o estado do buffer de forma de onda é alterado. O aplicativo pode usar WaitForSingleObject ou WaitForMultipleObjects para aguardar o evento. Quando o evento é sinalizado, você pode obter o estado atual do buffer de forma de onda verificando o membro dwFlags da estrutura WAVEHDR . (Consulte waveOutPrepareHeader.)

Se fdwOpen contiver o sinalizador CALLBACK_NULL , dwCallback deverá ser NULL. Nesse caso, nenhum mecanismo de retorno de chamada é usado.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	mmeapi.h (inclua Windows.h)
Biblioteca	Winmm.lib
DLL	Winmm.dll