汉王签批控件接口说明文档v22.docx
《汉王签批控件接口说明文档v22.docx》由会员分享，可在线阅读，更多相关《汉王签批控件接口说明文档v22.docx（8页珍藏版）》请在冰豆网上搜索。
汉王签批控件接口说明文档v22
汉王签批控件接口说明文档-v2.2
汉王笔迹签名控件接口说明文档v2.2
控件使用平台
1.1操作系统平台
WindowsXP，WindowsVista，Windows7
1.2支持软件平台
（1）浏览器：
IE浏览器V2.0至目前IE的最高版本（V10.0）
采用IE内核的浏览器
注：
360、搜狗、傲游等浏览器，均是双核浏览器，即兼容模式下为支持IE内核模式，此时支持控件的加载。
极速模式下为采用了Chromium内核，此种模式下不支持加载控件。
当用户浏览签批控件所在的页面时，请将以上浏览器的模式切换至兼容模式，否则控件无法正常工作。
（2）支持com组件调用的应用程序中
1.3控件功能
控件为浏览器的子窗口（故不能创建透明的签名窗口），可在窗口内实现带压感的原笔迹手写签字。
提供接口支持笔形（压力笔/钢笔）、笔宽（共5级）、笔颜色、窗口边框宽度及颜色、窗口内部背景颜色的设置，支持一次性清除所有
控件接口
注：
为保证图像不失真，PC端控件显示窗口与设备窗口长宽比应一致。
因此，建议对于设备ESP370，设置控件窗口长宽比为8:
3。
对于设备ESP560，设置控件窗口长宽比为5:
3。
2.1函数返回值错误码
HW_eOk0成功
HW_eDeviceNotFound-1未找到对应的汉王手写设备
HW_eFailedLoadModule-2手写模块加载失败
HW_eFailedInitModule-3手写模块初始化失败
HW_eWrongImageFormat-4不支持的图片格式
HW_eNoSignData-5没有签名数据
HW_eInvalidInput-6无效输入参数
其它返回值，参见windows（WinError.h头文件中定义）常见错误码含义。
2.2基本接口
1.LONGHWInitialize（void）
函数功能：
手写模块初始化
参数说明：
返回值见2.1
2.LONGHWFinalize（void）
函数功能：
手写模块卸载
参数说明：
无
3.LONGHWClearPenSign（void）
函数功能：
清除笔迹
4.LONGHWSetPenMode（LONGflag）
函数功能：
设置笔模型
参数说明：
flag：
0->毛笔（默认）
1->钢笔
5.LONGHWSetPenWidth（LONGpenWidth）
函数功能：
设置笔宽
参数说明：
penWidth：
笔宽，提供1-5个级别的设置，默认为3级
6.LONGHWSetPenColor（OLE_COLORcolor）
函数功能：
设置笔的颜色（默认颜色为0x000000）
参数说明：
color：
颜色，格式为RGB
7.LONGHWSetBkColor（OLE_COLORcolor）
函数功能：
设置签名区域背景颜色
参数说明：
color：
颜色，无背景图片时设置,默认为白色
8.LONGHWSetCtlFrame（LONGlinewidth,OLE_COLORcolor）
函数功能：
设置边框宽度和颜色
参数说明：
linewidth：
边框宽度，0为无边框。
Color：
边框颜色
9.LONGHWSetFilePath（VARIANT&path）
函数功能：
设置签名图像的保存路径，确保输入路径的目标文件夹存在，若不存在，控件不创建。
参数说明：
path：
路径，支持图像格式为bmp，jpg，png，gif
注：
win7/vista存在写文件权限问题，因此不支持将保存路径设置为该操作系统盘盘符下。
10.LONGHWSaveFile（void）
函数功能：
保存文件
参数说明：
返回值见2.1
11.BSTRHWGetBase64Stream（LONGflag）
函数功能：
获取签字区域图像的base64流
参数说明：
flag：
0->bmp图像类型
1->jpg
2->png
3->gif
返回值：
签字图像对应的base64数据流
12.LONGHWSwitchMonitor（LONGmode,LONGctlapp）
函数功能：
显示器模式切换（镜像&扩展）
参数说明：
mode：
0–>汉王签批控件切换到扩展屏显示
1->汉王签批控件在主显示器显示
ctlapp:
0->保留，取值为0
注：
此接口仅适用于汉王手写液晶屏。
13.LONGHWSetExtWndHandle（LONGhWndHandle）
函数功能：
传递与控件通信的窗口句柄值
参数说明：
hWndHandle：
窗口句柄值
14.LONGHWLoadImage（VARIANT&pathBackImage）
函数功能：
給控件手写区域添加背景图片
参数说明：
pathBackImage–>背景图片路径，当背景图片大小与控件手写区域大小不一致
时，背景图片将被进行拉伸或缩放
返回值：
见2.1
注：
此接口仅适用于获取整个签字区域图像版本的控件。
15.LONGHWLoadBase64Stream（VARIANT&stream）
函数功能：
给控件手写区域添加背景图片
参数说明：
stream→背景图片的Base64数据流
返回值：
见2.1。
注：
此接口仅适用于获取整个签字区域图像版本的控件。
16.LONGHWIsNeedSave（void）
函数功能：
是否有需要保存的笔迹
参数说明：
无
返回值：
0→无笔迹1→有笔迹
17.voidHWSetSignArea（LONGwidth,LONGheight）
函数功能：
设置待获取的签字图像大小
参数说明：
width→签字图像的宽度
Height→签字图像的高度
注：
此接口仅支持无窗口版本的控件。
2.3签名动作的自动触发
2.3.1签名板
1、回调触发
签名板的签名界面上带有“重签”和“确认”按钮，用户签名完成后，点击按钮的动作，汉王签名控件可以捕获。
（一）应用系统的HTML页面通过JS代码引用汉王的签名板控件（ActiveX）。
（二）应用系统通过调用汉王控件接口函数HWInitialize开始签名；
（三）客户签名完成，点击签名界面下按钮进行重签、确认动作；
（四）ActiveX控件监听到客户的动作，调用应用系统HTML页面上的JS函数；
（五）应用系统调用汉王控件接口函数HWFinalize结束签名。
控件（ActiveX）与HTML页面上的回调函数存在以下对应关系：
1）“确定”按钮→调用HTML页面上的“signComplete”函数
2）“重签”按钮→调用HTML页面上的”signRestart”函数
客户可以根据需要自行实现上述“signComplete”和”signRestart”函数，完成签名动作的自动触发机制（如Demo.html页面所示在signComplete函数里调用HWGetBase64Stream接口获取签名图片。
）。
应用系统也可以不采用这种触发机制，而通过手动的方式去获取用户的签名图像，此时在应用系统的HTML页面中不实现“signComplete”和”signRestart”函数即可。
2、窗口消息触发
约定：
当用户点击签名板上的取消、确定按钮时，控件会往往以下窗口句柄发送签名取消或完成的消息（调用HWSetExtWndHandle接口传进来的窗口句柄）。
用户可在程序中响应对应的消息即可。
消息定义如下：
HW_SIGN_COMPELETE0x7ffe
HW_SIGN_CLEAR0x7ffd
2.3.2手写液晶屏
1、回调触发
手写液晶屏的左侧有4个按键，当用户触发按键时，控件可以捕获并回调页面函数。
具体步骤。
（一）应用系统的HTML页面通过JS代码引用汉王的签名板控件（ActiveX）。
（二）应用系统通过调用汉王控件接口函数HWInitialize开始签名；
（三）客户触发手写液晶屏左侧按键；
（四）ActiveX控件监听到客户的动作，调用应用系统HTML页面上的JS函数；
（五）应用系统调用汉王控件接口函数HWFinalize结束签名。
控件（ActiveX）与HTML页面上的回调函数存在以下对应关系：
1）“确认”按钮→调用HTML页面上的“Confirm_Event”函数。
2）“取消”按钮→调用HTML页面上的“Cancel_Event”函数。
3）“上翻”按钮→调用HTML页面上的“PrePage_Event”函数。
4）“下翻”按钮→调用HTML页面上的“NextPage_Event”函数
客户可以根据需要自行实现上述“Confirm_Event”、“Cancel_Event”、“PrePage_Event”、“NextPage_Event”函数，实现自动触发机制（如Demo.html页面所示依次在各个回调函数中给出弹框提示）。
2、窗口消息触发
约定：
当用户点击签名板上的取消、确定按钮时，控件会往往以下窗口句柄发送签名取消或完成的消息（调用HWSetExtWndHandle接口传进来的窗口句柄）。
用户可在程序中响应对应的消息即可。
消息定义如下：
HW_SIGN_COMPELETE0x7ffe→“确认”按钮
HW_SIGN_CLEAR0x7ffd→“取消”按钮
HW_PAGE_PREV0x7ffb→“上翻”按钮
HW_PAGE_NEXT0x7ffc→“下翻”按钮
备注
（1）接口使用方法可参考Demo.html文件。
（2）由于控件为浏览器的一个子窗口，故不能创建透明的签名窗口。
升级会员 