Mocor MMI MPEG4 Interface User Guide.docx
《Mocor MMI MPEG4 Interface User Guide.docx》由会员分享，可在线阅读，更多相关《Mocor MMI MPEG4 Interface User Guide.docx（21页珍藏版）》请在冰点文库上搜索。
MocorMMIMPEG4InterfaceUserGuide
MocorMMIMPEG4InterfaceUserGuide
Version:
1.0.0
DocCode:
SW-MOCOR-UG-0001
Date:
2008-02-21
重要声明
版权声明
本文档中的任何内容受《中华人民共和国著作权法》的保护，版权所有©2008，展讯通信有限公司，保留所有权利，但注明引用其他方的内容除外。
商标声明
展讯通信有限公司和展讯通信有限公司的产品是展讯通信有限公司专有。
在提及其他公司及其产品时将使用各自公司所拥有的商标，这种使用的目的仅限于引用。
不作保证声明
展讯通信有限公司不对此文档中的任何内容作任何明示或暗示的陈述或保证，而且不对特定目的的适销性及适用性或者任何间接、特殊或连带的损失承担任何责任。
保密声明
本文档（包括任何附件）包含的信息是保密信息。
接收人了解其获得的本文档是保密的，除用于规定的目的外不得用于任何目的，也不得将本文档泄露给任何第三方。
前言
文档说明
本文档为MMIMPEG4模块的接口文档，详细描述了本模块提供给其他MMI模块的API接口。
阅读对象
本文档适合MMI软件开发人员和相关客户开发人员使用。
内容介绍
本文档包括三个章节，分别为：
•第一章：
模块的总体结构。
简单介绍了MMIMPEG4模块的功能结构；
•第二章：
数据类型。
介绍了对外部模块提供的数据结构；
•第三章：
提供给其他模块的接口。
介绍了MMIMPEG4模块提供给外部模块的接口函数。
文档约定
本文档采用下面醒目标志来表示在操作过程中应该特别注意的地方。
注意：
提醒操作中应注意的事项。
说明：
说明比较重要的事项。
相关文档
目录
第1章概述1-1
1.1模块总体框架1-1
1.2模块功能概述1-1
第2章数据类型2-1
2.1宏定义2-1
2.1.1MMIMPEG4_MAX_FILE_NAME_LEN2-1
2.2枚举2-1
2.2.1MMIMPEG4_TYPE_E2-1
2.2.2MMIMPEG4_MOVIE_SUPPORTED_TYPE_E2-2
2.3结构2-3
2.3.1MMIMPEG4_BUFFER_FILE_INFO_T2-3
第3章提供给其他模块的接口3-1
3.1初始化接口3-1
3.1.1MMIAPIMPEG4_Init3-1
3.2视频播放相关接口3-1
3.2.1MMIAPIMPEG4_PlayFromPathName3-1
3.2.2MMIAPIMPEG4_ReviewFromPathName3-2
3.2.3MMIAPIMPEG4_PlayFromBuf3-3
3.2.4MMIAPIMPEG4_PlayFromNameForPowerOnOff3-4
3.2.5MMIAPIMPEG4_CallBackForPowerOnOff3-5
3.2.6MMIAPIMPEG4_PowerOnOffExit3-5
3.2.7MMIAPIMPEG4_PlayFromNameForSSaver3-6
3.2.8MMIAPIMPEG4_CallBackProcForSSaver3-7
3.2.9MMIAPIMPEG4_SSaverExit3-7
3.2.10MMIAPIMPEG4_ProcessSignal3-8
3.3其它接口3-8
3.3.1MMIAPIMPEG4_MainEntry3-8
3.3.2MMIAPIMPEG4_Exit3-9
3.3.3MMIAPIMPEG4_IsOpened3-9
3.3.4MMIAPIMPEG4_ProcessTVOutClose3-10
3.3.5MMIAPIMPEG4_StopOperaSDPlug3-10
3.3.6MMIAPIMPEG4_GetMovieSupportedType3-11
3.3.7MMIAPIMPEG4_CheckPlayCondition3-11
3.3.8MMIAPIMPEG4_CombineFullPath3-12
附录ARevisionHistoryA-1
第一章概述
一.1模块总体框架
总体结构图如图11所示。
图11MPEG4模块在总体结构中的位置
一.2模块功能概述
MPEG4模块实现了视频播放器，并提供接口给外部模块来进行视频播放，具体功能包括：
•播放基本功能，即对视频文件的播放控制，包括播放、暂停、停止、快进、快退等；以及播放器界面功能，包括界面显示、文件详情获取、播放列表显示、设置等。
•向其他模块提供视频播放和相关控制的接口，如视频屏保、开机/关机动画的播放控制和设置接口，彩信预览、摄像预览、资源管理器视频预览等的文件播放。
第二章数据类型
二.1宏定义
二.1.1MMIMPEG4_MAX_FILE_NAME_LEN
【含义】
MMIMPEG4_MAX_FILE_NAME_LEN定义了MPEG4名字的最大长度（文件名+后缀名），以字节计。
【定义】
#defineMMIMPEG4_MAX_FILE_NAME_LEN
（MMIFILE_FILE_NAME_MAX_LEN*2+2）
二.2枚举
二.2.1MMIMPEG4_TYPE_E
【含义】
MMIMPEG4_TYPE_E定义了平台可能支持的一些视频格式。
【定义】
typedefenum
{
MPEG4_TYPE_3GP,
MPEG4_TYPE_MP4,
MPEG4_TYPE_SDP,
MPEG4_TYPE_MAX
}MMIMPEG4_TYPE_E;
【参数说明】
参数名称
含义
MPEG4_TYPE_3GP
3GP格式
MPEG4_TYPE_MP4
MP4格式
MPEG4_TYPE_SDP
SDP格式
MPEG4_TYPE_MAX
系统保留，不可使用
二.2.2MMIMPEG4_MOVIE_SUPPORTED_TYPE_E
【含义】
MMIMPEG4_MOVIE_SUPPORTED_TYPE_E定义了平台对视频文件是否可以播放的支持程度。
【定义】
typedefenum
{
MPEG4_SUPPORTED_AUDIO_ONLY,
MPEG4_SUPPORTED_VIDEO_ONLY,
MPEG4_SUPPORTED_BOTH,
MPEG4_SUPPORTED_NEITHER,
MPEG4_SUPPORTED_OVER_SCALED,//exceedthelimitof640*480
MPEG4_SUPPORTED_TYPE_MAX
}MMIMPEG4_MOVIE_SUPPORTED_TYPE_E;
【参数说明】
参数名称
含义
MPEG4_SUPPORTED_AUDIO_ONLY
仅支持音频解码播放
MPEG4_SUPPORTED_VIDEO_ONLY
仅支持图像解码播放
MPEG4_SUPPORTED_BOTH
可正常播放，图像解码和音频解码均支持
MPEG4_SUPPORTED_NEITHER
无法播放，图像解码和音频解码均不支持
MPEG4_SUPPORTED_OVER_SCALED
片源规格（最大分辨率）超出平台的支持范围。
MPEG4_SUPPORTED_TYPE_MAX
系统保留，不可使用
二.3结构
二.3.1MMIMPEG4_BUFFER_FILE_INFO_T
【含义】
MMIMPEG4_BUFFER_FILE_INFO_T定义了从BUFFER播放MPEG4时的文件信息。
【定义】
typedefstruct
{
void*buf_ptr;
MMIMPEG4_TYPE_Etype;
uint32memory_size;
MMI_WIN_ID_Treturn_win_id;
SFS_HANDLEmpeg4_file_hadle;
}MMIMPEG4_BUFFER_FILE_INFO_T;
【参数说明】
参数名称
含义
buf_ptr
数据Buffer地址
type
视频格式
memory_size
音乐厅模式
return_win_id
消息返回窗口ID
mpeg4_file_hadle
文件handle
第三章提供给其他模块的接口
三.1初始化接口
三.1.1MMIAPIMPEG4_Init
【函数原型】
PUBLICvoidMMIAPIMPEG4_Init（void）;
【函数功能】
注册MPEG4模块的MENU。
该函数用于开机初始化、U盘退出、格式化文件系统等情况。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.2视频播放相关接口
三.2.1MMIAPIMPEG4_PlayFromPathName
【函数原型】
PUBLICvoidMMIAPIMPEG4_PlayFromPathName（
FILE_DEV_E_Tfile_dev,
MMIMPEG4_TYPE_Etype,
uint8const*absolute_path_name_ptr,
uint32name_byte_length
）;
【函数功能】
提供给其他模块，用于播放视频文件。
【参数说明】
file_dev：
文件所在的设备名，U盘或者SD卡；
type：
文件类型；
absolute_path_name_ptr：
文件的绝对路径，包含文件名；
name_byte_length：
文件绝对路径的长度。
【返回值】
无。
【注意事项】
无。
三.2.2MMIAPIMPEG4_ReviewFromPathName
【函数原型】
PUBLICvoidMMIAPIMPEG4_ReviewFromPathName（
FILE_DEV_E_Tfile_dev,
MMIMPEG4_TYPE_Etype,
uint8const*absolute_path_name_ptr,
uint32name_byte_length
）;
【函数功能】
该函数提供给DV模块，用于播放录像文件。
【参数说明】
file_dev：
文件所在的设备名，U盘或者SD卡；
type：
文件类型；
absolute_path_name_ptr：
文件的绝对路径，包含文件名；
name_byte_length：
文件绝对路径的长度。
【返回值】
无。
【注意事项】
无。
三.2.3MMIAPIMPEG4_PlayFromBuf
【函数原型】
PUBLICvoidMMIAPIMPEG4_PlayFromBuf（
uint8*video_buf,
uint32video_length,
MMIMPEG4_TYPE_Evideo_type,
END_CALL_BACK_FUNCend_call_back_func,
BOOLEANneed_frame,
BOOLEANaudio_open,
BOOLEANis_power_on_off
）;
【函数功能】
该函数用于提供给其他模块，用于从Buffer中读取视频数据并播放之。
视频播放正常结束、强制结束或者异常结束之后，进行MPEG4的播放流程处理，之后会调用此回调函数end_call_back_func，以便执行其他模块所需的后续操作。
【参数说明】
video_buf：
视频数据所在的Buffer地址；
video_length：
视频数据的大小；
video_type：
视频数据类型；
end_call_back_func：
回调函数，视频播放正常结束或者异常结束之后，其他模块所需执行的操作；
need_frame：
是否需要显示播放器面板界面，否则全屏播放；
audio_open：
是否需要播放声音，否则只播画面；
is_power_on_off：
调用类型是否为开关机动画，否则为MMS模块调用。
【返回值】
无。
【注意事项】
无。
三.2.4MMIAPIMPEG4_PlayFromNameForPowerOnOff
【函数原型】
PUBLICvoidMMIAPIMPEG4_PlayFromNameForPowerOnOff（
uint8const*full_path_name_ptr,
uint16name_len,
BOOLEANaudio_open,
END_CALL_BACK_FUNCend_call_back_func
）;
【函数功能】
提供给PHONE模块，用于播放设为开机/关机动画的视频文件。
【参数说明】
full_path_name_ptr：
文件的绝对路径，包含文件名；
name_len：
绝对路径长度，以字节计；
audio_open：
判断标志，是否需要播放声音；
end_call_back_func：
回调函数，播放结束后调用，以供其他模块执行后续操作。
【返回值】
无。
【注意事项】
无。
三.2.5MMIAPIMPEG4_CallBackForPowerOnOff
【函数原型】
PUBLICvoidMMIAPIMPEG4_CallBackForPowerOnOff（
int32i_type
）;
【函数功能】
用于播放流程控制——从BUFFER播放的开机/关机动画的结束（包括正常、异常、强制结束）时，响应MSG_MPEG4_END_CALLBACK消息，退出MPEG4模块，同时调用MMIAPIMPEG4_PlayFromBuf（）函数传入的回调函数。
【参数说明】
i_type：
播放结束类型。
i_type=MMIMPEG4_END_NORMAL：
正常结束；
i_type>MMIMPEG4_END_NORMAL：
强制结束；
i_type异常结束；
详细信息请参考文档《DigitalPlayerInterfaceUserGuide》中的DPLAYER_RETURN_E定义。
【返回值】
无。
【注意事项】
无。
三.2.6MMIAPIMPEG4_PowerOnOffExit
【函数原型】
PUBLICBOOLEANMMIAPIMPEG4_PowerOnOffExit（void）;
【函数功能】
仅用于开关机动画的默认方式——从BUFFER播放视频数据。
提供给PHONE模块，当开关机动画5S时间结束或者闹铃打断视频播放时，强制结束开机/关机动画播放。
【参数说明】
无。
【返回值】
FALSE：
失败；
TRUE：
成功。
【注意事项】
无。
三.2.7MMIAPIMPEG4_PlayFromNameForSSaver
【函数原型】
PUBLICvoidMMIAPIMPEG4_PlayFromNameForSSaver（
uint8const*full_path_name_ptr,
uint16name_len,
BOOLEANis_first_play
）;
【函数功能】
提供给IDLE模块，用于播放设为屏保的视频文件。
【参数说明】
full_path_name_ptr：
文件的绝对路径，包含文件名；
name_len：
绝对路径长度，以字节计；
is_first_play：
是否为屏保启动后循环播放中的第一次播放。
【返回值】
TRUE：
该文件是当前播放的MP3文件；
FALSE：
该文件不是当前播放的MP3文件。
【注意事项】
无。
三.2.8MMIAPIMPEG4_CallBackProcForSSaver
【函数原型】
PUBLICBOOLEANMMIAPIMPEG4_CallBackProcForSSaver（
int32i_type
）;
【函数功能】
提供给IDLE模块，用于判断是否要重复播放还是结束屏保。
视频播放结束后会通过消息通知IDLE模块调用此函数，以执行后续操作。
【参数说明】
i_type：
播放结束类型。
i_type=MMIMPEG4_END_NORMAL：
正常结束；
i_type>MMIMPEG4_END_NORMAL：
强制结束；
i_type异常结束；
详细信息请参考文档《SC6800DigitalPlayerInterfaceUserGuide》中的DPLAYER_RETURN_E定义。
【返回值】
TRUE：
视频屏保播放正常结束，可以启动下次播放；
FALSE：
播放异常结束或者其他事件打断了播放，停止播放，退出屏保。
【注意事项】
无。
三.2.9MMIAPIMPEG4_SSaverExit
【函数原型】
PUBLICvoidMMIAPIMPEG4_SSaverExit（void）;
【函数功能】
提供给IDLE模块，当屏保停止时，调用此函数以退出视频播放。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.2.10MMIAPIMPEG4_ProcessSignal
【函数原型】
PUBLICvoidMMIAPIMPEG4_ProcessSignal（
uint16signal
）;
【函数功能】
该函数用于播放器的视频帧画面刷新。
【参数说明】
signa：
由驱动发送给MMI请求视频画面刷新的信号。
【返回值】
无。
【注意事项】
无。
三.3其它接口
三.3.1MMIAPIMPEG4_MainEntry
【函数原型】
PUBLICvoidMMIAPIMPEG4_MainEntry（void）;
【函数功能】
该函数用于打开视频播放器，进入播放器界面。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.3.2MMIAPIMPEG4_Exit
【函数原型】
PUBLICvoidMMIAPIMPEG4_Exit（void）;
【函数功能】
退出MPEG4窗口，用于来电、U盘启动、SD卡插入/拔出等情况。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.3.3MMIAPIMPEG4_IsOpened
【函数原型】
PUBLICBOOLEANMMIAPIMPEG4_IsOpened（void）;
【函数功能】
该函数用于判断MPEG4主窗口是否在运行。
【参数说明】
无。
【返回值】
TRUE：
MPEG4主窗口正在运行；
FALSE：
非上述情况。
【注意事项】
无。
三.3.4MMIAPIMPEG4_ProcessTVOutClose
【函数原型】
PUBLICvoidMMIAPIMPEG4_ProcessTVOutClose（void）;
【函数功能】
用于TVOUT模式退出时，如果视频播放器已打开或正在播放，则停止播放，并退出播放器窗口。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.3.5MMIAPIMPEG4_StopOperaSDPlug
【函数原型】
PUBLICvoidMMIAPIMPEG4_StopOperaSDPlug（void）;
【函数功能】
提供给UDISK模块，用于SD卡插入和拔出时，如果正在播放视频或者已打开视频播放器，退出MPEG4模块。
【参数说明】
无。
【返回值】
无。
【注意事项】
无。
三.3.6MMIAPIMPEG4_GetMovieSupportedType
【函数原型】
PUBLICMMIMPEG4_MOVIE_SUPPORTED_TYPE_E
MMIAPIMPEG4_GetMovieSupportedType（
uint8*full_file_name,
uint16full_name_len
）;
【函数功能】
提供给外部模块，用于判断视频文件是否为视频播放器的支持格式。
其他模块可以根据需要来判断返回类型格式是否支持。
【参数说明】
full_file_name：
文件的全路径，包括文件名；
full_name_len：
文件全路径的长度。
【返回值】
详细信息请参考MMIMPEG4_MOVIE_SUPPORTED_TYPE_E枚举定义。
【注意事项】
无。
三.3.7MMIAPIMPEG4_CheckPlayCondition
【函数原型】
PUBLICBOOLEANMMIAPIMPEG4_CheckPlayCondition（void）;
【函数功能】
提供给外部模块，用于判断MPEG4模块正常启动所需要的内存条件是否可以满足。
【参数说明】
无。
【返回值】
TRUE：
条件满足，可以启动视频播放；
FALSE：
条件不足，无法播放。
【注意事项】
无。
三.3.8MMIAPIMPEG4_CombineFullPath
【函数原型】
PUBLICuint16MMIAPIMPEG4_CombineFullPath（
uint8*abs_path_ptr,
uint32abs_path_len,
FILE_DEV_E_Tfile_dev,
uint8const*dir_ptr,
BOOLEANdir_is_ucs2,
uint8const*name_ptr,
BOOLEANname_is_ucs2
）;
【函数功能】
此函数用于拼接文件的绝对路径,是对MMIFILE_CombineFullPath的一层封装，类似于MMIFILE_CombineFullPath,但参数和返回值不同。
【参数说明】
abs_path_ptr：
［OUT］拼接好的绝对路径；
abs_path_len：
abs_path_ptr所指空间大小；
file_dev：
设备类型；
dir_ptr：
目录名；
dir_is_ucs2：
目录名是否为UINCODE；
name_ptr：
文件名；
name_is_ucs2：
文件名是否为UINCODE。
【返回值】
返回绝对路径长度。
【注意事项】
无。
附录ARevisionHistory
Version
Date
Owner
Notes
1.0.0
2008-02-21
Xingdong.li
Created
升级会员 