ANMIAN

 

    MMRESULT waveInPrepareHeader(HWAVEIN hwi, LPWAVEHDR pwh, UINT cbwh);

 

 

2. 함수의 기능
 
    아날로그 형식의 소리를 녹음할때, 녹음할 준비가 되었음을 드라이버에게 알리는 함수이다.
    따라서 이 함수를 호출하지 않은 상태에서 waveInStart 와 같은 함수를 호출하여 녹음이
    시작되면 녹음이 정상적으로 진행되지 않는다. 즉, waveInStart 함수를 호출하기 전에
    반드시 waveInPrepareHeader 함수를 호출하여 녹음에 필요한 버퍼가 준비되었음을 알려야 한다.

 

3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
    3.2 pwh
 
        소리를 저장할 버퍼의 정보를 포함하고 있는 WAVEHDR 구조체의 주소를 명시한다.
 
    3.3 cbwh
 
        pwh에 명시한 WAVEHDR 구조체의 크기를 명시한다. 일반적으로 sizeof(WAVEHDR)을 명시한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.

 

 

 

    이 함수 호출에 사용되는 WAVEHDR 구조체 정보중 dwFlags, lpData, dwBufferLength 항목의 값은 반드시 설정되어
    있어야 하며, dwFlags의 값은 반드시 0 이여야 한다.

 

 

    // 1. 클래스 멤버로 선언

 

        HANDLE mh_wave_data, mh_wave_header;
        unsigned char *mp_wave_data;
        WAVEHDR *mp_wave_header;
 
    // 2.소스에서 객체 생성자 또는 초기화 루틴에서 사용 (버퍼의 크기를 2205라고 가정)

 

        // 소리 데이터를 녹음할 버퍼를 할당한다.
        mh_wave_data = ::GlobalAlloc(GMEM_MOVEABLE, 2205);
        mp_wave_data = (unsigned char *)::GlobalLock(mh_wave_data);

 

        // WAVEHDR 구조체를 할당한다.
        mh_wave_header = ::GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE, sizeof(WAVEHDR));
        mp_wave_header= (LPWAVEHDR)::GlobalLock(mh_wave_header);

        // WAVEHDR 구조체에 필요한 정보를 설정한다.
        mp_wave_header->lpData = (char *)mp_wave_data;
        mp_wave_header->dwBufferLength = 2205;
        mp_wave_header->dwFlags = 0;
        mp_wave_header->dwLoops = 0;
 
    // 3. waveInOpen 함수를 호출하여 성공적으로 녹음 장치를 열고 해당 장치의 핸들이
    //     mh_wave_in 변수에 저장되어 있다면 아래와 같이 호출하면 된다. 또한 콜백에 의해서
    //     녹음된 데이터를 받은 후, 연속해서 녹음을 하는 경우에도 아래와 같이 호출해야 한다.

 

        waveInPrepareHeader(mh_wave_in, mp_wave_header, sizeof(WAVEHDR));

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    아날로그 형식의 소리를 녹음할때, 사용할 입력 버퍼를 드라이버에게 전달할때 사용한다.
    그리고 드라이버에 의해서 해당 버퍼에 소리 정보가 버퍼의 크기만큼 채워지면 콜백 기능을
    통해서 응용 프로그램에게 다시 되돌아 온다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
    3.2 pwh
 
        소리를 저장할 버퍼의 정보를 포함하고 있는 WAVEHDR 구조체의 주소를 명시한다.
 
    3.3 cbwh
 
        pwh에 명시한 WAVEHDR 구조체의 크기를 명시한다. 일반적으로 sizeof(WAVEHDR)을 명시한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 MMSYSERR_UNPREPARED - pwh에 명시된 정보가 waveInPrepareHeader 함수 호출을 통해서 준비된
                                                    상태가 아닌 경우에 발생한다.

 

 

    이 함수가 전달한 입력 버퍼에 내용이 채워지면 드라이버에 의해서 WAVEHDR 구조체의 dwFlags 항목에
    WHDR_DONE 값이 설정되는데, 이것은 이 함수의 pwh 항목에 명시된  WAVEHDR 구조체의 dwFlags 항목을
    체크해 보면 알수 있다. 그리고 pwh 항목에 명시되는 버퍼는 이 함수가 호출되기전에 waveInPrepareHeader
    함수를 호출하여 준비되었음을 명시하고 사용해야 한다.
 
 
6. 함수의 사용 예제
 
    // 1. 클래스 멤버로 선언
 
        HANDLE mh_wave_data, mh_wave_header;
        unsigned char *mp_wave_data;
        WAVEHDR *mp_wave_header;
 
    // 2.소스에서 객체 생성자 또는 초기화 루틴에서 사용 (버퍼의 크기를 2205라고 가정)
 
        // 소리 데이터를 녹음할 버퍼를 할당한다.
        mh_wave_data = ::GlobalAlloc(GMEM_MOVEABLE, 2205);
        mp_wave_data = (unsigned char *)::GlobalLock(mh_wave_data);
 
        // WAVEHDR 구조체를 할당한다.
        mh_wave_header = ::GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE, sizeof(WAVEHDR));
        mp_wave_header= (LPWAVEHDR)::GlobalLock(mh_wave_header);

        // WAVEHDR 구조체에 필요한 정보를 설정한다.
        mp_wave_header->lpData = (char *)mp_wave_data;
        mp_wave_header->dwBufferLength = 2205;
        mp_wave_header->dwFlags = 0;
        mp_wave_header->dwLoops = 0;
 
    // 3. waveInOpen 함수를 호출하여 성공적으로 녹음 장치를 열고 해당 장치의 핸들이
    //     mh_wave_in 변수에 저장되어 있다면 아래와 같이 호출하면 된다. 또한 콜백에 의해서
    //     녹음된 데이터를 받은 후, 연속해서 녹음을 하는 경우에도 아래와 같이 호출해야 한다.
 
        waveInPrepareHeader(mh_wave_in, mp_wave_header, sizeof(WAVEHDR));
        waveInAddBuffer(mh_wave_in, mp_wave_header, sizeof(WAVEHDR));

 

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    선택한 녹음 장치를 이용하여 녹음을 시작한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.

 

 

    이 함수에 의해서 녹음이 시작되면 waveInPrepareHeader와 waveInAddBuffer에 의해서 전달된 버퍼에
    내용이 가득 채워지거나 WaveInReset 함수가 호출되면 전달된 버퍼가 콜백 기능을 통해서 응용 프로그램에게
    되돌아 온다. 따라서 녹음된 데이터의 크기가 버퍼의 크기와 일치하지 않을수도 있기 때문에 WAVEHDR 구조체의
    dwBytesRecorded 항목을 체크하여 실제로 얼마만큼의 데이터가 녹음되었는지 확인할 필요가 있다.

 

    녹음을 위해 전달된 버퍼에 데이터가 가득 채워지거나 WaveInReset 함수의 호출로 콜백이 발생하고 응용프로그램에
    녹음된 데이터가 전달되면 응용 프로그램은 해당 데이터를 처리하고 다시 waveInPrepareHeader와 waveInAddBuffer
    함수를 호출하여 추가적으로 녹음에 사용할 버퍼를 드라이버에게 전달해야 한다. 만약, 추가적인 버퍼를 드라이버에게
    전달하지 않으면 드라이버는 그 시간만큼의 데이터를 저장할 공간이 없기 때문에 데이터를 잃어 버리게 된다.
    하지만, 버퍼가 제공되지 않는다고 해서 녹음이 중단되지는 않는다.
 
    waveInStart 함수가 호출되어 녹음이 진행되는데 waveInStart 함수가 호출된다면 해당 함수호출은 의미없는 호출로
    처리될것이다. 그리고 이러한 호출이 발생하면 waveInStart 함수는 0을 반환하게 될것이다.
 

 

6. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    선택한 녹음장치의 녹음을 중단한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.

 

 

    일반적으로 녹음 기능을 구현할때는 원활한 녹음진행을 위해서 버퍼를 두개이상 사용한다. 이러한 경우,
    waveInStop 함수가 호출되어 녹음이 중단되면 드라이버에 의해서 현재 기록되던 버퍼는 완료가 되었다는 정보와
    함게 콜백될 것이다. 하지만  대기하고 있던 버퍼는 응용프로그램에게 다시 되돌아오지 못하고 드라이버에
    그대로 남게 된다. 따라서 드라이버로부터 남은 버퍼를 강제로 반환받기 위해서 waveInReset 함수를 사용해야 한다.

 

    녹음이 중단된 상태이거나 waveInStart 함수를 사용하지 않은 상태에서 waveInStop 함수가 호출되면 의미없는
    호출로 처리될 것이다. 그리고 이러한 호출이 발생하면 waveInStop 함수는 0을 반환하게 될것이다.

 

 

6. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    선택한 녹음장치의 녹음을 중단하고 녹음에 사용되던 정보를 초기화 한다. 그리고 드라이버에게
    녹음을 위해 전달된 데이터 버퍼들 중에서 대기중이던 버퍼를 강제로 반환받는다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.

 

5. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

    녹음 버퍼에 waveInPrepareHeader 함수를 사용했다면 해당 버퍼는 해제되기 전에 반드시 waveInUnprepareHeader

    함수를 호출하여 정리한후에 해제해야 한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
    3.2 pwh
 
        소리를 저장할 버퍼의 정보를 포함하고 있는 WAVEHDR 구조체의 주소를 명시한다.
 
    3.3 cbwh
 
        pwh에 명시한 WAVEHDR 구조체의 크기를 명시한다. 일반적으로 sizeof(WAVEHDR)을 명시한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 WAVERR_STILLPLAYING - 명시한 WAVEHDR 정보가 드라이버에 의해서 사용되고 있는 경우에 발생한다.

 

 

    이 함수는 waveInPrepareHeader 함수와 보완 관계에 있는 함수이기 때문에 전체 진행으로 봤을때
    항상 쌍으로 호출되어야 한다. 그리고 waveInPrepareHeader 함수를 사용하지 않은 녹음 버퍼를
    waveInUnprepareHeader 함수에 적용한 경우에는 의미없는 호출로 처리되고 이 함수는 0을 반환한다.

 

 

 

    // 녹음을 안정적으로 하기 위해서 버퍼를 4개 사용한다고 가정한다.

    HWAVEIN mh_wave_in; // waveInOpen에 의해서 얻은 녹음 장치 핸들이 들어있다고 가정한다.

    WAVEHDR *mp_mp_wave_header[4]; // 녹음에 사용할 버퍼의 정보를 담고있다고 가정한다.

 

    MMRESULT error_code = 0;

    // 녹음을 중단한다.
    waveInStop(mh_wave_in);

    // waveInPrepareHeader에 의해서 전송된 데이터를 waveInUnprepareHeader 할수 있는
    // 상태로 만들어 주기 위해서 waveInReset 함수를 호출한다. 이 함수를 호출하지 않으면
    // 드라이버상에 대기중인 녹음버퍼가 waveInUnprepareHeader 함수 호출시 오류가 발생할수 있다.
    waveInReset(mh_wave_in);

 

    // 웨이브 데이터를 저장하기 위해서 생성한 버퍼들을 제거하기 위해서는 해당 버퍼가
    // waveInPrepareHeader 된 상태라면 waveInUnprepareHeader 시켜주어야 한다.
    // waveInPrepareHeader 상태의 버퍼를 waveInUnprepareHeader 하지 않고 제거하면 오류가 발생한다.
    for(int i = 0; i < 4; i++){
        error_code = waveInUnprepareHeader(mh_wave_in, mp_wave_header[i], sizeof(WAVEHDR));
        if(error_code != MMSYSERR_NOERROR){

            // 오류에 대한 처리를 한다.

        }
    }

    // 사운드 입력 장치를 닫는다.
    error_code = waveInClose(mh_wave_in);

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

3. 함수의 매개변수에 대한 설명
 
    3.1 hwi
 
        녹음장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveInOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 WAVERR_STILLPLAYING - 명시한 WAVEHDR 정보가 드라이버에 의해서 사용되고 있는 경우에 발생한다.

 

 

    응용프로그림이 waveInAddBuffer 함수를 호출하여 드라이버에게 녹음 버퍼를 전달한 상태에서 waveInClose
    함수를 호출하면 이 함수는 실패할 것이다. 따라서 이 함수를 사용하기전에 드라이버에 의해서 녹음되어지고
    있거나 대기중인 버퍼들은 waveInStop과 waveInReset 함수를 사용하여 모두 반환시켜야 할것이다.

 

6. 함수의 사용 예제
 
    // 녹음을 안정적으로 하기 위해서 버퍼를 4개 사용한다고 가정한다.
    HWAVEIN mh_wave_in; // waveInOpen에 의해서 얻은 녹음 장치 핸들이 들어있다고 가정한다.
    WAVEHDR *mp_mp_wave_header[4]; // 녹음에 사용할 버퍼의 정보를 담고있다고 가정한다.
 
    MMRESULT error_code = 0;
    // 녹음을 중단한다.
    waveInStop(mh_wave_in);

    // waveInPrepareHeader에 의해서 전송된 데이터를 waveInUnprepareHeader 할수 있는
    // 상태로 만들어 주기 위해서 waveInReset 함수를 호출한다. 이 함수를 호출하지 않으면
    // 드라이버상에 대기중인 녹음버퍼가 waveInUnprepareHeader 함수 호출시 오류가 발생할수 있다.
    waveInReset(mh_wave_in);
 
    // 웨이브 데이터를 저장하기 위해서 생성한 버퍼들을 제거하기 위해서는 해당 버퍼가
    // waveInPrepareHeader 된 상태라면 waveInUnprepareHeader 시켜주어야 한다.
    // waveInPrepareHeader 상태의 버퍼를 waveInUnprepareHeader 하지 않고 제거하면 오류가 발생한다.
    for(int i = 0; i < 4; i++){
        error_code = waveInUnprepareHeader(mh_wave_in, mp_wave_header[i], sizeof(WAVEHDR));
        if(error_code != MMSYSERR_NOERROR){
            // 오류에 대한 처리를 한다.
        }
    }
    // 사운드 입력 장치를 닫는다.
    error_code = waveInClose(mh_wave_in);

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

 

    2.1 Message ID : MM_WOM_DONE

 

    2.2 wParam - 재생장치의 핸들 값이 들어있다. 사용하고 싶다면 아래와 같이 형변환을 시켜서 사용하면 된다.
                          HWAVEOUT h_output = (HWAVEOUT)wParam;

 

    2.3 lParam - 재생버퍼의 정보를 담고 있는 WAVEHDR 구조체 형식의 주소가 들어있다. 현재 재생이 완료된
                         정보를 체크해볼 필요가 있다면 아래와 같이 코드를 구성하면 된다.
                         WAVEHDR *p_wave_out_header = (WAVEHDR *)lParam;
                         // p_wave_out_header->....
 

 

3. 메시지의 반환 값
 
    이 메시지는 특별한 값을 반환하지 않는다.

 

 

4. 구조체의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.

   

 

    2.1 Message ID : MM_WIM_DATA

 

    2.2 wParam - 녹음장치의 핸들 값이 들어있다. 사용하고 싶다면 아래와 같이 형변환을 시켜서 사용하면 된다.
                          HWAVEIN h_input = (HWAVEIN)wParam;

 

    2.3 lParam - 녹음버퍼의 정보를 담고 있는 WAVEHDR 구조체 형식의 주소가 들어있다. 현재 녹음이 완료된
                         정보를 체크해볼 필요가 있다면 아래와 같이 코드를 구성하면 된다.
                         WAVEHDR *p_wave_in_header = (WAVEHDR *)lParam;
                         // p_wave_in_header->....

 

 

3. 메시지의 반환 값
 
    이 메시지는 특별한 값을 반환하지 않는다.

 

 

    녹음버퍼가 응용프로그램으로 반환되는 조건이 녹음버퍼가 가득찼을때 이외에도 waveInReset 함수를
    호출하는 경우도 있기 때문에 녹음버퍼가 가득차지 않은 상태에서 반환되었을수도 있다. 따라서
    MM_WIM_DATA 메시지 처리루틴에서는 자신이 지정한 버퍼의 크기만큼 데이터를 처리하지 말고
    lParam에 전달되는 WAVEHDR 구조체 형식의 정보를 확인해서 실제로 녹음된 양만큼 처리해야 한다.
    실제로 녹음된 데이터 크기를 확인하려면 아래와 같이 코드를 구성하면 된다.

 

    WAVEHDR *p_wave_in_header = (WAVEHDR *)lParam;
    int record_size = p_wave_in_header->dwBytesRecorded; // 실제로 녹음된 크기

 

5. 구조체의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.

 

2. 함수의 기능
 
    아날로그 형식의 소리를 재생할때, 재생장치에 대한 핸들을 얻기 위해 이 함수를 사용한다.
  
 
3. 함수의 매개변수에 대한 설명
 
    3.1 phwo
 
        재생장치에 대한 핸들값이 저장될 변수의 주소를 명시한다. 이 함수가 정상적으로 수행을
        했다면 재생을 위해 사용될 함수들은 모두 이 핸들 값을 기준으로  동작할 것이다.
 
        HWAVEOUT h_output;
        WaveOutOpen(&h_output, ....(생략)....);
 
        fdwOpen 항목에 WAVE_FORMAT_QUERY가 명시되었다면 이 항목(phwi)의 값은  NULL일 것이다.
 
    3.2 uDeviceID
 
        사용할 재생 장치의 식별자(identifier)를 명시한다. 식별자는 장치의 고유 식별자이거나 이미
        사용되고 있는 재생 장치의 핸들일수 있다. 일반적으로 식별자를 사용하는것이 어렵기 때문에
        쉽게 사용할수 있도록 장치 식별자 대신에 WAVE_MAPPER라는 값을 사용한다.
        WAVE_MAPPER 값을 명시하면 이 함수가 조건에 맞는 재생 장치를 찾아 해당 장치의 고유
        식별자를 사용한다. 따라서 대부분의 경우, WAVE_MAPPER를 사용한다.
 
        HWAVEOUT h_output;
        WaveOutOpen(&h_output, WAVE_MAPPER, ....(생략)....);
 
    3.3 pwfx
 
        재생할 소리 데이터 형식을 저장한 WAVEFORMATEX 구조체의 주소를 명시한다.
        예를 들어, WAVE_FORMAT_PCM 형식으로 11.025 kHz, 8 Bits, 모노방식으로 재생하기
        원한다면 아래와 같이 WAVEFORMATEX 구조체 값을 구성하고 전달하면 된다.
 
        WAVEFORMATEX  my_wave_format;
 
        my_wave_format.wFormatTag = WAVE_FORMAT_PCM;
        my_wave_format.nChannels = 1;                      // 재생에 사용할 채널수 :  1 - 모노,  2 - 스테레오
        my_wave_format.nSamplesPerSec = 11025;    // 샘플링 주기 : 11.025 KHz
        my_wave_format.wBitsPerSample = 8;             // 샘플링 단위 : 8 Bits
        my_wave_format.nBlockAlign = my_wave_format.nChannels*my_wave_format.wBitsPerSample/8;
        my_wave_format.nAvgBytesPerSec = my_wave_format.nSamplesPerSec*my_wave_format.nBlockAlign;
        my_wave_format.cbSize = 0;                            // WAVEFORMATEX 구조체 정보외에 추가적인 정보가 없다.
 
        HWAVEOUT h_output;
        WaveOutOpen(&h_output, WAVE_MAPPER,  &my_wave_format, ....(생략)....);
 
    3.4 dwCallback
 
        재생되는 데이터를 실제로 처리할 콜백 함수의 주소, 이벤트 핸들, 윈도우 핸들 또는 스레드 식별자를
        명시한다. 사용자가 지정한 재생버퍼에 대하여 재생장치가 재생을 완료하면 자동으로 이 콜백 기능이 수행된다.
        예를 들어, 사용자가 재생공간을 2205 bytes로 지정하고 해당 크기만큼 재생 데이터를 복사한 다음, 재생장치로
        전달하게 되면 재생장치가 2205 bytes만큼 재생한후에 해당 윈도우로 MM_WOM_DONE 메시지를 전달할 것이다.
 
        WAVEFORMATEX  my_wave_format;
        // my_wave_format에 값을 설정하는것은 3.3 항목 참조
 
        HWAVEOUT h_output;
        WaveOutOpen(&h_output, WAVE_MAPPER,  &my_wave_format, (DWORD)m_hWnd, ....(생략)....);
 
        위와 같이 호출하면 재생장치에 전달한 재생버퍼가 재생완료되면 m_hWnd에 해당하는 윈도우로
        MM_WOM_DONE 메시지가 발생한다.  만약, 콜백기능을 사용하지 않는다면 0을 명시하면 되고 콜백함수를
        사용하는 경우에는 waveOutProc 함수를 참고하길 바란다.
 
    3.5 dwCallbackInstance
 
        콜백 함수와 같은 콜백 기술을 사용하는 경우, 함수의 인자로 전달된 사용자 데이터를 명시한다. 하지만
        윈도우 핸들을 명시하여 메시지로 콜백되는 경우에는 사용되지 않는다. 따라서 윈도우 콜백 방식일때는
        NULL을 명시하면 된다.
 
        WAVEFORMATEX  my_wave_format;
        // my_wave_format에 값을 설정하는것은 3.3 항목 참조
 
        HWAVEOUT h_output;
        WaveOutOpen(&h_output, WAVE_MAPPER, &my_wave_format, (DWORD)m_hWnd,
                                                                                      (DWORD)NULL, (DWORD)CALLBACK_WINDOW);
 
    3.6 fdwOpen
 
        장치를 사용할 형식에 대한 값을 명시한다. 사용 가능한 값의 목록은 아래와 같다.
 
        3.6.1 CALLBACK_EVENT - dwCallback 항목에 이벤트 핸들을 사용할 것이다.
        3.6.2 CALLBACK_FUNCTION - dwCallback 항목에 콜백 함수의 주소를 사용할 것이다.
        3.6.3 CALLBACK_NULL - 어떠한 콜백 기술도 사용하지 않는다.
        3.6.4 CALLBACK_THREAD - dwCallback 항목에 스레드 식별자를 사용할 것이다.
        3.6.5 CALLBACK_WINDOW - dwCallback 항목에 윈도우 핸들을 사용할 것이다.
 
        3.6.6 WAVE_ALLOWSYNC - 이 값이 설정되면 동시성을 지원하는 형태로 재생 장치를 사용할수 있다.
                                                     하지만, 이렇게 재생 장치가 사용되는 경우, 다른 프로그램에서 이 값을
                                                     설정하지 않고 해당 재생 장치를 사용하려고 하면 waveOutOpen 함수가
                                                     실패할 것이다.
        3.6.7 WAVE_FORMAT_DIRECT - ACM 드라이버는 소리데이터 변환 작업을 수행하지 않는다.
        3.6.8 WAVE_FORMAT_QUERY - 실제로 장치를 사용할 목적이 아니라 사용자가 지정한 형식이
                                                            현 시스템에서 제공되는지 체크할때 사용한다.
        3.6.9 WAVE_MAPPED - uDeviceID 항목에 웨이브 맵퍼에서 설정한 장치를 명시한 경우, 이 값을
                                              사용한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_ALLOCATED - 명시된 장치를 다른 프로세스가 사용중인 경우에 발생한다.
    4.2 MMSYSERR_BADDEVICEID - 명시된 장치의 식별자가 유효범위를 벗어난 경우에 발생한다.
    4.3 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.4 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.5 WAVERR_BADFORMAT - 제공하지 않는 소리 형식을 명시한 경우에 발생한다.
    4.6 WAVERR_SYNC - uDeviceID 항목에 명시한 장치가 동시성 형식으로 사용되고 있는데,
                                       fdwOpen 항목에 WAVE_ALLOWSYNC 값을설정하지 않고 waveOutOpen 함수를
                                       사용한 경우 발생한다.

 

 

5. 함수 사용시 주의사항
 
    현 시스템에 재생 가능한 장치의 수를 알고 싶다면 waveOutGetNumDevs 함수를 사용하면 된다.
    waveOutGetNumDevs 함수가 3을 반환했다면 uDeviceID에 사용가능한 값은 0, 1, 2 중에 하나이다.
    WAVE_MAPPER라고 명시한 경우에는 위 범위 규칙을 따르지 않는다.
 
    만약, 스레드 또는 윈도우 콜백 방식을 사용한다면 해당 스레드나 윈도우로 MM_WOM_OPEN,
    MM_WOM_CLOSE, MM_WOM_DONE와 같은 메시지가 전달될 것이다.
 
    만약, 콜백 함수를 사용한다면 함수가 호출될때 WOM_OPEN, WOM_CLOSE, WOM_DONE와 같은
    구별값이 함수의 인자를 통해 전달될것이다.

 

6. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 
2. 함수의 기능
 
    아날로그 형식의 소리를 재생할때, 재생할 준비가 되었음을 드라이버에게 알리는 함수이다.
    따라서 이 함수를 호출하지 않은 상태에서 waveOutWrite 와 같은 함수를 호출하여 재생이
    시작되면 재생이 정상적으로 진행되지 않는다. 즉, waveOutWrite 함수를 호출하기 전에
    반드시 waveOutPrepareHeader 함수를 호출하여 재생에 필요한 데이터가 준비되었음을 알려야 한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwo
 
        재생장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveOutOpen 함수를 호출하여 얻을수 있다.
 
    3.2 pwh
 
        재생할 소리 정보가 저장된 버퍼의 정보를 포함하고 있는 WAVEHDR 구조체의 주소를 명시한다.
 
    3.3 cbwh
 
        pwh에 명시한 WAVEHDR 구조체의 크기를 명시한다. 일반적으로 sizeof(WAVEHDR)을 명시한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwi 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.

 
5. 함수 사용시 주의사항
 
    이 함수 호출에 사용되는 WAVEHDR 구조체 정보중 dwFlags, lpData, dwBufferLength 항목의 값은 반드시 설정되어
    있어야 하며, dwFlags의 값은 반드시 WHDR_PREPARED, WHDR_BEGINLOOP 또는 WHDR_ENDLOOP 중에
    한개 이상을 명시해야 한다.
 
    waveOutPrepareHeader 함수가 호출되고 waveOutWirte 함수가 호출되는 그 사이에 WAVEHDR 구조체의
    dwFlags, dwBufferLength, dwLoops 항목을 변경할수도 있다. 하지만 dwBufferLength 값을 변경하는 경우에는
    변경할 값이 이전에 명시한 값보다 작아야만 한다.

 

6. 함수의 사용 예제
 
    // 1. 클래스 멤버로 선언
 
        HANDLE mh_wave_data, mh_wave_header;
        unsigned char *mp_wave_data;
        WAVEHDR *mp_wave_header;
 
    // 2.소스에서 객체 생성자 또는 초기화 루틴에서 사용 (버퍼의 크기를 2205라고 가정)
 
        // 소리 데이터를 재생할 버퍼를 할당한다.
        mh_wave_data = ::GlobalAlloc(GMEM_MOVEABLE, 2205);
        mp_wave_data = (unsigned char *)::GlobalLock(mh_wave_data);
        // mp_wave_data에 재생할 소리데이터를 복사해야 함.

        // WAVEHDR 구조체를 할당한다.
        mh_wave_header = ::GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE, sizeof(WAVEHDR));
        mp_wave_header= (LPWAVEHDR)::GlobalLock(mh_wave_header);

 

        // WAVEHDR 구조체에 필요한 정보를 설정한다.
        mp_wave_header->lpData = (char *)mp_wave_data;
        mp_wave_header->dwBufferLength = 2205;
        mp_wave_header->dwFlags = WHDR_PREPARED;
        mp_wave_header->dwLoops = 0;
 
    // 3. waveOutOpen 함수를 호출하여 성공적으로 재생 장치를 열고 해당 장치의 핸들이
    //     mh_wave_out 변수에 저장되어 있다면 아래와 같이 호출하면 된다. 또한 콜백에 의해서
    //     재생완료 정보를 받은 후, 연속해서 재생을 하는 경우에도 아래와 같이 호출해야 한다.
 
        waveOutPrepareHeader(mh_wave_out, mp_wave_header, sizeof(WAVEHDR));

 

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    아날로그 형식의 소리를 재생할때, 출력할 소리 데이터가 저장된 버퍼를 드라이버에게 전달할때
    사용한다. 이 버퍼는 재생이 완료된후, 응용프로그램으로 반환된다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwo
 
        재생장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveOutOpen 함수를 호출하여 얻을수 있다.
 
    3.2 pwh
 
        재생할 소리 데이터 버퍼의 정보를 포함하고 있는 WAVEHDR 구조체의 주소를 명시한다.
 
    3.3 cbwh
 
        pwh에 명시한 WAVEHDR 구조체의 크기를 명시한다. 일반적으로 sizeof(WAVEHDR)을 명시한다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwo 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 MMSYSERR_UNPREPARED - pwh에 명시된 정보가 waveInPrepareHeader 함수 호출을 통해서 준비된
                                                    상태가 아닌 경우에 발생한다.
 
 
5. 함수 사용시 주의사항
 
    이 함수가 전달한 재생 버퍼에 내용이 모두 재생되면 드라이버에 의해서 WAVEHDR 구조체의
    dwFlags 항목에 WHDR_DONE 값이 설정되는데, 이것은 이 함수의 pwh 항목에 명시된  WAVEHDR 구조체의
    dwFlags 항목을 체크해 보면 알수 있다.

    그리고 pwh 항목에 명시되는 버퍼는 이 함수가 호출되기전에 waveOutPrepareHeader 함수를 호출하여
    준비되었음을 명시하고 사용해야 한다.

 

    예외적으로, waveOutWirte 함수를 호출하기전에 waveOutPause 함수를 호출하였다면 waveOutWrite 함수가
    호출되어 재생정보가 드라이버로 전달되더라도 재생은 시작되지 않을 것이다.
 
 
6. 함수의 사용 예제
 
    // 1. 클래스 멤버로 선언
 
        HANDLE mh_wave_data, mh_wave_header;
        unsigned char *mp_wave_data;
        WAVEHDR *mp_wave_header;
 
    // 2.소스에서 객체 생성자 또는 초기화 루틴에서 사용 (버퍼의 크기를 2205라고 가정)
 
        // 소리 데이터를 재생할 버퍼를 할당한다.
        mh_wave_data = ::GlobalAlloc(GMEM_MOVEABLE, 2205);
        mp_wave_data = (unsigned char *)::GlobalLock(mh_wave_data);
        // mp_wave_data에 재생할 소리데이터를 복사해야 함.

 

        // WAVEHDR 구조체를 할당한다.
        mh_wave_header = ::GlobalAlloc(GMEM_MOVEABLE | GMEM_SHARE, sizeof(WAVEHDR));
        mp_wave_header= (LPWAVEHDR)::GlobalLock(mh_wave_header);

        // WAVEHDR 구조체에 필요한 정보를 설정한다.
        mp_wave_header->lpData = (char *)mp_wave_data;
        mp_wave_header->dwBufferLength = 2205;
        mp_wave_header->dwFlags = WHDR_PREPARED;
        mp_wave_header->dwLoops = 0;
 
    // 3. waveOutOpen 함수를 호출하여 성공적으로 재생 장치를 열고 해당 장치의 핸들이
    //     mh_wave_out 변수에 저장되어 있다면 아래와 같이 호출하면 된다. 또한 콜백에 의해서
    //     재생완료 정보를 받은 후, 연속해서 재생을 하는 경우에도 아래와 같이 호출해야 한다.
 
        waveOutPrepareHeader(mh_wave_out, mp_wave_header, sizeof(WAVEHDR));
        waveOutWrite(mh_wave_out, mp_wave_header, sizeof(WAVEHDR));

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

2. 함수의 기능
 
    이 함수는 소리를 재생하다가 잠시 재생을 중단시킬때 사용한다. 이렇게 중단되는 경우,
    재생되고 있던 위치가 유지되기 때문에 waveOutRestart 함수를 사용하여 다시 재생을 시키면
    중단되었던 위치부터 소리가 재생될 것이다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwo
 
        재생장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveOutOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwo에 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 MMSYSERR_NOTSUPPORTED - hwo에 명시된 장치가 동시성 기능을 사용하고 있거나
                                                              일시정지 기능을 제공하지 않는 경우에 발생한다.
 
 
5. 함수 사용시 주의사항
 
    이미 재생이 중단된 상태에서 이 함수를 호출하면 의미없는 호출로 간주하고 0 값을 반환한다.
 
 
6. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

 

2. 함수의 기능
 
    이 함수는 waveOutPause 함수를 사용하여 잠시 중단했던 재생을 다시 시작할때 사용한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwo
 
        재생장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveOutOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwo에 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 MMSYSERR_NOTSUPPORTED - hwo에 명시된 장치가 동시성 기능을 사용하고 있거나
                                                              일시정지 기능을 제공하지 않는 경우에 발생한다.
 
 
5. 함수 사용시 주의사항
 
    재생이 중단되지 않고 진행중인 상태에서 이 함수를 호출하면 의미없는 호출로 간주하고 0 값을 반환한다.
 
 
6. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.

 

2. 함수의 기능
 
    이 함수는 재생에 사용하던 닫을때 사용한다.
 
 
3. 함수의 매개변수에 대한 설명
 
    3.1 hwo
 
        재생장치에 대한 핸들값을 명시한다. 이 핸들값은 WaveOutOpen 함수를 호출하여 얻을수 있다.
 
 
4. 함수의 반환값
   
    이 함수가 성공적으로 수행 되었다면 MMSYSERR_NOERROR 값을 반환한다. 만약 오류가
    발생했다면 아래의 값이 반환될 것이다.
 
    4.1 MMSYSERR_INVALHANDLE - hwo에 명시된 장치 핸들이 유효하지 않는 경우에 발생한다.
    4.2 MMSYSERR_NODRIVER - 장치 드라이버가 존재하지 않는 경우에 발생한다.
    4.3 MMSYSERR_NOMEM - 메모리를 할당할수 없거나 메모리에 접근할수 없을때 발생한다.
    4.4 WAVERR_STILLPLAYING - 명시한 WAVEHDR 정보가 드라이버에 의해서 사용되고 있는 경우에 발생한다.

 

5. 함수의 주의사항
 
    재생장치가 재생을 진행중인 상태에서 waveOutClose 함수를 호출하면 장치 닫기에 실패할 것이다. 따라서 재생중인
    장치를 안전하게 닫으려면 waveOutReset 함수를 호출하여 재생을 중단시킨 후, waveOutClose 함수를 호출하여
    장치를 닫으면 된다.
 

 

6. 함수의 사용 예제
 
    // 재생을 안정적으로 하기 위해서 재생 버퍼를 4개 사용한다고 가정한다.
    HWAVEOUT mh_wave_out; // waveOutOpen에 의해서 얻은 재생 장치 핸들이 들어있다고 가정한다.
    WAVEHDR *mp_mp_wave_header[4]; // 재생에 사용할 버퍼의 정보를 담고있다고 가정한다.
 
    // 재생을 중지한다.
    MMRESULT error_code = waveOutPause(mh_wave_out);
    if(error_code == MMSYSERR_NOERROR){
        // waveOutPrepareHeader에 의해서 전송된 데이터를 waveOutUnprepareHeader 할수 있는
        // 상태로 만들어 주기 위해서 waveOutReset 함수를 호출한다. 이 함수를 호출하지 않으면
        // waveOutUnprepareHeader 함수 호출시 오류가 발생할수 있다.
        waveOutReset(mh_wave_out);
        for(int i = 0; i < 4; i++) waveOutUnprepareHeader(mh_wave_out, mp_wave_header[i], sizeof(WAVEHDR));
        // 출력 장치를 닫는다.
        waveOutClose(mh_wave_out);
    }

 

7. 함수의 요구사항
 
    Window NT/2000/XP: Included in Windows NT 3.1 and later.
    Windows 95/98/Me: Included in Windows 95 and Later.
    Header: Declared in Mmsystem.h; include Windows.h.
    Library: Use Winmm.lib.