消息与事件
=========================================

    AD140，AD150支持的消息见图《消息列表图》
    
    .. image:: msg_list.png
        :alt: "消息列表图“
        :align: center

    .. centered:: 消息列表图

    AD140，AD150目前支持的事件见下图10.2，事件最多支持64种，系统已经定义的事件如图《已有事件列表图》。事件发生与不发生的状态由两个32位的变量event_buf_L、event_buf_H表示，其中变量的每个位表示一个事件的状态（1：事件发生；0：事件未发生）。当某个事件发生时对应的位将被置1，其它位状态不变。如果用户要增加其它事件可类似定义变量和事件宏，用变量位表示其状态。

    .. image:: event_list.png
        :alt: "已有事件列表图“
        :align: center

    .. centered:: 已有事件列表图

    消息与事件的目录位于：APP/src/common/msg/msg.c、include_lib/msg/msg.h。其中主要的函数有：
        | void event_init(void);
        | void message_init();
        | u32 event2msg_api(u32 event);
        | int post_event(int event);
        | int post_msg(int argc, ...);
        | bool get_event_status(u32 event);
        | int get_msg(int len, int \*msg);
        | void clear_all_message(void);

^^^^^^^^^^^^^^^^^^^^

1 消息与事件使用一般流程
################################
    在开机时先调用event_init()、message_init()对消息系统初始化，主要初始化一些消息列表相关变量及事件状态变量。初始化后有用到消息的地方就可以设置消息或获取消息。
    
        a.开机调用event_init()及message_init()完成对事件和消息的初始化；
    
        b.调用post_event(int event)标记事件，调用post_msg(int argc, ...)标记消息；
    
        c.调用get_msg(int len, int \*msg)获取事件消息或其他消息；

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2 消息与事件函数
################################
    
2.1 void event_init(void)
******************************
    此函数会初始化事件状态信息，将event_buf_L、event_buf_H事件状态清空，这一步一般在开机时进行。

2.2 void message_init()
******************************
    此函数会初始化消息信息，将msg_cbuf结构体消息状态清空，这一步一般在开机时进行。

2.3 u32 event2msg_api(u32 event)
*******************************************
    此函数实现根据事件event信息获取对应的消息信息的功能。

    1、event, 事件编号（事件位置见图《事件消息对照表图》形参部分）可选事件:
        | ①　EVENT_F1A1_END, F1A1文件播放结束事件;
        | ②　EVENT_F1A1_ERR, F1A1文件播放错误事件;
        | ③　EVENT_F1A1_LOOP, F1A1文件播放循环事件;
        | ④　EVENT_F1A2_END, F1A2文件播放结束事件;
        | ⑤　EVENT_F1A2_ERR, F1A2文件播放错误事件;
        | ⑥　EVENT_F1A2_LOOP, F1A2文件播放循环事件;
        | ⑦　EVENT_MIDI_END, MIDI文件播放结束事件;
        | ⑧　EVENT_MIDI_ERR, MIDI文件播放错误事件;
        | ⑨　EVENT_A_END, A文件播放结束事件;
        | ⑩　EVENT_A_ERR, A文件播放错误事件;
        | ⑪　EVENT_A_LOOP, A文件播放循环事件;
        | ⑫　EVENT_MP3_END, MP3文件播放结束事件;
        | ⑬　EVENT_MP3_ERR, MP3文件播放错误事件;
        | ⑭　EVENT_MP3_LOOP, MP3文件播放循环事件;
        | ⑮　EVENT_APP_SW_ACTIVE, APP切换活跃事件;
        | ⑯　NO_EVENT, 无事件发生;

    2、返回值:与事件对应的消息信息；
    | 事件与消息对照表如下图《事件消息对照表图》

    .. image:: event2msg.png
        :alt: "事件消息对照表图“
        :align: center

    .. centered:: 事件消息对照表图

2.4 int post_event(int event)
************************************
    当某个事件event发生时，本函数实现将事件event对应的事件状态标号设置为1。只有事件event状态位被置1后，消息获取函数get_msg才能获取到与事件对应的消息。
    | 事件最多支持64种，系统已经定义的事件如图《已有事件列表图》。事件发生与不发生的状态由两个32位的变量event_buf_L、event_buf_H表示，其中变量的每个位表示一个事件的状态（1：事件发生；0：事件未发生）。当某个事件event发生时对应的位将被置1，其它位状态不变。如果用户需求事件量高于64，其事件可类似定义变量和事件宏，用变量位表示其状态,并修改文件中本函数post_event、get_event函数及事件消息对照数组event2msg[MAX_EVENT]等使其支持高于64种事件的事件。
    
    1、event：事件列表中的某个事件，位置见上图《事件消息对照表图》形参，可选事件：
        | ①　EVENT_F1A1_END，F1A1文件播放结束事件
        | ②　EVENT_F1A1_ERR，F1A1文件播放错误事件
        | ③　EVENT_F1A1_LOOP，F1A1文件播放循环事件
        | ④　EVENT_F1A2_END，F1A2文件播放结束事件
        | ⑤　EVENT_F1A2_ERR，F1A2文件播放错误事件
        | ⑥　EVENT_F1A2_LOOP，F1A2文件播放循环事件
        | ⑦　EVENT_MIDI_END，MIDI文件播放结束事件
        | ⑧　EVENT_MIDI_ERR，MIDI文件播放错误事件
        | ⑨　EVENT_A_END，A文件播放结束事件
        | ⑩　EVENT_A_ERR，A文件播放错误事件
        | ⑪　EVENT_A_LOOP，A文件播放循环事件
        | ⑫　EVENT_MP3_END，MP3文件播放结束事件
        | ⑬　EVENT_MP3_ERR，MP3文件播放错误事件
        | ⑭　EVENT_MP3_LOOP，MP3文件播放循环事件
        | ⑮　EVENT_APP_SW_ACTIVE，APP切换活跃事件
        | ⑯　NO_EVENT，无事件发生
    
    2、返回值：返回无误信息MSG_NO_ERROR，返回值无作用；
    
    .. image:: post_event.png
        :alt: "事件状态改变函数“
        :align: center

    .. centered:: 事件状态改变函数

2.5 int post_msg(int argc, ...)
****************************************
    当某个消息发生时，本函数实现将消息放入消息列表。
    
    1、argc：后面可变参数(...)的数量；
    
    2、. . .：可变参数，参数个数可变，可带入一个或多个文件；
    
    可变参数(...)有：
        | (1)　MSG_500MS，ticktime时钟到500ms消息
        | (2)　MSG_PRIV_FILE，播放前一个文件消息
        | (3)　MSG_NEXT_FILE，播放下一个文件消息
        | (4)　MSG_NEXT_DIR，播放下一个文件夹消息
        | (5)　MSG_PLAY_FILE1，播放文件1消息
        | (6)　MSG_PLAY_FILE2，播放文件2消息
        | (7)　MSG_PP，播放文件1暂停消息
        | (8)　MSG_PP_2，播放文件2暂停消息
        | (9)　MSG_VOL_UP，播放声音增大消息
        | (10)　MSG_VOL_DOWN，播放声音减小消息
        | (11)　MSG_A_PLAY，播放文件A消息
        | (12)　MSG_REC_MODE_SWITCH，开始录音与开始播放录音切换消息
        | (13)　MSG_REC_SPEED_EN，录音速率模式使能消息
        | (14)　MSG_MIDI_MODE_SWITCH，midi模式切换消息
        | (15)　MSG_MIDI_OKON_GOON，midi one key one note mode下一音节消息
        | (16)　MSG_NEXT_MODE，app模式切换消息
        | (17)　MSG_RECODE_START，重新编码开始消息
        | (18)　MSG_RECODE_END，重新编码结束消息
        | (19)　MSG_LOW_POWER，低电消息
        | (20)　MSG_ENTER_IDLE，cpu进入空闲消息
        | (21)　MSG_POWER_OFF，关机消息
        | (22)　MSG_CLEAN_ALL_MSG，清空所有消息的消息
    
    3、返回值：MSG_NO_ERROR无实际作用；

2.6 bool get_event_status(u32 event)
********************************************
    本函数实现获取事件event状态的功能。
    1、event: 事件序号, 位置见图《事件宏列表图》, 可选事件:
        
        | ①　EVENT_F1A1_END, F1A1文件播放结束事件
        | ②　EVENT_F1A1_ERR，F1A1文件播放错误事件
        | ③　EVENT_F1A1_LOOP，F1A1文件播放循环事件
        | ④　EVENT_F1A2_END，F1A2文件播放结束事件
        | ⑤　EVENT_F1A2_ERR，F1A2文件播放错误事件
        | ⑥　EVENT_F1A2_LOOP，F1A2文件播放循环事件
        | ⑦　EVENT_MIDI_END，MIDI文件播放结束事件
        | ⑧　EVENT_MIDI_ERR，MIDI文件播放错误事件
        | ⑨　EVENT_A_END，A文件播放结束事件
        | ⑩　EVENT_A_ERR，A文件播放错误事件
        | ⑪　EVENT_A_LOOP，A文件播放循环事件
        | ⑫　EVENT_MP3_END，MP3文件播放结束事件
        | ⑬　EVENT_MP3_ERR，MP3文件播放错误事件
        | ⑭　EVENT_MP3_LOOP，MP3文件播放循环事件
        | ⑮　EVENT_APP_SW_ACTIVE，APP切换活跃事件
        | ⑯　NO_EVENT，无事件发生
    
    2、返回值: 1：事件进行中; 0：事件未执行
        | 可选事件event列表：
        
        .. image:: event.png
            :alt: "事件宏列表图“
            :align: center

        .. centered:: 事件宏列表图 

2.7 函数int get_msg(int len, int \*msg)
*******************************************
    本函数实现获取事件对应的消息信息以及消息列表中消息的功能当获取到事件消息时，不在获取消息列表中消息，当没有事件消息时，查询消息列表，如果有消息，这保存消息信息到形参msg。形参msg需要自定义。
    
    | 1、len：形参msg的长度，长度由实际要获取的消息长度决定，msg长度小于要获取的		   消息长度时返回MSG_BUF_NOT_ENOUGH错误信息；
    | 2、msg：保存获取到的消息信息（可获取到的消息如图图10.1 消息列表图）；
    | 3、返回值：
        
        | MSG_NO_ERROR：获取消息无误       
        | MSG_BUF_NOT_ENOUGH：形参len长度小于实际消息长度
    
    | 可获取到的消息如图《消息列表图》

2.8 函数void clear_all_message(void)
*********************************************
    本函数实现清除所有消息的功能，清除后消息列表为空，没有消息可获取。