0.4DLL接口方式
DLL接口作用
为了方便对接平台，我们将网络访问和URL协议签名部分封装成了DLL方便对接使用。
这里下载：GuPAPI_DLL.zip
接口DLL文件名：GuoPAPI.dll,最新版本：3.2.2006.2301
最新更新：支持初始化参数clientver,以兼容do-sync
2019-10-17:
1.增加sys-notify消息通知下行推送，用于通知发送
2.多条消息不再等前一条确认接收后再发送，会出现并行发送，请注意处理
2019-10-22
1.增加本地缓存操作函数，cacheGet,cachePut,cacheLen，可用于排重等场景
2019-11-03
1.优化部分http请求返回异常的处理
2.新增本地缓存操作函数
2019-11-20
1.增加自动清除过期数据文件，默认保留7天
2.优化9100服务启动异常进行捕获
3.DLL包文件中默认包含SSL扩展，默认支持https
2019-12-16
1.优化初始化调用成功返回T1.json中增加返回datapath
2020-01-09
1.增加与JuSAPI.dll的兼容性
2.修改JuSApi.dll兼容模式下默认数据文件目录为./Data
2020-01-13
1.优化Init初始化出错时生成返回文件可靠性
2020-02-20
1.在线支付的订单，不推送do-new消息
2020-02-21
1.优化日志文件格式，可用LOG日志查看工具查看
2020-02-24
1.优化自动更新机制
2020-02-26
1.兼容新MQ推送格式
2.优化日志获取方式和自动更新机制
2020-02-27
1.修复DLL所在程序目录名称中有空格时导致初始化失败的问题
2020-04-13
1.增加支持Get参数中增加Seq来跟踪请求和返回
2.优化MQ连接、推送稳定性
2020-06-23
1.优化网络异常重连机制
2.优化订单推送补拉机制
3.优化接口初始化速度
注意：这个DLL只适用于静态DLL调用方式，不适用动态调用。（不清楚调用方式的区别，请先联系我们的技术支持）
此DLL，将代替原接口协议中需要轮询方式调用的6.1/1.1/2.1，并且新接口将不再支持轮询接口
https加密通道：
部分商家网络被劫持等原因，导致http请求异常，可以使用https通道进行API请求，DLL支持https请求方式。
DLL接口基本定义
一、DLL接口调用环节定义如下：
1.果盘平台：是指果盘线上业务平台
2.接口DLL：本文说明的GuoPAPI.dll
3.收银软件接口：收银软件为实现与果盘平台的对接而开发的接口程序，通过调用接口DLL与平台交互数据
二、DLL函数定义：
1.接口初始化函数：int _stdcall apiInit(char* 门店编号, char* ApiKey,int handle, char* extention)，用于初始化接口，接口程序退出前只需要调用一次。
2.业务接口函数：int _stdcall apiCall(int msgid)，用于所有上行业务接口的调用。
3.接口退出关闭函数：int _stdcall apiClose()，用于接口程序退出前调用,告知平台接口已退出。
4.缓存读取函数：int _stdcall cacheGet(char* key,char* value),读取指定缓存内容，内容在value变参中返回，函数返回值为缓存有效期剩余时间(单位秒)
5.缓存保存函数：int _stdcall cachePut(char* key,char* value,int expires),设置缓存内容，expires为缓存有效期（单位秒）
6.缓存读取函数：int _stdcall cacheLen(char* key),获取指定keykey名称缓存长度，-1表示缓存不存在
具体调用方式参照本文后续说明。三、数据交换文件定义：
1.数据采用文件交换方式，文件存在DLL同目录下。
2.文件内容数据格式：JSON,UTF-8格式，同时支持xml,ini格式，下面以json举例。
2.数据交换文件名第一部分，R为收银软件生成的文件，T、Tx为接口DLL生成的文件。第二部分为数字编号，一般为1、1001或更大，表示消息序号。文件后缀为.json
3.收银软件生成的文件R1.json，第一位R是固定的，后面的数字编号根据场景不同。
4.接口DLL生成的文件T1.json,第一位T是固定的，后面的数字编号根据场景不同，但一次请求R/T,请求/返回的数字编号是相同的。
5.特殊情况：接口DLL主动推送消息时，生成的文件名为Tx1001.json（其中1001为window消息体中LParam的值，此处以1001示例）。
6.交互文件格式范例：
以取消订单（协议1.7do_cancel为例)，请求R1.json文件内容：
{
"action": {
"action": "do_cancel"
},
"get": {
"id": 3738173,
"op": "user"
}
}
调用apiCall(1);返回的T1.json内容：
{
"status": 1,
"info": "提交成功",
"payid": 6383378,
"refund_status": 1,
"refund_info": "退款成功"
}
一个典型的错误返回，T1.json内容
{
"status": 0,
"info": "订单号不存在:55837"
}
DLL接口初始化函数
用于初始化接口，必须先进行一次初始化，才能调用后续的业务接口。否则会返回错误。
int _stdcall apiInit(char* 门店编号, char* ApiKey,int handle, char* extention)
参数说明：
1.门店编号，果盘后台的商家下的门店编号，参见0.2中的说明。
2.ApiKey，果盘商家的接口签名密钥，参见0.2中的说明。
3.handle，收银系统接口程序的窗口句柄，用于接收主动推送的消息通知，需要实现消息处理流程。
4.extention,扩展参数，扩展参数目前支持如下：（多个参数项之间用&分隔）(应用id、应用密钥参见0.2说明)
① 应用ID（必填），例如：gpid=gp13************df
② 应用密钥（必填），例如: gpsecret=30461a27b7b0871c********************1756
③指定数据文件格式：format=json。可选format=xml,format=ini,默认为json。
④ 指定数据文件存放目录： datapath=Data，注意为相对DLL文件所在的目录。另外指定目录后所有Tx/T/R数据交换文件都在此目录下。
⑤指定门店API接口协议：clientver=3.2，指定3.2版本表示已经实现do-sync协议对接，需要DLL版本3.2.x.x以上才能支持。
返回值：
返回1表示初始化成功，
返回非1表示初始化失败，具体错误信息在T1.json中。
DLL工作模式
1.DLL有两种工作模式：
a.网关工作模式，DLL中将启用消息服务（下行接口服务），平台能及时发送消息到接口，用于接收订单、支付的网关的场景(网关模式普通接口也可以正常调用,如：菜品上传接口)。
b.普通接口模式，DLL仅作为主动调用的接口(上行接口)，用于收银系统主动发起调用的场景，如：扫码付、会员接口等。
2.两种模式启动方式：
a.网关工作模式，请在调用初始化接口时传入接收消息的Handle，进入网关工作模式（注意：一个门店只能开一个网关模式接口，多开会导致冲突）
b.普通接口模式，请在调用初始化时handle=0
下行接口交互流程
接口DLL主动推送消息的情况(如线上订单、支付推送)，收银接口程序收到消息后直接读取文件，并根据文件的内容作相应的处理。
此业务场景下，所有交互文件的数字编号，以首次推送WINDOW消息使用的消息编号，直到这个业务完成。交互时序图如下：
1.推送使用发送Window消息给收银软件接口程序的方式。
2.消息ID：WM_GPAPI_PUB=WM_USER+1883（或者直接2907）
3.消息中LParam=1001为一个整数，表示消息流水编号，为自增编号，一定时间内不会重复。
4.当LParam=1001时，对应消息数据文件名为Tx1001.json
5.重要：调用初始化时，DLL会向传入的窗口Handle发送一个握手消息，标志是消息体WParam = 1,请直接返回200即可（或者没有返回值），WParam=0的情况为正常的业务推送消息,请注意判断。
6.window自定义消息接收方式：
Delphi:
const WM_GPAPI_PUB = WM_USER+1883;
procedure onGPAPIMessage(var msg: TMessage): message WM_GPAPI_PUB;
begin
if(msg.WParam=1) then //握手消息，返回200，(777表示接收状态日志消息,WM_COPYDATA)
begin
msg.Result :=200;
end
else if msg.WParam=0 then
begin
sFile := 'Tx'+intToStr(msg.LParam)+'.json';
//todo: 业务处理流程
msg.Result := 200; //如果此消息类型不想处理，或是需要异步处理，可以此处直接返回 666，则此消息不再重复推送。
end;
end;
PB:
在PB中是窗口的OTHER事件里进行消息判断
ifmessage.number= 2907then
执行你的处理
return1
else
return0
endif
C#
public const int WM_GPAPI_PUB =USER+1883;
protected override void DefWndProc ( ref System.Windows.Forms.Message m )
{
switch(m.Msg)
{
case Message.WM_GPAPI_PUB:
//处理消息
break;
default:
base.DefWndProc(ref m); //调用基类函数处理非自定义消息。
break;
}
}
上行接口交互流程
收银软件主动调用接口时，生成R1.json，生成文件后调用apiCall(1); 调用返回后，直接读取T1.json。
线下主动调用接口的业务场景，消息文件编号固定是1，请不要设置为其它值！交互时序图如下：
上行业务接口函数
用于所有业务的接口调用。
int _stdcall apiCall(int msgid)
参数的说明：
msgid：消息编号，整数值。不同的场景下有不同的值。msgid必须与生成的数据文件R1001.json的编号相符
返回值：
返回值一般等于msgid。具体返回的消息内容在文件中。如msgid=1001时，返回数据文件为T1001.json
业务调用流程示例
1.线上订单推送流程
2.线上扫码秒付流程
图片上传
图片上传按如下格式进行上传,以协议3.2上传菜品图片为例，
R1.json文件如下：调用apiCall(1);
{
"action": {
"action": "do_upload_pic"
},
"get": {
"gdsid": "000100276"
},
"post": {
"file": "U:\\20180817111115_79987.jpg"
}
}
调用示例
Delphi调用示例：
函数声明
function apiInit(const shopid: pansichar; const ApiKey: pansichar; const Handle: integer=0; const Extention:pansichar=0): integer;stdcall; external 'GuoPAPI.dll';
function apiCall(const MsgId: integer): integer; stdcall; external 'GuoPAPI.dll';
function apiClose(): integer; stdcall; external 'GuoPAPI.dll';
function cacheGet(const key:pansichar;value:pansichar): integer; stdcall; external 'GuoPAPI.dll';
function cachePut(const key:pansichar;const value:pansichar;expires: integer): integer; stdcall; external 'GuoPAPI.dll';
function cacheLen(const key:pansichar): integer; stdcall; external 'GuoPAPI.dll';调用：
初始化：
apiInit(PAnsiChar(shopId),PAnsiChar(APiKey),handle,PAnsiChar(format));
接口调用：
apiCall(1001);
PB11 调用示例：初始化
FUNCTION int apiInit(ref string msid, ref string apikey, long handle, ref string ext) LIBRARY "GuoPAPI.dll" ALIAS FOR "apiInit;ansi"
FUNCTION int apiCall(int msgid) LIBRARY "GuoPAPI.dll" ALIAS FOR "apiCall;ansi"
PB9 调用示例：
初始化
FUNCTION int apiInit(string msid, string apikey, long handle, string ext) LIBRARY "GuoPAPI.dll"
FUNCTION int apiCall(int msgid) LIBRARY "GuoPAPI.dll"
调用示例：
string ls_no ,ls_apikey
string ls_templong i,h_wnd
ls_no = sle_1.text
ls_apikey = sle_2.text
h_wnd = handle(frmMain)
i = apiInit(ls_no, ls_apikey, h_wnd)
string str1 ,str2, s
BLOB STR3 ,blob1 , blob2
str1 = sle_3.Text
str2 = sle_4.Text
///todo: save data to R1.json
///
i = apiCall(1);////todo: load data from T1.json
VB声明示例：
Public Declare Function apiInit Lib "GuoPAPI.dll" (ByVal msid As String, ByVal apikey As String, ByVal handle As Long, ByVal ext As String) As Integer
Public Declare Function apiCall Lib "GuoPAPI.dll" (ByVal msgid As Integer) As Integer