SP接入API(win32)使用手册

短信的资料

SP接入API使用手册

1 说明

为了降低SP接入联通在信系统的难度，加快SP接入的速度，傲天公司推出本套

SP接入API，使用该API，SP不用关心网络连接处理，线程控制和SGIP协议，只用

关心具体的业务流程处理。

2 API结构

该API以事件驱动的方式工作，调用初试始化函数Startup后，一系列线程组件开

始运行，包括Submit发送线程，连接监听线程，Deliver接收和处理线程等。当SP调

用Submit函数时，Submit处理线程自动生成Submit协议包并将该包发送给网关系统，

同时接收网关的Submit Response，如果用户定义了Response处理函数，则触发Response

事件，调用该函数。当收到网关的Deliver或Report时，Deliver处理线程会自动触发相

应事件，调用用户定义的业务处理函数。对网关系统的连接管理由API自动完成。

3 变量类型定义

C++ ：

typedef unsigned char UINT_1;

typedef unsigned short UINT_2;

typedef unsigned int UINT_4;

//Deliver包结构

typedef struct deliverstr

{

UINT_4 sequencenumber1;

UINT_4 sequencenumber2;

UINT_4 sequencenumber3;

char usernumber[22]；

char spnumber[22];

UINT_1 tp_pid;

UINT_1 tp_udhi；

UINT_1 messagecoding；

UINT_4 messagelength；

char messagecontent[160]；

}DeliverStr;

短信的资料

//Report包结构

typedef struct reportstr

{

UINT_4 sequencenumber1；

UINT_4 sequencenumber2；

UINT_4 sequencenumber3；

char usernumber[22]；

UINT_1 state；

UINT_1 errcode;

}ReportStr;

//MT Response结构

typedef struct mtrespstr

{

UINT_4 sequencenumber1；

UINT_4 sequencenumber2；

UINT_4 sequencenumber3；

UINT_1 result；

}MTRespStr;

//Submit错误结构,当Submit发送不成功时，在Deliver处理中返回该结构

typedef struct mterrorstr

{

UINT_4 sequencenumber1;

UINT_4 sequencenumber2;

UINT_4 sequencenumber3;

INT_4 errortype ; //1：因为连接不上SMG网关系统，导致包超时 2：发送前发现该包超

时 3：包发送失败且超过重发次数

INT_4 result;//如果失败是因为对方回了错误的Response，则result中保留错误的Response

Result值，否则是内部的错误码：负值。

}MTErrorStr;

Delphi：

//Report包结构

type

ReportStr = packed Record

sequencenumber1: LongInt;

sequencenumber2: LongInt;

sequencenumber: LongInt;

usernumber: packed Array[0..21] of char;

state: char;

errcode: char;

end;

短信的资料

//Deliver包结构

type

DeliverStr = packed record

sequencenumber1: LongInt;

sequencenumber2: LongInt;

sequencenumber3: LongInt;

usernumber: packed array[0..21] of char;

spnumber: packed array[0..21] of char;

tp_pid: char;

tp_udhi: char;

messagecoding: char;

messagelength: integer;

messagecontent: packed array[0..159] of char;

end;

//MT Response包结构

type

MTRespStr = packed record

sequencenumber1: LongInt;

sequencenumber2: LongInt;

sequencenumber3: LongInt;

result: char;

end;

//Submit错误结构,当Submit发送不成功时，在Deliver处理中返回该结构

type

MTErrStr = packed record

sequencenumber1: LongInt;

sequencenumber2: LongInt;

sequencenumber3: LongInt;

errortype: integer;

end;

4 接口函数

4.1 Strartup

int

char* Startup(char* cLocalIp,short iLocalPort,char* cSmgIp,short iSmgPort, cLoginName,char* cPassword,int lSocketTimeOut,int lMTTimeOut,

短信的资料

int iSrcNode,int lMTThread,int lMaxListNode,int lMTMaxRetryTime,int lMOThread,

void (* fProcessDeliver)(DeliverStr deliver),

void (* fProcessReport)(ReportStr report),

void (* fProcessResponse)(MTRespStr response),

void (*fProcessMTError)(MTErrorStr mterror));

该函数是API的初始化函数，在使用API前，必须调用该函数

参数说明：

cLocalIp：本地IP地址

iLocalPort：本地Socket监听端口

cSmgIp：网关系统IP

cSmgPort：网关系统监听端口

cLoginName：连接网关的用户名

cPassword：连接网关的密码

lSocketTimeOut：Socket超时（秒）

lMTTimeOut：Submit的超时，在超时的时间内，如果该MT没有成功发送，

则返回错误包，MTErrorStr

iSrcNode：SP节点编号

lMTThread：Submit处理线程数

lMaxListNode：最大待处理队列节点数

lMTMaxRetryTime：Submit发送失败重试次数

lMOThread：Deliver处理线程数

deliver：用户定义的Deliver处理函数（为NULL时不处理Deliver包）

report：用户定义的Report处理函数（为NULL时不处理Report包）

response：用户定义的Submit Response处理函数（为NULL时不处理Submit

Response包）

mterror：用户定义的错误处理函数（为NULL时不处理错误包）

返回值：

0、已经调用了Startup

1、 成功

-1、失败

4.2 Submit

SP发送消息时调用该函数，函数的输入参数与SGIP协议中Submit消息包的内容想对

应

int Submit(char* spnumber,

char* chargenumber,

int user_count,

char* usernumber,

char* corpid,

char* service_type,

UINT_1 fee_type,

char* fee_value,

短信的资料

char* given_value,

UINT_1 agent_flag,

UINT_1 mo_flag,

UINT_1 priority,

char* expire_time,

char* schedule_time,

UINT_1 report_flag,

UINT_1 tp_pid,

UINT_1 tp_udhi,

UINT_1 message_coding,

UINT_1 message_type,

UINT_4 message_length,

char* message_content,

char* reserve,

UINT_4 *sequencenumber1,

UINT_4 *sequencenumber2,

UINT_4 *sequencenumber3)

参数说明：

spnumber：SP的接入号码

ChargeNumber：付费号码

user_count：接收手机用户个数

usernumber：接收该短消息的手机号，多个号码间以“；”或“，”隔开

corpId：企业代码

service_type：业务代码

fee_type：计费类型

fee_value：该条短消息的收费值

given_value：赠送用户的话费

agent_flag：代收费标志

mo_flag：引起MT消息的原因

priority：优先级

expire_time：短消息寿命的终止时间

schedule_time：短消息定时发送的时间

report_flag：状态报告标记

tp_pid：GSM协议类型

tp_udhi：GSM协议类型

message_coding：短消息的编码格式

message_type：信息类型

message_length：短消息内容的长度

message_content：短消息的内容

reserve：保留

sequencenumber1,sequencenumber2,sequencenumber3：短消息序列号，由API

按协议规范生成，并返回

返回值：

0：队列满

短信的资料

1：成功放入队列 -1：放入队列失败

4.3 Deliver处理函数

void (* fProcessDeliver)(DeliverStr deliver)

用户自定义的业务处理函数，作为指针传递给Startup。

注意：

该函数必须是线程安全的，其中访问的全局变量必须采用同步机制，如果SP使用

的开发工具为C++Builder或Delphi，对VCL的调用可采用发送消息的方式来同步

（SendMessage或PostMessage）。

4.4 Report处理函数

void (* fProcessReport)(ReportStr report)

注意：

同上

4.5 MT Response处理函数

void (* fProcessResponse)(MTRespStr response)

注意：

同上

4.6 Cleanup

int Cleanup()

该函数清空所有初始化内容，结束运行。

4.7 Deliver

int Deliver(int *type,DeliverStr* DeliverStruct,ReportStr* ReportStruct,MTRespStr*

RespStruct，MTErrorStr* MTErrorStruct)

当用户不采用事件触发的机制，而是自己取得Deliver包时，调用该函数，这时必须将Startup

中的lMOThread设置为0，并不提供处理包的函数函数根据取得包的类型返回不同的结构。

参数说明：

type：返回包的类型，1：Deliver包，2：Report包，3：MT Response包,4：

短信的资料

Submit错误包

DeliverStruct：当Type=1时返回

ReportStruct：当Type=2时返回

RespStruct：当Type=3时返回

MTErrorStruct：当Type=4时返回

返回值：

0：取得最后一个包

1：取得一个包

-1：取包错误或未取到包

5 范例

1、先定义DLL中的外部函数：

C++ ：

extern "C" __declspec(dllimport) int Startup(char* cLocalIp,short iLocalPort,char*

cSmgIp,short iSmgPort, char* cLoginName,char* cPassword,int

lSocketTimeOut,int lMTTimeOut, int iSrcNode,int lMTThread,int

lMaxListNode,int lMTMaxRetryTime,int lMOThread,

void (* fProcessDeliver)(DeliverStr deliver),

void (* fProcessReport)(ReportStr report),

void (* fProcessResponse)(MTRespStr response),

void (*fProcessMTError)(MTErrorStr mterror));

extern "C" __declspec(dllimport) int Cleanup();

extern "C" __declspec(dllimport) int Submit(char* spnumber,

char* chargenumber,

int user_count,

char* usernumber,

char* corpid,

char* service_type,

UINT_1 fee_type,

char* fee_value,

char* given_value,

UINT_1 agent_flag,

UINT_1 mo_flag,

UINT_1 priority,

char* expire_time,

char* schedule_time,

UINT_1 report_flag,

UINT_1 tp_pid,

UINT_1 tp_udhi,

UINT_1 message_coding,

短信的资料

UINT_1 message_type,

UINT_4 message_length,

char* message_content,

char* reserve,

UINT_4 *sequencenumber1,

UINT_4 *sequencenumber2,

UINT_4 *sequencenumber3);

Delphi：

function StartUp(cLocalIp: pchar; iLocalPort: integer; cSmgIp: pchar; iSmgPort: integer;

cLoginName,cPassword: pchar;

lSocketTimeOut,lMTTimeOut,iSrcNode,lMTThread,lMaxListNode,lMTMaxRetryTime

,lMOThread: integer;deliver: TDeliver; aa,bb,cc: pointer): integer;cdecl;external

'SGIP.DLL' name '_Startup';

function Submit(spnumber,chargenumber: pchar; user_count: integer;

usernumber,corpid,service_type: pchar;

fee_type: char; fee_value,given_value: pchar; agent_flag,mo_flag,priority: char;

expire_time,schedule_time: pchar;

report_flag,tp_pid,tp_udhi,message_coding,message_type: char;

message_length: LongInt; message_content,reserve: pchar;

var sequencenumber1,sequencenumber2,sequencenumber3: LongInt):

integer;cdecl;external 'SGIP.DLL' name '_Submit';

2、定义业务处理函数

C++ ：

void PDeliver(DeliverStr deliver);

void PReport(ReportStr report);

void PResponse(MTRespStr response);

void Perror(MTErrorStr mterror);

void PDeliver(DeliverStr deliver)

{

…

//对于全局变量加锁

CountLock->Enter();

DeliverCount++;

CountLock->Leave();

…

…

}

Delphi：

type TDeliver = procedure(deliver: DeliverStr);

3、调用初始化函数

C++ ：

Startup("192.168.0.1",8801, "192.168.0.2",9881,"openet","openet",

30,60,330006,1,5000,5,1,PDeliver,PReport,PResponse,PMTError);

短信的资料

Delphi：

StartUp('192.168.0.224',8801,'192.168.0.222',9881,'openet','openet',30,60,336666,

1,5000,5,1,Deliver,nil,nil,nil)

4、调用Submit函数发送消息

void __fastcall TForm1::Button1Click(TObject *Sender)

{

UINT_4 sequencenumber1;

UINT_4 sequencenumber2;

UINT_4 sequencenumber3;

Submit("9777", "8613028890583",3,

"8613028890583,8613028899991;8613028890584", "107222","11",1,

"100","0",0,0,0,"2001010101","2001010102",0, 0, 0, 0, 0, 6,"okokok","",&sequencenumber1,

&sequencenumber2, &sequencenumber3);

}

5、退出，清除

Cleanup();

本文来源：https://www.bwwdw.com/article/wwu4.html