OMCS 开发手册（10）－－语音消息

　　在腾讯微信的功能中，语音消息是非常好用的一个功能，也有许多客户需要在自己的项目/系统中集成这样的功能。OMCS直接提供了对语音消息的支持，使得在自己的项目中实现类似的功能变得非常简单。 OMCS的语音消息功能支持的特性如下：

（1）采集语音消息。

（2）发送语音消息。

（3）接收方触发收到消息的事件。

（4）播放语音消息。

（5）服务端提供接口支持实现离线语音消息。

一. OMCS.Passive.ShortMessages 命名空间

　　在客户端，OMCS.Passive.ShortMessages命名空间提供：IAudioMessageController接口、AudioMessage类、IAudioMessagePlayer组件，通过这三个元素，我们便可以使用OMCS提供的对语音消息功能了。

1. IAudioMessageController

　　语音消息控制器（IAudioMessageController）是客户端使用语音留言功能的入口。

    /// <summary>
    /// 语音消息控制器。
    /// （1）可以采集当前用户麦克风的数据，以构造一个语音消息，并将其发送给目标用户。。   
    /// （2）当收到来自其它用户的语音消息时，将触发AudioMessageReceived事件。 
    /// 注意：当IAudioMessageController完成初始化后，将会持续占用麦克风，直到将IAudioMessageController释放。
    /// </summary>
    public interface IAudioMessageController : IDisposable
    {
        /// <summary>
        /// 当接收到目标用户的语音消息时，触发该事件。
        /// </summary>
        event CbGeneric<AudioMessage> AudioMessageReceived;     

        /// <summary>
        /// 是否已经初始化？
        /// </summary>
        bool Initialized { get; }

        /// <summary>
        /// 是否正在采集？
        /// </summary>
        bool IsCapturing { get; }

        /// <summary>
        /// 语音消息播放器。（在IAudioMessageController初始化后，才可使用。）
        /// </summary>
        IAudioMessagePlayer AudioMessagePlayer{ get; }     

        /// <summary>
        /// 初始化语音消息控制器。
        /// 如果不再使用短信组件，则请调用Dispose方法，以释放对设备的占用。
        /// 调用Dispose方法释放后，可以在需要的时候重新调用Initialize，再次进行初始化。
        /// </summary>
        void Initialize();

        /// <summary>
        /// 开始采集。
        /// </summary>
        void StartCapture();      

        /// <summary>
        /// 结束采集。
        /// </summary>        
        AudioMessage StopCapture();

        /// <summary>
        /// 发送语音消息。发送完毕，该调用才会返回，如果不想阻塞当前线程，可考虑异步调用本方法。
        /// </summary>
        /// <param name="audioMessage">语音消息</param>
        /// <param name="destUserID">接收者ID</param>
        void Send(AudioMessage audioMessage, string destUserID);       
    }

（1）我们可以通过OMCS客户端的核心组件 -- 多媒体管理器IMultimediaManager的AudioMessageController属性获取语音消息控制器的引用。　

（2）在使用语音消息控制器之前，必须先调用其Initialize方法对其进行初始化。

（3）语音消息控制器初始化完成后，随时可以调用StartCapture方法以开始采集语音短信。

（4）当完成语音消息采集时，即调用StopCapture方法，该方法将返回采集得到的AudioMessage对象。

（5）语音短信采集完成后，可以调用Send方法，将其发送给目标用户。

（6）如果目标用户也连接上了OMCS服务器，则对方会触发AudioMessageReceived事件，通过事件参数，就可以拿到语音短信。

（7）得到语音短信后，可以使用IAudioMessageController的AudioMessagePlayer组件来播放语音消息。

2. AudioMessage

　　AudioMessage 封装了一个语音短信，其类图如下所示：

（1）ID 是语音消息编号。该ID在每个客户端实例在运行的过程中是唯一的。（不同的客户端，或客户端重启后，可能会重复）。

（2）AudioList 是语音短信的真正内容，即采集得到的数据，这个数据是使用OMCS内部的格式进行压缩组织的，只能由IAudioMessagePlayer进行播放。

（3）CreateTime 是短信采集的时间。

（4）CreatorID 即发送者的UserID。

（5）SpanInMSecs 是短信的时长，单位：毫秒。

3. IAudioMessagePlayer

IAudioMessagePlayer 用于播放AudioMessage对象，其类图如下所示：

（1）通过IAudioMessageController的AudioMessagePlayer属性，即可得到语音消息播放器对象。（前提是：AudioMessageController完成了初始化）。

（2）调用AudioMessagePlayer的Play方法，即可播放指定的AudioMessage。

（3）如果播放过程中，需要取消播放，则调用Stop方法。

（4）无论是播放完毕，还是取消播放，都会触发PlayFinished事件，事件参数为刚播放的那个AudioMessage。

（5）如果前一个语音消息还未播放完，就调用Play方法播放下一个AudioMessage，则会触发PlayInterrupted事件，事件参数为中断播放的那个AudioMessage。

（6）如果要增大或减小播放的音量，可以设置声音放大系数 MaxAmplifier。

二. 如何实现离线语音消息

　　如果语音消息的接收方不在线，那么，发送的语音短信，他就收不到。那么，如何才能做到当其上线时，把那些漏掉的语音短信再发送给他了？

OMCS服务端提供了接口，来实现类似的离线语音消息的功能。在服务端IMultimediaServer接口中有两个API与此相关：

         /// <summary>
        /// 当不在线的用户收到语音消息时，将触发此事件。参数：语音短信接收者ID - 语音短信发送者ID - AudioMessage
        /// </summary>
        event CbGeneric<string, string, AudioMessage> AudioMessagePostFailed;

        /// <summary>
        /// 发送语音短信给目标用户。
        /// </summary>        
        /// <param name="destUserID">短信的接收者ID</param>
        /// <param name="msg">语音短信</param>
        void SendAudioMessage(string destUserID, AudioMessage msg);