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

深圳励研科技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_ResetBOOL SCL_Reset(WORD nDevID);功能：复位控制器入口：无出口：若控制器正常复位，返回TRUE(非0)，否则返回FALSE(0)2.2 播放新节目表 SCL_ReplayBOOL SCL_Replay(WORD nDevID,int drv, int Index);功能：当全部图片及节目表文件都发送到控制器上后，调用此函数令控制器执行新节目表入口：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_SetTimerBOOL SCL_SetTimer(WORD nDevID);功能：自动取计算机的系统时钟校准控制器的时钟入口：无出口：校准时钟成功则返回TRUE(非0)，否则返回FALSE(0)2.4 设置自动开关屏时间 SCL_SetOnOffTimeBOOL SCL_SetOnOffTime(WORD nDevID,unsigned short OnTime,unsigned short OffTime);功能：设置自动开关屏时间。若需要强行关闭显示屏，可设置开屏时间、关屏时间均为0；若需强行打开显示屏，可设置开屏时间和关屏时间均为23点59分。入口：OnTime: 开屏时间OffTime：关屏时间。OnTime和OffTime的格式为 时*100+分。例如，9点28分将写成928出口：设置成功，返回TRUE(非0)，否则返回FALSE(0)2.5 设置显示屏亮度 SCL_SetBrightBOOL SCL_SetBright(WORD nDevID,unsigned short brightness);功能：设置显示屏的亮度。入口：bright：亮度值，有效范围为0-31，其中31表示根据外置的亮度传感器自动调整屏体亮度出口：设置亮度成功，返回TRUE(非0)，否则返回FALSE(0)2.6 设置温度采样补偿 SCL_SetTempOffsetBOOL SCL_SetTempOffset(WORD nDevID,short offset);功能：修正温度传感器DS18B20采样的数据。DS18B20传感器允许2的误差，此修正可令LED显示更准确。入口：offset为将加到温度传感器采样结果之上的调整值，范围为-7到+7出口：设置成功，返回TRUE(非0)，否则返回FALSE(0)2.7 设置电源模式 SCL_SetPowerModeBOOL SCL_SetPowerMode(WORD nDevID,int PowerMode);功能： 设置屏体电源模式，实现远程屏体电源控制入口：PowerMode：新的屏体电源模式，0：关闭电源，1：打开电源，2：按照SCL_SetOnOffTime函数设置的开关时间自动控制出口：设置电源模式成功，返回TRUE(非0)，否则返回FALSE(0)2.8 读运行信息SCL_GetRunTimeInfoBOOL SCL_GetRunTimeInfo(WORD nDevID, BYTE *Buff512Bytes);功能： 获取控制器当前的运行信息入口：Buff512Bytes：保存运行信息的至少512字节的缓冲区，保存在Buff512Bytes中的数据格式请参见C语言Delphi语言的动态链接库头文件。出口：获取运行信息成功，返回TRUE(非0)，Buff512Bytes缓冲区中的内容有效；否则返回FALSE(0)2.9 读播放信息SCL_GetPlayInfoBOOL SCL_GetPlayInfo(WORD nDevID, BYTE *PlayInfo);功能：获取控制器当前的播放信息入口：PlayInfo：存放返回结果的至少7个字节的内存空间出口：获取播放信息成功，返回TRUE(非0)，PlayInfo中的数据有效；否则返回FALSE(0)。PlayInfo0：当前播放的节目表的驱动器编号;PlayInfo1：当前播放的第00套-第99套节目的索引号，从0开始编号;PlayInfo2：当前播放的PLAYLIST.LY文件中的第几个节目，从0开始编号；PlayInfo3：区域1正在播放的节目项索引,从0开始编号PlayInfo4：区域2正在播放的节目项索引,从0开始编号PlayInfo5：区域3正在播放的节目项索引,从0开始编号PlayInfo6：区域4正在播放的节目项索引,从0开始编号2.10控制扩展开关SCL_SetExtSWBOOL SCL_SetExtSW(WORD nDevID,WORD OnOff);功能：控制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_PictToXMPFileBOOL SCL_PictToXMPFile(int colortype,int width,int height,BOOL bstretch, 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.2 XMP文件大小SCL_GetMaxFileSizeint SCL_GetMaxFileSize(int ScreenCount, BOOL bSmallest, BOOL bSCL2008);功能： 根据单个节目的分区数和播放该图片的区域是否为最小区域计算一个XMP文件的最大字节数。因为控制器在播放时根据当前节目的分区数自动分配文件预读缓冲区(边播放边将下一待播放的文件读入内存)，所以生成的XMP文件的大小不能超出缓冲区大小。本函数按照控制器的缓冲区分配算法获取XMP文件的最大长度。入口：ScreenCount：节目的分区数，1-4；bSmallest：当前计算的区域是否是最小区域；bSCl2008：控制器类型。FALSE:SuperComm，TRUE：SCL2008出口：以字节为单位的XMP文件大小4.3 合并XMP文件 SCL_AddXMPToXMPint SCL_AddXMPToXMP(char* InFilename, char* OutFilename,int MaxSize);功能：将两个XMP格式的图片文件合并为一个XMP文件入口：InFilename：包含一个或多个图片的XMP文件名(含路径)；OutFilename：包含一个或多个图片的XMP文件名(含路径)，若OutFilename不存在，则执行InFilename到OutFilename的拷贝操作；MaxSize：XMP文件的最大长度，使用SCL_GetMaxFileSize的返回值。要求InFilename和OutFilename中的图片的颜色类型、基本宽高都一致才可以合并。出口：若合并成功，返回0，否则返回错误代码： 1：InFilename不存在 2：InFilename打开失败 3：OutFilename打开失败 4：合并后的图片总数超过255 5：两个文件的版本不符(每点颜色类型不同) 6：两个文件中的图片的基本宽高不同 7：InFilename表示的文件，其大小与文件中定义的图片类型及大小不符(文件有损坏) 8：OutFilename表示的文件，其大小与文件中定义的图片类型及大小不符(文件有损坏) 9：合并后的文件大小超出MaxSize限定的最大长度第五章 使用字库5.1 装载字库SuperComm/SCL2008控制器支持多种字库。在第二章中已经介绍Config.LY中装载字库的指定。控制器提供最大8M空间存放字库，并且支持同时管理最多8套字库。必须小心的计算所有要装载的字库文件的大小。他们的总和不得大于8M字节。开发包中提供了一个自动生成汉字和西文字库的程序MakeFontLib.Exe。程序员可以利用它生成需要的字库，该程序运行完毕后，将会有CharCount、width和height信息，这些信息在字库需要装入时必须写入Config.LY文件中。MakeFontLib程序还可以生成旋转90度的字库。利用该字库，可以很简单的在垂直放置的显示板制作的屏上，按垂直方向输出文字(例如制作舞台两侧的歌词、唱词显示屏)，形成如下效果：5.2 文字显示信息ShowString函数的第一个参数是指向“文字显示信息”的指针。“文字显示信息”是一个记录类型，格式为：struct TextOutInfo WORD Left; WORD Top; WORD Width; WORD Height; LONG Color; WORD ASCFont; WORD HZFont; WORD XPos; WORD YPos;typedef struct TextOutInfo TEXTINFO;其中：Left、Top、Width、Height为文字输出区域的左上角坐标及区域的宽和高，Left和Top坐标是以控制器最大控制范围为基础的绝对坐标。控制器将自动在该区域中排版输出，即，当输出到区域的右边界，且在剩下的空间小于当前要输出的字符的宽度时，将自动换行到下一行的最左边继续输出；当输出到下边，且剩下的空间小于当前要输出的字符的高度时，控制器将终止在该区域的输出；该区域必须是节目表中划分的区域的一部分，不允许跨区域输出。Color为文字输出的颜色，符合计算机的标准24位颜色定义，即，在一个32位的长整数中，D23-D16为蓝色，D15-D8为绿色，D7-D0为红色；ASCFont为输出西文字符时选择的字库索引，该索引为Config.LY文件中装载字库的顺序，从1开始编号；HZFont为输出汉字字符或其它本地语言文字时选择的字库索引，该索引为ConFig.LY文件中装载字库的顺序，从1开始编号；XPos和YPos为输出文字的起点坐标；该坐标是以Left、Top定义的区域左上角为原点的相对坐标；控制器在上电时，按照Config.LY文件指定的顺序装载字库到内存。字库的索引值即是装载顺序。ASCII码字库和汉字字库(或其它本地语言文件字库)统一编制索引。字库指定规则：控制器在文字输出前，会使用已装载的索引值最小的ASCII字库为默认的ASCII字库，使用已装载的索引值最小的C类字库为默认的C类字库。当指定某类字库为索引值x的字库时，若对应的字库不是该类字库，则控制器将忽略该命令。例如，假设第1套、第2套字库为A类型，第3套、第4套为C类型，ASCFont指定使用第3套字库，HZFont指定使用第2套字库，则控制器使用第1套默认的A类字库，使用第3套默认的C类字库。5.3 扩展显示码文字串中，除了普通的ASCII码和国标汉字码外，在SuperComm/SCl2008中还定义了一些扩展操作代码，这些代码由字母(键盘上1左边的键，ASCII码0x60)或ESC(不可见，ASCII码0x1B)引导，后接一些命令字母。扩展显示码可用在简单通讯协议的文字显示、播放纯文本文件，以及立即文字显示中。：直接输出符号，例如：；A：ASCII字库索引。后接1个1-8之间的数字字符，对应“文字显示信息”中的ASCFont，表示从该定义之后的所有ASCII字符选用新的字库。例如：A3表示选用第三套字库；该指定将遵循前节介绍的“字库指定规则”；B：文字背景色。后接6个十六进制数字字符，表示文字输出的背景色。例如：B203fff表示背景色选择为蓝0x20绿0x3f红0xffC：文字前景色。后接6个十六进制数字字符，表示文字输出的前景色，对应“文字显示信息”中的Color。例如：C00ffff表示文字输出选择为蓝0绿0xff红0xff(黄色)D：文字输出方向。后接1个十进制数字字符，表示文字输出的方向，0：水平输出，1：垂直输出H：汉字字库索引。后接1个1-8之间的数字字符，对应“文字显示信息”中的HZFont，表示从该定义之后的所有汉字输出选用新的字库。例如：H1表示选用第一套字库；该指定将遵循前节介绍的“字库指定规则”；M：文字输出模式。后接1个1-3的数字，表示文字的输出模式。1：覆盖输出，2：叠加输出，3：反白输出。SCL2008不支持叠加输出模式；R：清除局部区域。后接4组3位共12位（SCL2008:4组4位共16位）十进制数字字符，每3个数字(SCL2008:每4个数字)分别表示一个区域左上角的x坐标、y坐标、区域宽度和区域的高度。该命令表示清除文字显示区域中的一个子区域。本扩展代码中的x坐标、y坐标为以文字输出区域的左上角为原点的相对坐标，所定义的区域必须是文字输出区域的子区域。例如：R008010096032表示清除文字显示区域中水平方向第8点到8+96点，垂直方向从第10点到10+32点的一个小区域；W：文字输出宽度。后接1位数字字符，可选择0或1，分别表示定宽或变宽方式输出文字。主要针对ASCII字库。某些字体中，一些字很宽，而另一些字很窄，例如I和W如果都按照字库定义的宽度来输出，可能视觉感觉不是很好，此时就可以用“W1”来要求控制器采用变宽方式输出。变宽方式下，每输出一个文字，下一文字的输出水平坐标为前一文字有效显示点之后间隔一个点。(SCL2008不支持变宽方式)；X：移动X坐标。后接3个十进制数字字符，表示下一文字输出的新的x坐标(以区域左上角为原点的相对坐标)；允许在3个十进制数字前加+或-号，如X-023，表示从当前点出发移动坐标(当前输出位置的相对坐标)；Y：移动Y坐标。后接3个十进制数字字符，表示下一文字输出的新的y坐标(以区域左上角为原点的相对坐标)；允许在3个十进制数字前加+或-号，如Y-001，表示从当前点出发移动坐标(当前输出位置的相对坐标)；Z：重定义输出区域。后接4组3位共12位（SCL2008:4组4位共16位）十进制数字字符，每3个数字(SCL2008：每4个数字)分别表示一个区域左上角的x坐标、y坐标、区域宽度和区域的高度。Z命令用来重新定义文字输出的区域(等于是重新给文字输出信息中的Left、Top、Width和Height赋值)。本扩展代码中的坐标为控制器最大范围内的绝对坐标。利用这些扩展定义码，可以输出很多特殊的效果。例如：假设第一套字库的宽高均为32，第2套字库的宽高均为16，则文字串“H1特殊显示H2第一行小字X128Y16第二行小字 ”将输出成如下效果： 又例如，“X002Y002C00FFFF镶边汉字X001Y003C0000FF镶边汉字 ”将输出成如下效果(SCL2008因不支持叠加模式，故不能形成该效果)：第六章 搜索.配置控制器6.1 搜索已配置的控制器如果需要在局域网中查找已经配置好的工作着的控制器，可以调用下面的三个函数：1、 开始查找BOOL SCL_SeekStart(WORD Delay,char *RemoteIP,WORD port,char *SubnetMask,BOOL bSCL2008);入口： Delay：查找过程中等待回应的时间，单位：秒RemoteIP：控制器的IP地址。若此处为空串，则可以在局域网内广播式查找，若给出一个IP地址，则只对指定对象取信息。指定IP地址可实现跨网段查找；Port：查找时使用的UDP端口号；SubNetMask：本地网络的子网掩码bSCL2008：TRUE表示查找SCL2008控制器，FALSE表示查找SuperComm控制器出口：返回TRUE表示已经正确初始化 Socket,并发出查找报文；返回FALSE表示启动失败,可能是因为端口被占用。2、 获取控制器返回的IP地址与助记名BOOL SCL_SeekGetAItem(char *IP, char *Name);入口：无出口：若返回TRUE，IP中有给回应答的控制器的IP地址，Name中有控制器的助记名；返回FALSE表示没有得到控制器的应答。3、 退出查找BOOL SCL_SeekClose(void);入口： 无出口：一般返回TRUE。查找结束后，应调用此函数释放通讯硬件。在查找同网段所有控制器的时候，先调用SCL_SeekStart，然后重复调用SCL_SeekGetAItem，依次获取所有控制器返回的应答，直到SCL_SeekGetAItem返回FALSE(表示再没有其它应答了)，最后调用SCL_SeekClose6.2 修改控制器的IP地址、助记名、子网掩码或网关初始化控制器的网络参数时，用到如下的一个数据结构：C: struct NetParaStru BYTE MAC6;Char Name16;BYTE IP4;BYTE NetMask4;BYTE GateWay4;typedef struct NetParaStru NetParaType;其中： MAC: 存放MAC 地址 N