联通短信网关SP端应用程序接口使用说明(sgip12).doc

中兴通讯联通短信网关SP端应用程序接口使用说明短信网关SP端应用程序接口使用说明 - ZTE_SGIP_API一、 使用说明本接口遵循 SGIPv1.2 协议标准,以提供消息发送和接收函数的方式, 向 ICP 提 供同联通网关进行信息交换的实现途径.客户可以依据具体需要,利用所提供的函数实 现不同的连接方式(长连接和短连接)以及何时自动建立和中断连接, 除此之外, API 作为应用的接口,对 SGIP 描述的其它功能,象流量控制 重发机制和并发处理都不预 干预,需要应用程序处理二、 函数说明：1、 设置源节点代码(set_src_node) 函数功能依照SGIP1.2协议，设置源节点代码 返回值无 参数说明：参数名数据长度数据类型说明num4整型SP源节点代码值 2、与网关建立连接（SGIP_Connect） 函数功能建立与网关间的连接 返回值整型0 连接成功 返回值标识一个连接，在以下的函数中使用0 连接失败 参数说明：参数名数据长度数据类型说明gw_ip15字符串网关的IP地址port2短整型端口号username16字符串登陆用户名passwd16字符串登陆密码3、向网关提交信息 (SGIP_Submit) 函数功能向网关提交短信 返回值=0 标识成功0 标识发送失败 参数说明：参数名数据长度数据类型说明conn_id4整型SGIP_Connect 返回的连接标识sp_dial_num21字符串SP接入号ICPID5字符串企业代码service_id10字符串业务代码fee_type1整型计费类型01：免费 02：按条 03：包月 04：封顶 05：SP收费。fee_value6字符串资费代码，以分为单位give_value6字符串赠送费用代码，以分为单位agent_flag1整型代收费标志，0：应收；1：实收mt_flag1整型引起MT消息的原因0：MO点播引起的第一条MT消息1：MO点播引起的非第一条MT消2：非MO点播引起的MT消息。priority1无符号整型优先级 0-9从低到高valid_time15字符串存活时间，格式为YYYYMMDDHHMMSSat_time15字符串存活时间，格式为YYYYMMDDHHMMSSreport_flag1无符号整型状态报告标记0：该条消息只有最后出错时要返回状态报告1：该条消息无论最后是否成功都要返回状态报告2：该条消息不需要返回状态报告3：该条消息仅携带包月计费信息，不下发给用户，要返回状态报告tp_pid1无符号整型一般填0 具体值参见GSM03.40tp_udhi1无符号整型一般填0 具体值参见GSM03.40msg_type1无符号整型消息类型msg_format1无符号整型消息格式 0=ASCII 4=bin 8=UCS2 15=GBcharge_mobile21字符串付费号码，如果为空，则该条短消息产生的费用由UserNumber代表的用户支付user_num1无符号整型接收手机个数 100dest_mobiles21*user_num字符串接收手机号码，以空格分隔msg160字符串消息内容msg_len1无符号整型消息长度p_seq14无符号整型返回生成的序列号1p_seq24无符号整型返回生成的序列号2p_seq34无符号整型返回生成的序列号3注意：1、如果建立好连接后一段时间没有发送消息，网关可能会关闭连接，2、SGIP_Submit返回ERROR_SOCKET_CLOSE ,这时，必须重新建立连接并发送消息3、p_seq1,p_seq2,p_seq3是函数返回的序列号，可与状态报告中的序列号对应 4、主动与网关断开连接（SGIP_Disconnect） 函数功能主动和网关断开链接 返回值=0 标识成功 0 标识成功收到MO消息,返回值是消息类型可能为MO_MSG或MO_REPORT0 标识发生错误: 参数说明：参数名数据长度数据类型说明sockfd4整型连接标识p_MO-指向指针的指针返回的MO消息可能为MO_msg或MO_report 注意：1、应用程序必须自己建立监听socket,并将accept返回的socket标识传给SGIP_Get_MO (参见test_mo例子)2、如果没有MO消息将阻塞，直至MO消息到达或连接被网关关闭3、返回ERROR_SOCKET_CLOSE并不是错误，只是网关关闭了连接4、对收到的MO，应用程序要根据SGIP_Get_MO返回的类型。三、 结构体说明参数名数据长度数据类型说明sourceUser21字符串发送消息的手机SPNumber21字符串SP接入号tp_pid4无符号整型成功转发数量tp_udhi4无符号整型待转发数量msgFormat4无符号整型转发失败数量msgLen4无符号整型向SP成功送达数量msg4无符号整型向SP待送达数量1、MO消息2、状态报告参数名数据长度数据类型说明seq14无符号整型相应的submit序列号1seq24无符号整型相应的submit序列号2seq34无符号整型相应的submit序列号3report_type1无符号整型状态报告类型mobile21字符串接收手机state1无符号整型短信中心序列号errCode1无符号整型错误代码四、常量说明1、MO类型常量名说明MO_MSG一般MO消息MO_REPORT状态报告2、错误码常量名代表值说明ERROR_OK0正常ERROR_SOCKET_CREATE-100创建socket失败ERROR_CONNECT-101联接到网关失败ERROR_SOCKET_WRITE-102写socket失败ERROR_SOCKET_READ-103读socket失败ERROR_ICP_ID-104错误的SP_IDERROR_AUTH-105认证错误ERROR_MSG_LEN-106短消息长度错ERROR_FEE_CODE-107计费代码错ERROR_SERVICE_ID-108业务代码错ERROR_FLOW_CONTROL-109流量控制错ERROR_SOCKET_CLOSE-110当对Socket操作时，socket关闭ERROR_CMD-111错误的命令字ERROR_INTERNAL-200内部错误，一般为信息结构错ERROR_UNKNOWN-201未知错误ERROR_ARGUMENT-202调用api函数参数错五、常见问题解答1、为何联接到网关时网关回复ERROR_SOCKET_READ错误码？答：造成此问题的原因很可能是你的IP同局方管理人员设置的IP不一致。请与局方管理人员核对数据。2、为何向网关提交短信时会返回ERROR_FEE_CODE错误码？答：深讯信科网关要求资费类别为按条计费时资费代码不能为0；3、接收MO消息时，为何进程会僵死？答：造成此现象的原因很可能是api没有得到网关发来的MO或者状态报告包，处于阻塞等待状态。4、为何和网关建立的MT链路经常会断开？答：造成此问题的原因很可能是提