三星SDK的API翻译

最新推荐文章于 2024-01-30 08:00:10 发布

iteye_19606

最新推荐文章于 2024-01-30 08:00:10 发布

阅读量227

点赞数

文章标签： c/c++ 数据结构与算法

主要只翻译了device API

Development Guide

http://www.samsungdforum.com/Guide/ref00011/index.html
(2013-04-26 10:35:01)
1.Device API
(API发布时间,2012-02-01,本API兼容SDK4.0,3.5,2.5 和2012,2011的模块)

设备API提供了一种可选的,比网络设备API更老的方式来利用中间件DTV的功能.另外它提供了更多的功能,这些功能在网络设备API上是不可用的.

设备API定义了下面一些内容

API的Widget使用js功能时不支持TV的功能,(比如换频道).
设备API也是一种js
设备API是一种方法调用或者是一种回调,也就是说它具有双向通信的特性
设备API配合浏览器使用
设备API有有限的表达能力和使用,比如一些数据结构或者是数组的表达.
三星的设备API在每个产品上可以不同
设备API依赖三星机器的模块,并且每个产品可以有不同的模块.

该体系的设备API结构说明如下
widget可以调用的设备API支持三星的设备和其他的设备模块,比如频道功能分层
设备API层事实上像C++/C语言绑定了js.
三星智能电视有两个主要层,Widget和三星的引擎
设备API为二进制图像,可以不改变任意的需求.

每个API在设备API下可以有附加的功能的增强版本,可以通过版本号得到,版本描述格式样例:
[DeivceAPIName]-[xxxx]|ex.|TVMW-0005

设备API包含了以下内容

API/模块描述

1.Common/通用
通用API是一个虚拟的插件,介绍了所有插件的一些常见功能,它不是一个真正的插件

function/函数
GetPluginInfo()

define: 本函数获取设备API的信息
param : 参数PL_CMN_INFO定义了设备API的常用信息类型,0为PL_CMN_INFO_VERSION表示插件版本,可以传入数字或者字符串
return: 返回正值为成功,负值为失败
example:例子:
versionMsg = pluginObject.GetPluginInfo(PL_CMN_INFO_VERSION);

2.AppCommon/App常用
App常用api处理基本的电视功能,比如键值注册等
function/函数
CheckReservedKey()

IsKeyRegister()
RegisterAllKey()
RegisterColorKey()
RegisterKey()
RegisterNaviKey()
RegisterNumKey()
RegisterPlaybackKey()
SendEvent IME()
SendEvent IME Sync()
SendKeyToTVViewer()
SubscribeEvent()
UnregisterAllKey()
UnregisterColorKey()
UnregisterKey()
UnregisterNaviKey()
UnregisterNumKey()
UnregisterPlaybackKey()
UnsubscribeEvent()

event/事件
OnMessage

3.Player/播放器
播放器API控制多媒体播放回看. 最新版本PLAYER-0006,CLSID:SAMSUNG-INFOLINK-PLAYER

function/函数

ClearScreen()
define : 清除电视屏幕并且黑屏
param :
return : turn on 返回成功,否则false
example: var retVal=ImageViewer.ClearScreen()

GetAvailableBitrates()
define : 获取当前播放的流媒体的可用比特率
param :
return : 返回可用的比特率.用一个字符串或者用'|'分割的字节来表示,比如100kBps,200kBps 或者102400|204800
remarks: 返回值仅仅在使用play()后才有效
example: var bitratesInfo=Player.GetAvailableBitrates();

GetCurrentBitrates()
define : 获取当前播放内容的比特率
param :
return : 以数字格式返回当前播放的比特率
example: var bps=Player.GetCurrentBitrates();

GetDuration()
define : 获取当前播放内容的持续行.
param :
return : 总共成功的播放次数,否则返回-1
remarks: 必须在OnStreamInfoReady()回调函数开始前使用
example: var totalTime=Player.GetDuration();

GetLiveDuration()
define : 获取当前媒服务器可以持久支持的直播内容
param :
return : 返回开始和结束时间里面的直播内容串
remarks: 仅仅在使用Widevine直播流解决方案后可用
example: var retVal=GetLiveDuration();

GetPlayerVersion()
define : 获取播放器版本
param :
return : 返回播放器版本,格式如"UNIPLAYER-000000"
example: var version=GetPlayerVersion();

GetVideoHeight()
define : 获取当前播放视频的高度
param :
return : 返回当前播放视频内容的高度
remarks: 在OnStreamInfoReady 回调函数回调时用
example: var height=Player.GetVideoHeight();

GetVideoWidth()
define : 获取当前播放视频内容的宽度
param :
return : 当前的播放视频内容的宽度
remarks: 在OnStreamInfoReady 回调函数回调时用
example: var width=Player.GetVideoWidth();

InitPlayer()
define : 通过一个指定的URL初始化播放器
param : (String url) / url串
return : 总是返回true
remarks: 不能和Play() API一起用.如果widget使用Initplayer().就必须使用StartPlayback()来播放一个内容,否则它必须仅使用Play(),如果要使用InitPlayer(),它必须在其他API申明前使用.
example: Player.InitPlayer(url);
SetDisplayArea(x, y, width, height);
SetInitialBufferSize(400*1024); //400KB
StartPlayback();

JumpBackward()
define : 从当前重播点指定多少秒后往后跳
param : number offset/数字偏移量,当前时间和需要跳转的时间的秒差值
return : 跳转成功返回success,否则false
remarks: 和TV一样
example: var retVal=Player.JumpBackward(30);

JumpForward()
define : 从当前重播点指定多少秒后往前跳
param : number offset/数字偏移量,当前时间和需要跳转的时间的秒差值
return : 跳转成功返回success,否则false
example: var retVal=Player.JumpForward(30);

Pause()
define : 暂停当前播放内容
param :
return : 成功success 失败false
example: var retVal=Player.Pause();

Play()
define : 播放指定的url内容
param : string/url串
return : 成功success失败false
example: var retVal=Player.Play(url);

Resume()
define : 恢复暂停的内容
param :
return : 成功success失败false
example: var retVal=Player.Resume();

ResumePlay()
define : 恢复播放通过指定url,指定的位置播放的内容
param : String/url串,Number/多少秒
return : 成功success失败false
remarks: 经常使用在从书签保存的点恢复播放
example: var retVal=Player.ResumePlay(url,3600);

SetCropArea()
define : 设置widget裁剪区想要显示的原始内容.通常用来去除黑边
param : (Number x, Number y, Number width, Number height) / x,y轴坐标(左上为0,0),宽和高
return : 成功success失败false
example: var retVal=Player.SetCropArea(0,100,1920,880);

SetDisplayArea()
define : 设置显示视频内容在电视屏上
param : (Number x, Number y, Number width, Number height) / x,y轴坐标(左上为0,0),宽和高
return : 成功success失败false
example: var retVal=Player.SetDisplayArea(0,0,1920,1080);

SetICT()
define : 设置ICT输出等级
param : bICTOn,bool值/指定ICT的输出水平,ICT开返回true,ICT关返回false
return : 成功success失败false
remarks: 在OnStreamInfoReady回调使用后用,如果widget没调用这个函数,那么系统会关闭ICT
example: var retVal=SetICT(false);

SetInitialBuffer()
define : 设置回播时第一次缓存的百分比大小
param : byte/字节,指定缓存的字节大小,这个api是可选的,媒体播放器有一个默认值
return : 成功success失败false
example: var retVal=SetInitialBuffer(1024*1024);

SetInitialTimeOut()
define : 设置开始播放前的初始缓存的超时最大时间
param : number second/秒
return : 成功success失败false
remarks: 这个api是可选的,媒体播放器有一个默认值
example: var retVal=SetInitialTimeout(30);

SetMacrovision()
define : 设置宏视野的等级,支持PLAYER-0003
param : number/或者指定level
0 : APS_ALL_OFF
1 : APS_AGC_ON_ONLY
2 : APS_AGC_ON_CS_2L
3 : APS_AGC_ON_CS_4L
return : 成功success失败false
remarks: 在OnStreamInfoReady回调使用后用,如果widget没调用这个函数,那么等级默认为0.
example: var retVal=SetMacrovision(3);

SetPendingBuffer()
define : 设置媒体播放器缓冲时的缓冲区占总缓存的百分比的大小
param : number byte
return : 成功success失败false
remarks: 这个api是可选的,媒体播放器有一个默认值
example: var retVal=SetPendingBuffer(512*1024); 512KB

SetPlaybackSpeed()
define : 设置回播内容的速度
param : speed(number)/播放的倍速,可以是负数
return : 成功success失败false
remarks: 在Play()回调函数调用后使用
example: var retVal=SetPlayerbackSpeed(2);

SetPlayerProperty()
define : 设置媒体播放器的一些属性,比如cookie
param : (Number type, String StrParam, Number NumParam)/数字,字符串,数字参数
Number type : 1:Cookie 指定widget想要设置的属性,1为cookie
StrParam : 字符串,指定设置的属性后的参数,比如1st是cookie的值对于cookie属性
NumParam : 指定设置数字参数在上面的参数设置完了,比如cookie的值的长度
return : 成功success失败false
remarks: 在InitPlayer()和StartPlayer()使用后回调,Play()不能使用SetPlayerProperty()
example: InitPlayer(URL);
SetTotalBufferSize(size); //Optional
SetPlayerProperty(1, "CookieValue", CookievalueLength); //Set cookie
StartPlayback(sec);

SetTotalBufferSize()
define : 设置播放器的流的缓冲大小
param : number
return : 成功success失败false
remarks: size/数字,指定总的缓冲区大小字节数,本api可选,播放器含有默认值
example: var retVal=SetTotalBufferSize(5*1024*1024); 5MB

SetVBIData()
define : 设置VBIData输出等级,支持PLAYER-0003
param : (Number macrovisionType,Number cgmsType)
macrovisionType
Number, Specifies the macrovisionType level.指定宏视野的等级
0 : APS_ALL_OFF
1 : APS_AGC_ON_ONLY
2 : APS_AGC_ON_CS_2L
3 : APS_AGC_ON_CS_4L
cgmsType
Number
Specifies the cgmsType level.
0 : CGMS_COPY_FREE
1 : CGMS_COPY_NO_MORE
2 : CGMS_COPY_ONCE
3 : CGMS_COPY_NEVER
return : 成功success失败false
remarks: 在OnStreamInfoReady 回调后调用,如果widget没调用这个函数,系统就不会设置VBIData输出等级,所以最低等级将会被应用,如果widget想保护内容或者想使用不同的保护等级,就必须调用这个api,默认是APS_ALL_OFF 和CGMS_COPY_FREE
example: var retVal=SetVBIData(3,3);

StartPlayback()
define : 开始回放内容
param :
return : 成功success失败false
remarks: 必须在InitPlayer()后调用,不能被Play().StartPlayback()调用
example: Player.InitPlayer(url);
SetDisplayArea(x, y, width, height);
SetInitialBufferSize(400*1024); //400KB
StartPlayback();

Stop()
define : 停止当前播放内容
param :
return : 成功success失败false
example: var retVal=Player.Stop();

event/事件
OnAdEnd
define : 播放完广告时,仅适用于使用流媒体解决方案的一些具体内容.支持PLAYER-0005
remakrs: widget的程序可以利用这个时间来跳转/掠过操作或者隐藏用户通知消息
example: Player.OnAdEnd=OnAdEnd;
function OnAdEnd()
{
//hide AD. notification message 隐藏广告通知消息
//unblock jump event 解锁跳事件
}

OnAdStart
define : 当回播时,需要1个广告开始,仅适用在一些使用了HAS流资源的指定内容,支持PLAYER-0005
remakrs: widget的程序可以利用这个时间以防止广告跳过或者显示用户通知消息
example: Player.OnAdStart=OnAdStart;
function OnAdStart()
{
//show AD. notification message 显示广告通知消息
//block jump event锁定跳事件
}

OnAuthenticationFailed
define : 媒体播放器在验证过程失败的事件
example: Player.OnAuthenticationFailed=OnAuthenticationFailed;
function OnAuthenticationFailed() {
Player.Stop();
}

OnBufferingComplete
define : 媒体播放器得到缓冲状态
example: Player.OnBufferingComplete=OnBufferingComplete;
function OnBufferingComplete()
{
//unload buffering image. 上传一个缓冲图像
}

OnBufferingProgress
define : 通知媒体播放器从缓冲状态接收了多少的数据
param : percent 数字,从0~100
example: Player.OnBufferingProgress=OnBufferingProgress;
function OnBufferingProgress()
{
//Drawing buffering progress bar.
}

OnBufferingStart
define : 媒体播放器得到缓冲状态
example: Player.OnBufferingStart=OnBufferingStart;
function OnBufferingStart()
{
//Drawing buffering image.
}

OnConnectionFailed
define : 媒体服务器没有连接到流媒体服务器时
remakrs: 不同于网络链接时间OnNetWorkDisconnected,该事件仅在媒体播放器在开始播放连接http/https流媒体服务器时发送该事件.
example: Player.OnConnectionFailed=OnConnectionFailed;
function OnConnectionFailed()
{
Player.Stop();
...
}

OnCurrentPlayTime
define : 当媒体播放器被通知当前回播时间时
param : 微秒
example: Player.OnCurrentPlayTime=OnCurrentPlayTime;
function OnCurrentPlayTime() {
...
}

OnNetworkDisconnected
define : 当媒体播放器的网络失去连接时或者流媒体服务器停止发送流的时候
remakrs: 收到该事件意味着媒体播放器成功连接了流媒体服务,通常该事件意味着流在网络失去链接
example: Player.OnNetworkDisconnected=OnNetworkDisconnected;
function OnNetworkDisconnected()
{
Player.Stop();
}

OnRenderError
define : 当媒体播放器的指定参数出现问题时
param : renderErrorType number/数字
remakrs: 定义了下面的参数
1 : Unsupported container
2 : Unsupported video codec
3 : Unsupported audio codec
4 : Unsupported video resolution
example:

OnRenderingComplete
define : 当媒体服务器播放时到达流的结束位置时
example: Player.OnRenderingComplete=OnRenderingComplete;
function OnRenderingComplete()
{
Player.Stop();
}

OnResolutionChanged
define : 当一个视频资源在回播中被改变,仅对于一些指定使用了HAS流资源的内容有效,版本PLAYER-0002
example: Player.OnResolutionChanged=OnResolutionChanged;
function OnResolutionChanged() {

}

OnStreamInfoReady
define : 当播放器准备发送内容信息比如持续时长,参数流的视频资源
remakrs: 一些APIs仅仅在OnStreamInfoReady()发送时有效.比如GetDuration(),GetVideoWidth(),GetVideoHight()
example: Player.OnStreamInfoReady=OnStreamInfoReady;
function OnStreamInfoReady()
{
var totaltime=Player.GetDuration();
var width=Player.GetVideoWidth();
var height=Player.GetVideoHeight();
}
OnStreamNotFound
define : 播放器因为流媒体服务器通过url参数的 Play()api不存在,导致播放失败
example: Player.OnStreamNotFound=OnStreamNotFound;
function OnStreamNotFound()
{
Player.Stop();
}

4.Screen/屏幕
屏幕API处理电视屏幕的命令,比如3D效果,最新版本SCREEN-0004,CLSID:SAMSUNG-INFOLINK-SCREEN

function/函数

Check3DEffectMode
define : 检查3D效果的输入模式
param : PL_SCREEN_3DEFFECT_MODE
return : 正值成功.负值失败
remarks: 总是返回false
example:
if( 1 == ScreenPlugin.Flag3DEffectSupport() )
{
if( PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE == ScreenPlugin.Get3DEffectMode() )
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
}
}
else
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
}
}
}

Flag3DTVConnect
define : 检查连接的电视是否支持3D模式,只有在BD模式下可以调用,支持SCREEN-0005
param :
return : 正值成功.负值失败
example:
if( 1 == ScreenPlugin.Flag3DTVConnect() )
{
if( PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE == ScreenPlugin.Get3DEffectMode() )
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
}
}
else
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
}
}
}

Flag3DEffectSupport
define : 检查设备是否支持3D效果
param :
return : 正值成功.负值失败
remarks: 总是返回false
example:
if( 1 == ScreenPlugin.Flag3DEffectSupport() )
{
if( PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE == ScreenPlugin.Get3DEffectMode() )
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
}
}
else
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
}
}
}

Get3DEffectMode
define : 获取当前的3D模式(PL_SCREEN_3DEFFECT_MODE),支持SCREEN-0002
param :
return : 正值成功.负值失败
remarks: 总是返回PL_SCREEN_3DEFFECT_MODE_OFF
example:
if( 1 == ScreenPlugin.Flag3DEffectSupport() )
{
if( PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE == ScreenPlugin.Get3DEffectMode() )
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
}
}
else
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
}
}
}

GetOption
define : 获取特定选项的值 PL_SCREEN_OPTION
param : PL_SCREEN_OPTION
return : 得到指定的值返回success,否则返回负值
remarks: 总是返回true
example:
if( 1 == ScreenPlugin.GetOption(PL_SCREEN_OPTION_SHOP_MODE) )
{
ScreenPlugin.GetOption(PL_SCREEN_OPTION_SHOP_MODE, 0)
}
else
{
...
}

Set3DEffectMode
define : 设置3D效果
param : PL_SCREEN_3DEFFECT_MODE
return : 正值成功.负值失败
remarks: 总是返回false
example:
if( 1 == ScreenPlugin.Flag3DEffectSupport() )
{
if( PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE == ScreenPlugin.Get3DEffectMode() )
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_OFF);
}
}
else
{
if( 1 == ScreenPlugin.Check3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
{
ScreenPlugin.Set3DEffectMode(PL_SCREEN_3DEFFECT_MODE_SIDE_BY_SIDE);
}
}
}

5.Video/视频
视频API控制DTV平台上视频相关的功能,比如屏幕状态.最新版本TVMW-0027,CLSID:SAMSUNG-INFOLINK-TVMW

function/函数
ChangeWidgetMode()
define : 这个函数在widget的下面,当一个widget从完整模式,部分模式,或者部分全模式的变化,widget将调用这个函数当全部/部分模式改变时.
param : PL_VIDEO_VIDEGET_MODE
return : 成功success失败false
remakrs: 全模式,窗口覆盖全屏幕(960x540),部分模式,装扣仅覆盖一部分DTV屏
example: VideoPlugin.ChangeWidgetMode(PL_VIDEO_WIDGET_MODE_FULL);
//切换到全模式
VideoPlugin.ChangeWidgetMode(PL_VIDEO_WIDGET_MODE_PART);
//切换到部分模式

SetOSDState()
define : 设置屏幕增强功能是否开启MJC on/off
param : (Number handle,Number x,Number y,Number w,Number h,Number OSDState)
return : 成功返回PLR_TURE 失败返回错误码
remarks: 当一些widget显示在一些面板上,隐藏widget时,会留有残影,这个函数可以避免
example: //... MJC Off ...
VideoPlugin.SetOSDState(1,100, 100, 100, 100, PLR_TRUE);
//... MJC On ...
VideoPlugin.SetOSDState(1,100, 100, 100, 100, PLR_FALSE);