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事件里进行消息判断

if message.number = 2907 then
   执行你的处理
   return 1
else
   return 0
end if

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_temp
long 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