Windows多媒体API -低阶（一）

在 windows中，API 支持的多媒体功能主要分成两个集合：低阶和高阶 介面；

低阶介面是一系列函式，这些函式以简短的说明性字首开头，而且在/Platform SDK/Graphics and Multimedia Services/Multimedia Reference/Multimedia Functions（与高阶函式一起）中列出。

低阶的波形声音输入输出函式的字首是waveIn 和waveOut。

midiOut函式控制MIDI 输出设备。

字首为time 的函式，这些函式允许设定一个高解析度的计时器常式，其计时器的时间间隔速率最低能够到1 毫秒。此程式主要用于播放MIDI音乐。其他几组函式包括声音压缩、视讯压缩以及动画和视讯序列。

多媒体函式列表中七个带有字首mci 的函式，它们允许存取媒体控制介面（MCI：Media Control Interface）。这是一个高阶的开放介面，用于控制多媒体PC 中所有的多媒体硬体。MCI 包括所有多媒体硬体都共有的许多命令，因为多媒体的许多方面都以磁带答录机这类设备播放/记录方式为模型。您为输入或输出而「打开」一台设备，进而可以「录音」（对于输入）或者「播放」（对于输出），并且结束后可以「关闭」设备。

MCI 本身分为两种形式。一种形式下，可以向MCI 发送讯息，这类似于

Windows讯息。这些讯息包括位元编码标记和C 资料结构。另一种形式下，可以

向MCI 发送文字字串。这个程式主要用于描述命令语言，此语言具有灵活的字

串处理函式，但支持呼叫Windows API 的函式不多。

MessageBeep 和PlaySound这两个高阶介面多媒体函数，。MessageBeep播放「控制台」的「声音」中指定的声音。PlaySound可播放磁碟上、记忆体中或者作为资源载入的.WAV 档案。

存取多媒体硬体的另一种方法包括DirectX API，过于复杂。

录音：

waveInOpen -> waveInPrepareHeader -> waveInAddBuffer -> waveInStart -> waveInStop -> waveInReset ->waveInUnprepareHeader -> waveInClose

录音的回调函数只需要处理WIM_DATA消息，拷贝数据及重新调用waveInAddBuffer将此缓存加入队列。

放音：

waveOutOpen -> waveOutPrepareHeader -> waveOutWrite -> waveOutReset -> waveOutUnprepareHeader -> waveOutClose

1.1         WAVEFORMATEX

WAVEFORMATEX 为波形音频流格式的数据结构

typedef struct tWAVEFORMATEX

{

      WORD            wFormatTag;           

      WORD            nChannels;              

      DWORD          nSamplesPerSec;     

      DWORD          nAvgBytesPerSec;     

      WORD            nBlockAlign;           

      WORD            wBitsPerSample;     

      WORD            cbSize;                 

                                                    

} WAVEFORMATEX, *PWAVEFORMATEX, NEAR *NPWAVEFORMATEX, FAR *LPWAVEFORMATEX;

wFormatTag：设置波形声音的格式

nChannels：设置音频文件的通道数量，对于单声道的声音，此此值为1。对于立体声，此值为2.

nSamplesPerSec：设置每个声道播放和记录时的样本频率。如果wFormatTag= WAVE_FORMAT_PCM，那么nSamplesPerSec通常为8.0 kHz， 11.025 kHz， 22.05 kHz和44.1 kHz。例如对于采样率为11.025 kHz的音频，nSamplesPerSec将被设为11025。对于非PCM格式的，根据厂商的设定计算。

nAvgBytesPerSec：设置请求的平均数据传输率，单位byte/s。这个值对于创建缓冲大小是很有用的。

nBlockAlign：以字节为单位设置块对齐。块对齐是指最小数据的原子大小。如果wFormatTag= WAVE_FORMAT_PCM，nBlockAlign为(nChannels*wBitsPerSample)/8。对于非PCM格式根据厂商的说明计算。

wBitsPerSample：根据wFormatTag的类型设置每个样本的位深（即每次采样样本的大小，以bit为单位）。如果wFormatTag= WAVE_FORMAT_PCM，此值应该设为8或16，对于非PCM格式，根据厂商的说明设置。一些压缩的架构不能设置此值，此时wBitsPerSample应该为零。

cbSize：额外信息的大小，以字节为单位，额外信息添加在WAVEFORMATEX结构的结尾。这个信息可以作为非PCM格式的wFormatTag额外属性，如果wFormatTag不需要额外的信息，此值必需为0，对于PCM格式此值被忽略。

1.2         WAVEHDR-音频数据块缓存结构

其声明如下：  

type struct{

LPSTR lpData;                          

DWORD dwBufferLength;              

DWORD dwBytesRecorded;              

DWORD dwUser;                          

DWORD dwFlag;                          

DWORD dwLoops;                       

struct wavehdr_tag *lpNext;     

DWORD reserved;                       

} WAVEHDR;

dwFlags

Flags supplying information about the buffer. The following values are defined:

WHDR_BEGINLOOP

This buffer is the first buffer in a loop. This flag is used only with output buffers.

WHDR_DONE

Set by the device driver to indicate that it is finished with the buffer and is returning it to the application.

WHDR_ENDLOOP

This buffer is the last buffer in a loop. This flag is used only with output buffers.

WHDR_INQUEUE

Set by Windows to indicate that the buffer is queued for playback.

WHDR_PREPARED

Set by Windows to indicate that the buffer has been prepared with the waveInPrepareHeader or waveOutPrepareHeader function.

1.3         WAVEOUTOPEN

MMRESULT waveOutOpen(

  LPHWAVEOUT         phwo,                       

  UINT_PTR            uDeviceID,                 

  LPWAVEFORMATEX pwfx,                          

  DWORD_PTR          dwCallback,              

  DWORD_PTR          dwCallbackInstance,  

  DWORD                fdwOpen                    

);

参数介绍(paramters)：

phwo

一个指向接收波形音频输出装置柄的缓冲器。用柄来区别（identify）装置当呼叫别的波形装置输出装置。如果fdwOpen被设定为 WAVE_FORMAT_QUERY,那么这个参数可能为NULL 。

uDevideID

将要被打开的波形音频输出装置的ID ，它可以是一个装置ID，也可以是一个已经打开的波形音频输入装置柄，你可以用以下的值来货替：

值                                              含义

WAVE_MAPPER            该函数选一个能够播放给定格式的波形音频输出装置

pwfx

一个指向区别将被送到装置的音频数据格式的WAVEFORMATEX结构的指针，你可以FREE这个结构当你一将其传到waveOutOpen 函数；

dwCallback

它指向一个特定的CALLBACK函数，事件柄，窗口柄，或一个将在波形音频回放时以便处理与回放进度相关的消息的期间呼叫的线程ID,如果无须CALLBACK函数，可以将其设为0 。

dwCallbackInstance

传递到CALLBACK进程的用户实例数据。如果是窗口CALLBACK进程的话，该参数不用（设为0）

 

fwOpen

用来打开装置的标识（FLAGS），它们的定义如下：

值                                                         含义

CALLBACK_EVENT               dwCallback 参数栏是事件柄

CALLBACK_FUNCTION      dwCallback 参数栏是CALLBACK过程地址

CALLBACK_NULL                   默认的设置，即无CALLBACK进程

CALLBACK_THREAD          dwCallback 参数栏是线程ID

CALLBACK_WINDOW         dwCallback 参数栏是窗口柄

WAVE_ALLOWSYNC            如果该项被设置，一个同步的装置能被打开。如果在打开一个同步驱动时没有用该项，装置打开将会失败。

WAVE_FORMAT_DIRECT    如果设定该项，the ACM driver does not perform conversions on the audio data.

WAVE_FORMAT_QUERY    如果设定该项，waveOutOpen 询问装置来决定是否支持给定的格式，但装置实际上并没有被打开。

WAVE_MAPPED      该项被设定后uDeviceID参数表示一个被声波映射装置映射的波形装置。

返回值：

成功后返回MMSYSERR_NOERROR ，否则返回以下值：

值                                                                     描述

MMSYSERR_ALLOCATED          表示资源已存在

MMSYSERR_BADDEVICEID       装置ID超出范围

MMSYSERR_NODRIVER               没有驱动

MMSYSERR_NOMEM                     不能分配内存

WAVERR_BADFORMAT               企图打开一个不被支持的格式

WAVERR_SYNC                                 装置是可同步的，但waveOutOpen没用有WAVE_ALLOWSYNC呼叫。

注：

用waveOutGetNumDevs函数测定在当前系统中输出装置的数目。如果uDeviceIC参数项是一个装置ID，它将会表示从0 到总的数目，WAAVE_MAPPER常量也可以用作装置ID。pwfc所指的结构能够扩展到包含某些数据格式的特殊信息，例如，对于PCM数据，一个额外的UNIT类型用来表示取样的位数目。在这个情况下用PCMWAVEFORAMT结构。对于其它的格式，用WAVEFORMATEX结构来表示额外的数据长度。如果你选用的是一个窗口或线程来接收CALLBACK信息，如下的信息将会被送到窗口处理函数中，来表明波形音频输出进程：MM_WOM_OPEN，MM_WOM_CLOSE ，和MM_WOM_DONE，如果你选用的是一个函数来接收CALLBACK信息，如下的信息将会被传到函数中，来显示波形音频输出进程：WOM_OPEN ，WOM_CLOSE，WOM_DONE。

1.4         WAVEOUTPREPAREHEADER

//声明:

waveOutPrepareHeader(

   hWaveOut: HWAVEOUT;       {设备句柄}

   lpWaveOutHdr: PWaveHdr; {TWaveHdr 结构的指针}

   uSize: UINT                   {TWaveHdr 结构大小}  

): MMRESULT;                     {成功返回 0; 可能的错误值见下:}

 

MMSYSERR_INVALHANDLE = 5;   {设备句柄无效}

MMSYSERR_NOMEM          = 7;   {不能分配或锁定内存}

MMSYSERR_HANDLEBUSY   = 12; {其他线程正在使用该设备}

 

//TWaveHdr 是 wavehdr_tag 结构的重定义

wavehdr_tag = record

   lpData: PChar;               {指向波形数据缓冲区}

   dwBufferLength: DWORD;   {波形数据缓冲区的长度}

   dwBytesRecorded: DWORD; {若首部用于输入, 指出缓冲区中的数据量}

   dwUser: DWORD;               {指定用户的32位数据}

   dwFlags: DWORD;             {缓冲区标志}

   dwLoops: DWORD;             {循环播放次数, 仅用于输出缓冲区}

   lpNext: PWaveHdr;          {保留}

   reserved: DWORD;            {保留}

end;

 

//TWaveHdr 中的 dwFlags 的可选值:

WHDR_DONE         = $00000001; {设备已使用完缓冲区, 并返回给程序}

WHDR_PREPARED   = $00000002; {waveInPrepareHeader 或 waveOutPrepareHeader 已将缓冲区准备好}

WHDR_BEGINLOOP = $00000004; {缓冲区是循环中的第一个缓冲区, 仅用于输出}

WHDR_ENDLOOP    = $00000008; {缓冲区是循环中的最后一个缓冲区, 仅用于输出}

WHDR_INQUEUE    = $00000010; { reserved for driver }

提示: 必须调用 GlobalAlloc 给 TWaveHdr 和其中的 lpData 指向的缓冲区分配内存(使用 GMEM_MOVEABLE、GMEM_SHARE), 并用 GlobalLock 锁定.

1.5         WAVEOUTWRITE

The waveOutWrite function sends a data block to the given waveform-audio output device.

MMRESULT waveOutWrite(

HWAVEOUT hwo,

LPWAVEHDR pwh,

UINT cbwh

);

Parameters

hwo

Handle to the waveform-audio output device.

pwh

Pointer to a WAVEHDR structure containing information about the data block.

cbwh

Size, in bytes, of the WAVEHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following.

Value

Description

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NODRIVER

No device driver is present.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

WAVERR_UNPREPARED

The data block pointed to by the pwh parameter hasn't been prepared.

Remarks

When the buffer is finished, the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

The buffer must be prepared with the waveOutPrepareHeader function before it is passed to waveOutWrite. Unless the device is paused by calling the waveOutPause function, playback begins when the first data block is sent to the device.