深圳励研科技SCL程序员手册(二)

深圳励研科技SCL程序员手册(二)第一章通讯控制函数本章介绍通讯初始化函数。网络模式下，计算机与控制器采用UDP协议交换数据，占用两个相邻的端口号(P、P+1)。通讯时，计算机用端口P向控制器的P+1端口发送数据，控制器也用端口P向计算机的端口P+1发送数据。在与控制器通讯前，必须调用SCL_NetInitial或SCL_ComInitial之一；通讯结束后，必须调用SCL_Close释放通讯设备。函数的参数表中，若有参数nDevID，该参数即是设备编号，含义请参见§1.第二章文件管理、数据收发函数在以下各章中，“驱动器编号”参数为0表示A盘(FLASH盘)，1表示B盘(SD卡)，2表示C盘(RAM盘)第六章控制函数§2.1复位控制器SCL_ResetBOOLSCL_Reset(WORDnDevID);功能：复位控制器入口：无出口：若控制器正常复位，返回TRUE(非0)，否则返回FALSE(0)§2.2播放新节目表SCL_ReplayBOOLSCL_Replay(WORDnDevID,intdrv,intIndex);功能：当全部图片及节目表文件都发送到控制器上后，调用此函数令控制器执行新节目表入口：drv:驱动器编号Index：节目表编号，0-99。例如，SCL_Replay(nDevID,2,8)可命令控制器播放C:\P08目录下的PLAYLIST.LY；SCL_Replay(nDevID,1,3)则命令控制器播放B:\P03目录下的节目表PLAYLIST.LY出口：若控制器开始播放新节目表，返回TRUE(非0)，否则返回FALSE(0)§2.3校准控制器时钟SCL_SetTimerBOOLSCL_SetTimer(WORDnDevID);功能：自动取计算机的系统时钟校准控制器的时钟入口：无出口：校准时钟成功则返回TRUE(非0)，否则返回FALSE(0)2.4设置自动开关屏时间SCL_SetOnOffTimeBOOLSCL_SetOnOffTime(WORDnDevID,unsignedshortOnTime,unsignedshortOffTime);功能：设置自动开关屏时间。若需要强行关闭显示屏，可设置开屏时间、关屏时间均为0；若需强行打开显示屏，可设置开屏时间和关屏时间均为23点59分。入口：OnTime:开屏时间OffTime：关屏时间。OnTime和OffTime的格式为时*100+分。例如，9点28分将写成928出口：设置成功，返回TRUE(非0)，否则返回FALSE(0)§2.5设置显示屏亮度SCL_SetBrightBOOLSCL_SetBright(WORDnDevID,unsignedshortbrightness);功能：设置显示屏的亮度。入口：bright：亮度值，有效范围为0-31，其中31表示根据外置的亮度传感器自动调整屏体亮度出口：设置亮度成功，返回TRUE(非0)，否则返回FALSE(0)§2.6设置温度采样补偿SCL_SetTempOffsetBOOLSCL_SetTempOffset(WORDnDevID,shortoffset);功能：修正温度传感器DS18B20采样的数据。DS18B20传感器允许±2℃的误差，此修正可令LED显示更准确。入口：offset为将加到温度传感器采样结果之上的调整值，范围为-7到+7出口：设置成功，返回TRUE(非0)，否则返回FALSE(0)2.7设置电源模式SCL_SetPowerModeBOOLSCL_SetPowerMode(WORDnDevID,intPowerMode);功能：设置屏体电源模式，实现远程屏体电源控制入口：PowerMode：新的屏体电源模式，0：关闭电源，1：打开电源，2：按照SCL_SetOnOffTime函数设置的开关时间自动控制出口：设置电源模式成功，返回TRUE(非0)，否则返回FALSE(0)§2.8读运行信息SCL_GetRunTimeInfoBOOLSCL_GetRunTimeInfo(WORDnDevID,BYTE*Buff512Bytes);功能：获取控制器当前的运行信息入口：Buff512Bytes：保存运行信息的至少512字节的缓冲区，保存在Buff512Bytes中的数据格式请参见C语言Delphi语言的动态链接库头文件。出口：获取运行信息成功，返回TRUE(非0)，Buff512Bytes缓冲区中的内容有效；否则返回FALSE(0)2.9读播放信息SCL_GetPlayInfoBOOLSCL_GetPlayInfo(WORDnDevID,BYTE*PlayInfo);功能：获取控制器当前的播放信息入口：PlayInfo：存放返回结果的至少7个字节的内存空间出口：获取播放信息成功，返回TRUE(非0)，PlayInfo中的数据有效；否则返回FALSE(0)。PlayInfo[0]：当前播放的节目表的驱动器编号;PlayInfo[1]：当前播放的第00套-第99套节目的索引号，从0开始编号;PlayInfo[2]：当前播放的PLAYLIST.LY文件中的第几个节目，从0开始编号；PlayInfo[3]：区域1正在播放的节目项索引,从0开始编号PlayInfo[4]：区域2正在播放的节目项索引,从0开始编号PlayInfo[5]：区域3正在播放的节目项索引,从0开始编号PlayInfo[6]：区域4正在播放的节目项索引,从0开始编号§2.10控制扩展开关SCL_SetExtSWBOOLSCL_SetExtSW(WORDnDevID,WORDOnOff);功能：控制SuperComm完整版的SW2(SCL2008:SW1)的输出状态入口：OnOff：0关闭，1打开出口：设置成功，返回TRUE(非0)，否则返回FALSE(0)。设置成功时，若OnOff参数为0，则控制器上的LSW2灯(SCL2008:SW1)熄灭，SW2(SCL2008:SW1)输出口无压差；若OnOff参数为1，则控制器上的LSW2灯(SCL2008:SW1)点亮，SW2(SCL2008:SW1)输出口两个引脚提供4V、20mA的信号，用于控制固态继电器。第三章自行组织数据收发某些情况下，希望动态链接库提供的函数只实现通讯协议的封装过程，由程序员自行安排通讯设备的初始化和数据的收发管理。本章解释如何实现这些需求。调用SCL_InitForPackage函数初始化虚拟的网络或串行设备，让动态链接库仅封装数据包而不通过真实的通讯设备收发数据。若调用了SCL_InitForpackage，最后也需要SCL_Close关闭。网络方式下，计算机与控制器采用UDP协议交换数据，占用两个相邻的UDP端口。获得数据包后，若计算机使用端口P向控制器发送数据，则目标端口(控制器的接收端口)必须是P+1；同时，控制器也用端口P向计算机发送数据，计算机程序需在P+1端口接收应答。文件管理和数据收发函数以及控制类函数中，SCL_GetDirItem、SCL_SendFile和SCL_ReceiveFile需要与控制器交换多个数据包，这三个函数之外的其它所有函数与控制器均只需要交换一个数据包。本章介绍如何获取封装好的数据包，及检查这些数据包发送到控制器后，控制器给回的应答是否正确。调用的基本步骤为：1、调用SCL_InitForPackage函数，初始化一个虚拟的网络或串行通讯设备2、根据需要，调用SCL_SetRemoteIP或SCL_SetLEDNum，以及SCL_TargetSCL2008函数3、调用文件收发和控制类功能函数4、调用SCL_GetPackage，取封装好通讯协议的数据包5、程序员自行组织数据的收发过程6、调用SCL_CheckAnswer，确定控制器给回的应答是否正确，若正确，或可使用这些应答，或可继续向控制器发送其它数据因为SCL_GetDirItem、SCL_SendFile和SCL_ReceiveFile函数需要与控制器交换多个数据包，所以这三个函数在程序员自行组织收发时不能直接调用。本章也将介绍如何实现这三个函数的功能。第四章文件格式转换§4.1图片文件转换成XMP文件SCL_PictToXMPFileBOOLSCL_PictToXMPFile(intcolortype,intwidth,intheight,BOOLbstretch,char*Pictfilename,char*XMPfilename);功能：将BMP或JPEG文件转换成包含一个图片的XMP文件，不支持其它格式的图片文件。入口：colortype：颜色类型，0：双色256级灰度(用于SuperComm)1：三色64级灰度(用于SuperComm)2：双色无灰度(用于SCL2008)3：三色无灰度(用于SCL2008)width：目标图片的宽，单位：象素；height：目标图片的高，单位：象素；bstretch：是否对源图片进行自动缩放；Pictfilename：输入的BMP或JPEG图片文件名(含路径)；XMPfilename：输出的XMP文件名(含路径)出口：转换成功，返回TRUE(非0)，否则返回FALSE(0)。返回FALSE可能是因为：颜色类型非法，或区域的宽、高超出控制器的控制范围，或读入BMP、JPEG图片文件失败，或输出XMP文件失败§4.2XMP文件大小SCL_GetMaxFileSizeintSCL_GetMaxFileSize(intScreenCount,BOOLbSmallest,BOOLbSCL2008);功能：根据单个节目的分区数和播放该图片的区域是否为最小区域计算一个XMP文件的最大字节数。因为控制器在播放时根据当前节目的分区数自动分配文件预读缓冲区(边播放边将下一待播放的文件读入内存)，所以生成的XMP文件的大小不能超出缓冲区大小。本函数按照控制器的缓冲区分配算法获取XMP文件的最大长度。入口：ScreenCount：节目的分区数，1-4；bSmallest：当前计算的区域是否是最小区域；bSCl2008：控制器类型。FALSE:SuperComm，TRUE：SCL2008出口：以字节为单位的XMP文件大小§4.3合并XMP文件SCL_AddXMPToXMPintSCL_AddXMPToXMP(char*InFilename,char*OutFilename,intMaxSize);功能：将两个XMP格式的图片文件合并为一个XMP文件入口：InFilename：包含一个或多个图片的XMP文件名(含路径)；OutFilename：包含一个或多个图片的XMP文件名(含路径)，若OutFilename不存在，则执行InFilename到OutFilename的拷贝操作；MaxSize：XMP文件的最大长度，使用SCL_GetMaxFileSize的返回值。要求InFilename和OutFilename中的图片的颜色类型、基本宽高都一致才可以合并。出口：若合并成功，返回0，否则返回错误代码：1：InFilename不存在2：InFilename打开失败3：OutFilename打开失败4：合并后的图片总数超过2555：两个文件的版本不符(每点颜色类型不同)6：两个文件中的图片的基本宽高不同7：InFilename表示的文件，其大小与文件中定义的图片类型及大小不符(文件有损坏)8：OutFilename表示的文件，其大小与文件中定义的图片类型及大小不符(文件有损坏)9：合并后的文件大小超出MaxSize限定的最大长度第五章使用字库§5.1装载字库SuperComm/SCL2008控制器支持多种字库。在第二章中已经介绍Config.LY中装载字库的指定。控制器提供最大8M空间存放字库，并且支持同时管理最多8套字库。必须小心的计算所有要装载的字库文件的大小。他们的总和不得大于8M字节。开发包中提供了一个自动生成汉字和西文字库的程序MakeFontLib.Exe。程序员可以利用它生成需要的字库，该程序运行完毕后，将会有CharCount、