0.4DLL接口方式
DLL接口作用
为了方便对接平台，我们将网络访问和URL协议签名部分封装成了DLL供大家使用。
这里下载：GuoPAPI DLL.zip
接口DLL文件名：GuoPAPI.dll,最新版本：3.1.1906.1901
注意：这个DLL只适用于静态DLL调用方式，不适用动态调用。（不清楚调用方式的区别，请先联系我们的技术支持）
此DLL，将代替原接口协议中需要轮询方式调用的6.1/1.1/2.1
DLL接口基本定义
一、DLL接口调用环节定义如下：
1.果盘平台：是指果盘线上业务平台
2.接口DLL：本文说明的GuoPAPI.dll
3.收银软件接口：收银软件为实现与果盘平台的对接而开发的接口程序，通过调用接口DLL与平台交互数据
二、数据交换文件定义：
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"
}
三、推送消息相关定义
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，则此消息被认为已处理，不再重复推送，也不需要再调用apiCall(1xxx)来反馈确认接收。
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;
}
}
四、接口交互流程
1、收银软件主动调用接口时，生成R1.json，生成文件后调用apiCall(1);调用返回后，直接读取T1.json。
线下主动调用接口的业务场景，消息文件编号固定是1，请不要设置为其它值！交互时序图如下：
2、接口DLL主动推送消息的情况(如线上订单、支付推送)，收银接口程序收到消息后直接读取文件，并根据文件的内容作相应的处理。
此业务场景下，所有交互文件的数字编号，以首次推送WINDOW消息使用的消息编号，直到这个业务完成。交互时序图如下：
DLL接口初始化函数
用于初始化接口，必须先进行一次初始化，才能调用后续的业务接口。否则会返回错误。
int _stdcall apiInit(char* 门店编号, char* ApiKey,int handle, char* extention)
参数说明：
1.门店编号，果盘后台的商家下的门店编号，参见0.1中的说明。
2.ApiKey，果盘商家的接口签名密钥，参见0.1中的说明。
3.handle，收银系统接口程序的窗口句柄，用于接收主动推送的消息通知，需要实现消息处理流程。
4.extention,扩展参数，扩展参数目前支持如下：（多个参数项之间用&分隔）
①指定数据文件格式：format=json,留空默认为。可选format=xml,format=ini。
②指定数据文件存放目录： datapath=Data，注意为相对DLL文件所在的目录。另外指定目录后所有Tx/T/R数据交换文件都在此目录下。
返回值：
返回1表示初始化成功，
返回非1表示初始化失败，具体错误信息在T1.json中。
业务接口函数
用于所有业务的接口调用。
int _stdcall apiCall(int msgid)
参数的说明：
msgid：消息编号，整数值。不同的场景下有不同的值。msgid必须与生成的数据文件R1001.json的编号相符
返回值：
返回值一般等于msgid。具体返回的消息内容在文件中。如msgid=1001时，返回数据文件为T1001.json
业务调用流程示例
1.线上订单推送流程
2.线上扫码秒付流程
关于调用和旧版更新
1.新版有两种工作模式：
a.网关工作模式，DLL中将启用消息服务，平台能及时发送订单到接口，用于接收订单、支付的网关的场景(网关模式普通接口也可以正常调用,如：菜品上传接口)。
b.普通接口模式，DLL仅作为主动调用的接口，用于收银系统主动发起调用的场景，如：扫码付、会员接口等。
2.两种模式启动方式：
a.网关工作模式，请在调用初始化接口时传入接收消息的Handle，进入网关工作模式
b.普通接口模式，请在调用初始化时handle=0
3.旧版DLL更新为新版：
目前只支持网关上使用的JuSAPI.dll更新为最新DLL库，（直接将GuoPApi.dll改名为JuSAPI.dll覆盖原文件即可）
普通接口调用模式请不要使用GuoPAPI.dll!
图片上传
图片上传按如下格式进行上传,以协议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';
调用：
初始化：
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