waveOutOpen 함수(mmeapi.h)

아티클
08/24/2023

waveOutOpen 함수는 재생을 위해 지정된 파형 오디오 출력 디바이스를 엽니다.

구문

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

매개 변수

phwo

열린 파형 오디오 출력 디바이스를 식별하는 핸들을 수신하는 버퍼에 대한 포인터입니다. 핸들을 사용하여 다른 파형 오디오 출력 함수를 호출할 때 디바이스를 식별합니다. fdwOpen에 WAVE_FORMAT_QUERY 플래그가 지정된 경우 이 매개 변수는 NULL일 수 있습니다.

uDeviceID

열 파형 오디오 출력 디바이스의 식별자입니다. 디바이스 식별자 또는 열린 파형 오디오 입력 디바이스의 핸들일 수 있습니다. 디바이스 식별자 대신 다음 플래그를 사용할 수도 있습니다.

값	의미
WAVE_MAPPER	함수는 지정된 형식을 재생할 수 있는 파형 오디오 출력 디바이스를 선택합니다.

pwfx

디바이스로 보낼 파형 오디오 데이터의 형식을 식별하는 WAVEFORMATEX 구조체에 대한 포인터입니다. waveOutOpen에 전달한 직후 이 구조를 해제할 수 있습니다.

dwCallback

콜백 메커니즘을 지정합니다. 값은 다음 중 하나여야 합니다.

콜백 함수에 대한 포인터입니다. 함수 서명은 waveOutProc을 참조하세요.
창에 대한 핸들입니다.
스레드 식별자입니다.
이벤트에 대한 핸들입니다.
값 NULL입니다.

fdwOpen 매개 변수는 dwCallback 매개 변수가 해석되는 방법을 지정합니다. 자세한 내용은 설명 부분을 참조하세요.

dwInstance

콜백 메커니즘에 전달된 사용자 instance 데이터입니다. 이 매개 변수는 창 콜백 메커니즘에 사용되지 않습니다.

fdwOpen

디바이스를 열기 위한 플래그입니다. 다음 값이 정의됩니다.

값	의미
CALLBACK_EVENT	dwCallback 매개 변수는 이벤트 핸들입니다.
CALLBACK_FUNCTION	dwCallback 매개 변수는 콜백 프로시저 주소입니다.
CALLBACK_NULL	콜백 메커니즘이 없습니다. 이 값은 기본 설정입니다.
CALLBACK_THREAD	dwCallback 매개 변수는 스레드 식별자입니다.
CALLBACK_WINDOW	dwCallback 매개 변수는 창 핸들입니다.
WAVE_ALLOWSYNC	이 플래그를 지정하면 동기 파형 오디오 디바이스를 열 수 있습니다. 동기 드라이버를 여는 동안 이 플래그를 지정하지 않으면 디바이스가 열리지 않습니다.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	이 플래그가 지정되고 uDeviceID 매개 변수가 WAVE_MAPPER 경우 함수는 기본 통신 디바이스를 엽니다. 이 플래그는 uDeviceID 가 WAVE_MAPPER 경우에만 적용됩니다. 참고 Windows 7 필요
WAVE_FORMAT_DIRECT	이 플래그를 지정하면 ACM 드라이버는 오디오 데이터에 대한 변환을 수행하지 않습니다.
WAVE_FORMAT_QUERY	이 플래그를 지정하면 waveOutOpen 은 디바이스를 쿼리하여 지정된 형식을 지원하는지 확인하지만 디바이스가 실제로 열리지 않습니다.
WAVE_MAPPED	이 플래그를 지정하면 uDeviceID 매개 변수는 웨이브 매퍼에서 매핑할 파형 오디오 디바이스를 지정합니다.

반환 값

성공하면 MMSYSERR_NOERROR 반환하고, 그렇지 않으면 오류를 반환합니다. 가능한 오류 값은 다음과 같습니다.

반환 코드	설명
MMSYSERR_ALLOCATED	지정된 리소스가 이미 할당되어 있습니다.
MMSYSERR_BADDEVICEID	지정된 디바이스 식별자가 범위를 벗어났습니다.
MMSYSERR_NODRIVER	디바이스 드라이버가 없습니다.
MMSYSERR_NOMEM	메모리를 할당하거나 잠글 수 없습니다.
WAVERR_BADFORMAT	지원되지 않는 파형 오디오 형식으로 열려고 했습니다.
WAVERR_SYNC	디바이스는 동기식이지만 waveOutOpen 은 WAVE_ALLOWSYNC 플래그를 사용하지 않고 호출되었습니다.

설명

waveOutGetNumDevs 함수를 사용하여 시스템에 있는 파형 오디오 출력 디바이스의 수를 확인합니다. uDeviceID 매개 변수로 지정된 값이 디바이스 식별자인 경우 0에서 1까지는 존재하는 디바이스 수보다 작을 수 있습니다. WAVE_MAPPER 상수를 디바이스 식별자로 사용할 수도 있습니다.

pwfx에서 가리키는 구조체를 확장하여 특정 데이터 형식에 대한 형식별 정보를 포함할 수 있습니다. 예를 들어 PCM 데이터의 경우 샘플당 비트 수를 지정하기 위해 추가 UINT 가 추가됩니다. 이 경우 PCMWAVEFORMAT 구조를 사용합니다. 다른 모든 파형 오디오 형식의 경우 WAVEFORMATEX 구조를 사용하여 추가 데이터의 길이를 지정합니다.

창 또는 스레드가 콜백 정보를 수신하도록 선택하는 경우 창 프로시저 함수로 전송되어 파형 오디오 출력의 진행률을 나타내는 MM_WOM_OPEN, MM_WOM_CLOSE 및 MM_WOM_DONE.

콜백 메커니즘

dwCallback 및 fdwOpen 매개 변수는 파형 오디오 출력의 진행률에 대해 애플리케이션에 알림을 받는 방법을 지정합니다.

fdwOpen에 CALLBACK_FUNCTION 플래그가 포함된 경우 dwCallback은 콜백 함수에 대한 포인터입니다. 함수 서명은 waveOutProc을 참조하세요. 콜백의 uMsg 매개 변수는 오디오 출력의 진행률을 나타냅니다.

fdwOpen에 CALLBACK_WINDOW 플래그가 포함된 경우 dwCallback은 창에 대한 핸들입니다. 창은 진행률을 나타내는 다음 메시지를 받습니다.

fdwOpen에 CALLBACK_THREAD 플래그가 포함된 경우 dwCallback은 스레드 식별자입니다. 스레드는 이전에 CALLBACK_WINDOW 대해 나열된 메시지를 받습니다.

fdwOpen에 CALLBACK_EVENT 플래그가 포함된 경우 dwCallback은 이벤트에 대한 핸들입니다. 파형 버퍼의 상태가 변경될 때마다 이벤트가 신호를 보냅니다. 애플리케이션은 WaitForSingleObject 또는 WaitForMultipleObjects 를 사용하여 이벤트를 대기할 수 있습니다. 이벤트가 신호를 받으면 WAVEHDR 구조체의 dwFlags 멤버를 확인하여 파형 버퍼의 현재 상태를 가져올 수 있습니다. ( waveOutPrepareHeader를 참조하세요.)

fdwOpen에 CALLBACK_NULL 플래그가 포함된 경우 dwCallback은 NULL이어야 합니다. 이 경우 콜백 메커니즘이 사용되지 않습니다.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	mmeapi.h(Windows.h 포함)
라이브러리	Winmm.lib
DLL	Winmm.dll