SP接入API使用指南.docx

SP接入API使用指南.docx

《SP接入API使用指南.docx》由会员分享，可在线阅读，更多相关《SP接入API使用指南.docx（17页珍藏版）》请在冰豆网上搜索。

SP接入API使用指南

SP接入API使用指南

版本：

1.2

深圳市傲天信息技术有限公司

深圳市高新科技园南区科技南十路深圳国际技术创新研究院二楼A座

邮政编码：

518057

电话：

86-755-26727239

本文档描述了SP接入API的使用说明，供使用人员参考。

第一章概述2

1.1系统简介2

1.2系统设计原则3

1.3术语说明3

第二章系统结构4

2.1结构说明4

2.2系统结构图4

2.3系统应用环境5

2.4系统开发环境5

第三章接口函数说明6

3.1函数说明格式6

3.2数据结构定义6

3.2.1Deliver包结构6

3.2.2Report包结构6

3.2.3MTResponse结构7

3.2.4Submit错误结构7

3.3函数功能介绍8

3.3.1Startup（系统初始化函数）8

3.3.2Submit（下发消息函数）9

3.3.3Deliver（Deliver包处理函数）11

3.3.4Report（Report包处理函数）11

3.3.5MTResponse（MTResponse包处理函数）11

3.3.6取包函数12

第一章概述

本章首先简要介绍了傲天公司的短信网关平台（MUSESMG），然后描述了API的设计目标及原则。

1.1系统简介

MUSESMG（短信网关）为SP提供了一个具有全网互连功能的短消息接入平台，为电信运营商、SP开展全国性的短消息业务提供了承载功能，借助这个通道，SP可以向手机用户提供短消息增值服务。

随着短消息增值业务的不断发展，越来越多有着丰富特色的SP希望尽快接入到该平台上，为广大的手机用户提供各种应用，同时也使自己获得可观的利益。

由于SP与网关平台之间相连是采用SGIP协议来实现的，SP必须在熟悉SGIP协议的前提下才能进行开发，这样就增加了开发难度，也延长了SP接入的时间。

基于这种情况，傲天公司凭借自己在网关开发及协议理解方面的优势，开发了这套API。

通过使用API，SP在不熟悉协议的情况下也可以快速的开发自己的服务程序，将更多的精力放在自己的业务流程处理上，从而在短时间内创造效益。

1.2系统设计原则

●模块化

系统的功能设计按流程的要求实行模块化，以利于系统的开发和对系统的理解、使用。

●稳定性

性能稳定，能满足每秒发送/接受100条短信的要求。

●灵活性

系统结构应具有伸缩性，配置灵活。

●实用性

系统应处理好网络连接及协议封装，做到与业务无关。

1.3术语说明

SPServiceProvider，内容提供商

SMGShortMessageGateway，联通管理人员的短消息网关，SMG之间的通讯协议

采用SGIP

SGIPShortMessageGatewayInterfaceProtocol，本协议所描述的短消息网

关接口协议，用于完成在SMG和SP之间、SMG和SMG之间短消息的发

送、接收和转发功能，以及SMG和GNS之间路由表的同步功能

SMSCShortMessageServiceCenter，短消息中心

MO由手机用户提交的短消息

MT由手机用户接收的短消息

DeliverSMG用Deliver命令向SP发送MO消息

SubmitSP用Submit命令向SMG提交MT消息

ReportReport命令用于向SP发送一条先前的Submit命令的当前状态，或者用于向前转SMG

发送一条先前的Deliver命令的当前状态

第二章系统结构

本章描述了API内部的结构及应用、开发环境。

2.1结构说明

系统采用事件驱动的方式工作，当调用初始化函数Startup后，一系列线程组件开始运行，包括Submit发送线程、连接监听线程、Deliver接收和处理线程等。

当SP调用Submit函数时，Submit处理线程会自动生成Submit协议包并将该包发送给网关系统，同时接收网关返回的SubmitResponse，如果用户定义了Response处理函数，则触发Response事件，调用该函数。

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

2.2系统结构图

2.3系统应用环境

适用操作系统：

Windows98/NT/2000

适用开发工具：

VC5.0/6.0;VB6.0;C++Builder5.0/6.0;Delphi5.0/6.0

2.4系统开发环境

操作系统：

Windows2000

开发工具：

C++Builder6.0

第三章接口函数说明

3.1函数说明格式

每个函数按以下顺序进行介绍：

【函数功能】：

简要介绍函数所实现的功能。

【函数原型】：

给出该函数的标准C语言原型

【参数说明】：

给出每个参数的简要说明及输入、输出。

【使用说明】：

给出函数在使用时需要注意的问题。

3.2数据结构定义

下面给出函数调用中所用到的参数类型及结构定义，按照C语言进行解释。

其它语言的定义请参照使用范例。

TypedefunsignedcharUINT_1;

TypedefunsignedshortUINT_2;

TypedefunsignedintUINT_4;

3.2.1Deliver包结构

Typedefstructdeliverstr

{

UINT_4sequencenumber1;

UINT_4sequencenumber2;

UINT_4sequencenumber3;

charusernumber[22]；

charspnumber[22];

UINT_1tp_pid;

UINT_1tp_udhi；

UINT_1messagecoding；

UINT_4messagelength；

charmessagecontent[160]；

charlinkid[8];

}DeliverStr;

3.2.2Report包结构

Typedefstructreportstr

{

UINT_4sequencenumber1；

UINT_4sequencenumber2；

UINT_4sequencenumber3；

charusernumber[22]；

UINT_1state；

UINT_1errcode;

}ReportStr;

3.2.3MTResponse结构

Typedefstructmtrespstr

{

UINT_4sequencenumber1；

UINT_4sequencenumber2；

UINT_4sequencenumber3；

UINT_1result；

}MTRespStr;

3.2.4Submit错误结构

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

Typedefstructmterrorstr

{

UINT_4sequencenumber1;

UINT_4sequencenumber2;

UINT_4sequencenumber3;

interrortype;

/*1：

因为连接不上SMG网关系统，导致包超时；

2：

发送前发现该包超时；

3：

包发送失败且超过重发次数；

*/

intresult;

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

误的ResponseResult值，否则返回内部错误码：

负值。

-1非法登录

-2重复登录

-3登录类型错

-4登录过多

-5参数格式错

-6非法接收号码

-7消息ID错

-8信息超长

-32系统失败

*/

}MTErrorStr;

3.3函数功能介绍

3.3.1Startup（系统初始化函数）

【函数功能】

API初始化函数。

应用程序必须首先调用该函数。

【函数原型】

int__stdcallStartup（char*cLocalIp,

shortiLocalPort,

char*cSmgIp,

shortiSmgPort,

char*cLoginName,

char*cPassword,

intlSocketTimeOut,

intlMTTimeOut,

unsignedintiSrcNode,

intlMTThread,

intlMaxListNode,

intlMTMaxRetryTime,

intlMOThread,

void（*fProcessDeliver）（DeliverStrdeliver）,

void（*fProcessReport）（ReportStrreport）,

void（*fProcessResponse）（MTRespStrresponse）,

void（*fProcessMTError）（MTErrorStrmterror））;

【参数说明】

cLocalIp：

SP的IP地址（即应用程序所在机器的IP地址，且必须是公网IP）

iLocalPort：

SP作为服务器时的Socket监听端口

cSmgIp：

SMG的IP地址

cSmgPort：

SMG作为服务器时的Socket监听端口（由联通管理人员分配）

cLoginName：

SP作为客户端登录网关的用户名（由联通管理人员分配）

cPassword：

SP作为客户端登录网关的密码（由联通管理人员分配）

lSocketTimeOut：

Socket超时（秒）

lMTTimeOut：

Submit的超时，在超时的时间内，如果该MT没

有成功发送，则返回错误包MTErrorStr

iSrcNode：

SP节点编号（编号规则是3AAAAQQQQQ。

其中， AAAA表示四

位长途区号（不足四位的长途区号，左对齐，右补零。

可不填），QQQQQ

表示5位企业代码，由联通管理人员分配）

lMTThread：

Submit处理线程数

lMaxListNode：

最大待处理队列节点数

lMTMaxRetryTime：

Submit发送失败重试次数

lMOThread：

Deliver处理线程数

deliver：

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

report：

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

response：

用户定义的SubmitResponse处理函数（为NULL时不处理Submit

Response包）

mterror：

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

返回参数：

0：

已经调用了Startup

1：

调用成功

-1：

调用失败

【使用说明】

该函数采用标准的Win32API调用（stdcall）。

声明外部函数时需加上stdcall修

饰符。

3.3.2Submit（下发消息函数）

【函数功能】

发送Submit包。

SP向手机用户下发消息时调用该函数。

【函数原型】

int__stdcallSubmit（char*spnumber,

char*chargenumber,

intuser_count,

char*usernumber,

char*corpid,

char*service_type,

UINT_1fee_type,

char*fee_value,

char*given_value,

UINT_1agent_flag,

UINT_1mo_flag,

UINT_1priority,

char*expire_time,

char*schedule_time,

UINT_1report_flag,

UINT_1tp_pid,

UINT_1tp_udhi,

UINT_1message_coding,

UINT_1message_type,

UINT_4message_length,

char*message_content,

char*reserve,

UINT_4*sequencenumber1,

UINT_4*sequencenumber2,

UINT_4*sequencenumber3）

【参数说明】

spnumber：

SP的接入号码（由联通管理人员分配）

chargenumber：

付费号码（手机号码前加“86”国别标志；当且

仅当群发且对用户收费时为空；如果为空，则该条短消息产生的费用由

usernumber代表的用户支付；如果为全零字符串

“000000000000000000000”，表示该条短消息产生的费用由SP支付。

）

user_count：

接收短消息的手机数量，取值范围1至100

usernumber：

接收该短消息的手机号，手机号码前加“86”国别标志，多个号

码间以“；”或“，”隔开

corpId：

企业代码（由联通管理人员分配）

service_type：

业务代码（由SP自己定义，如“笑话”定义为“XH”）

fee_type：

计费类型，定义如下：

1－对“计费用户号码”免费

2－对“计费用户号码”按条计信息费

3－对“计费用户号码”按包月收取信息费

4－对“计费用户号码”的收费是由SP实现

fee_value：

该条短消息的收费值，单位为分，由SP定义，取值范围0-99999，对于包月制收费的用户，该值为月租费的值

given_value：

赠送用户的话费，单位为分，由SP定义，取值范围0-99999，

特指由SP向用户发送广告时的赠送话费

agent_flag：

代收费标志（0：

应收1：

实收）

mo_flag：

引起MT消息的原因，定义如下：

0－MO点播引起的第一条MT消息；

1－MO点播引起的非第一条MT消息；

2－非MO点播引起的MT消息；

3－系统反馈引起的MT消息。

priority：

优先级0-9从低到高，默认为0

expire_time：

短消息寿命的终止时间

schedule_time：

短消息定时发送的时间

report_flag：

状态报告标记，定义如下：

0－该条消息只有最后出错时要返回状态报告

1－该条消息无论最后是否成功都要返回状态报告

2－该条消息不需要返回状态报告

3－该条消息仅携带包月计费信息，不下发给用户，要返回状态报告

tp_pid：

GSM协议类型

tp_udhi：

GSM协议类型

message_coding：

短消息的编码格式，定义如下：

0－纯ASCII字符串

3－写卡操作

4－二进制编码

8－UCS2编码

15－GBK编码

message_type：

信息类型（短信息填0）

message_length：

短消息内容的长度

message_content：

短消息的内容

reserve：

保留

sequencenumber1,sequencenumber2,sequencenumber3：

短消息序列号，由API

按协议规范生成，并返回

返回参数：

0：

队列满

1：

成功放入队列

-1：

插入队列失败

【使用说明】

该函数采用标准的Win32API调用（stdcall）。

声明外部函数时需加上stdcall修

饰符。

3.3.3Deliver（Deliver包处理函数）

【函数功能】

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

用户可在此函数中根据

自己的业务来处理相应的Deliver包。

【函数原型】

void（*fProcessDeliver）（DeliverStrdeliver）

【参数说明】

deliver：

DeliverStr类型的参数。

【使用说明】

该函数采用标准的Win32API调用（stdcall）。

声明外部函数时需加上stdcall修

饰符。

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

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

（SendMessage或PostMessage）。

用户在解包的时候需要根据短信编码格式MessageCoding来对消息内容MessageContent做相应的处理。

3.3.4Report（Report包处理函数）

【函数功能】

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

用户可在此函数中自定

义如何处理网关返回的Report。

【函数原型】

void（*fProcessReport）（ReportStrreport）

【参数说明】

report：

ReportStr类型的参数。

【使用说明】

同Deliver处理函数。

3.3.5MTResponse（MTResponse包处理函数）

【函数功能】

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

用户可在此函数

中自定义如何处理网关返回的MTResponse。

【函数原型】

void（*fProcessResponse）（MTRespStrresponse）

【参数说明】

response：

MTRespStr类型的参数。

【使用说明】

同Deliver处理函数。

3.3.6取包函数

【函数功能】

用户手动从接收队列中取包，包括Deliver、Report、MTRespronse和MTError包。

【函数原型】

intDeliver（int*type,DeliverStr*DeliverStruct,ReportStr*ReportStruct,MTRespStr*RespStruct，MTErrorStr*MTErrorStruct）

【参数说明】

type：

返回包的类型

1－Deliver包

2－Report包

3－MTResponse包

4－Submit错误包

DeliverStruct：

返回的DeliverStr结构的包，当type＝1时返回

ReportStruct：

返回的ReportStr结构的包，当type＝2时返回

RespStruct：

返回的MTRespStr结构的包，当type＝3时返回

MTErrorStruct：

返回的MTErrorStr结构的包，当type＝4时返回

返回参数：

0：

取得最后一个包

1：

取得一个包

－1：

取包错误或未取到包

【使用说明】

该函数采用标准的Win32API调用（stdcall）。

声明外部函数时需加上stdcall修

饰符。

当用户不想采用事件触发机制取包，而是手动从接收队列中取包时调用此函数。

调用此函数时，必须将Startup函数中的IMOThread参数设置为0，同时将Deliver、

Report、Response和MTError参数设置为nil。