MDCUSSD网关软件使用手册2012

1、MDC USSD网关软件使用手册北京移数通电讯有限公司2012年4月目 录1关于本文档31.1阅读对象32运行环境32.1硬件环境32.2软件环境32.3网络环境43软件运行43.1安装43.2运行43.3卸载54功能说明54.1USSD应用接口API54.1.1RegisterUssdCallbackFunctions54.1.2UssdSendBegin74.1.3UssdSendContinue84.1.4UssdSendRelease94.1.5UssdSendAbort94.1.6UssdSendSwitch104.1.7UssdSendCharge114.2USSD会话124.2.

2、1会话管理124.2.2超时处理124.2.3重连机制124.3缓存机制134.4错误代码131 关于本文档本文档是MDC USSD网关软件的使用说明。1.1 阅读对象本文档的主要阅读对象为所有使用MDC USSD网关软件人员和开发人员作为开发参考。2 运行环境2.1 硬件环境硬件最小配置推荐配置CPUPentium III 500MHzPentium III 1GHz显卡支持800600，16位增强色，4MB显存支持1024768，32位增强色，16MB显存内存128MB256MB硬盘至少具有40MB可用磁盘空间网卡Linux兼容网卡光驱CDROM驱动器2.2 软件环境项目说明操作系统Lin

3、ux应用程序MDC USSD网关软件2.3 网络环境局域网，广域网环境。3 软件运行3.1 安装把MDC USSD网关程序拷贝到指定目录下即可。3.2 运行键入ussdproxy，会显示提示：输入相应的地址、端口、用户名和密码即可运行MDC USSD网关程序。3.3 卸载删除指定的安装目录即可。4 功能说明4.1 USSD应用接口API 接口API分为两类，一是移动台上行到USSD业务应用的消息接口，一是USSD业务应用下发给移动台的消息接口。下面分别进行描述：4.1.1 RegisterUssdCallbackFunctions通过此接口注册USSD消息处理回调函数，用来处理移动台上行到US

4、SD业务应用的消息。 【接口函数】int RegisterUssdCallbackFunctions(TUssdCallbacks CallbackFuncs); 【功能说明】向USSD协议层API注册USSD消息处理回调函数，当收到移动台上行的消息后，调用回调函数进行处理【数据结构】 struct TUssdCallbacks LPONUSSDRECEIVEBEGIN m_pOnUssdReceiveBegin; LPONUSSDRECEIVEUSERINPUT m_pOnUssdReceiveUserInput; LPONUSSDRECEIVEEND m_pOnUssdReceiveEnd

5、; LPONUSSDRECEIVEABORT m_pOnUssdReceiveAbort; LPONUSSDTIMEOUT m_pOnUssdTimeOut; LPONUSSDCHGACK m_pOnUssdChgAck; 【返回值】函数执行成功返回0，否则返回USSD错误代码 【详细描述】该函数向USSD协议层API 注册消息回调函数，回调函数用于处理来自USSD业务中心的会话消息，这些回调函数的地址由CallbackFuncs指定。如果调用失败，则返回值为错误代码，成功则返回0 【参数说明】CallbackFuncs - USSD回调函数的地址集【回调函数原型】1）UssdReceiveB

6、egin消息的回调函数原型：typedef int (*LPONUSSDRECEIVEBEGIN)( HANDLE hUssdDialog, TUssdData UssdData, DWORD *pdwUssdAppParam);2）UssdReceiveUserInput消息的回调函数typedefint (*LPONUSSDRECEIVEUSERINPUT)( HANDLE hUssdDialog, char szUssdString, DWORD dwUssdAppParam);3）UssdReceiveEnd消息的回调函数typedefint (*LPONUSSDRECEIVEEND)

7、( HANDLE hUssdDialog, DWORD dwUssdAppParam);4）UssdReceiveAbort消息的回调函数typedefint (*LPONUSSDRECEIVEABORT)( HANDLE hUssdDialog, DWORD dwErrorCode, DWORD dwUssdAppParam);5）UssdTimeout消息的回调函数typedefint (*LPONUSSDTIMEOUT)( HANDLE hUssdDialog, DWORD dwUssdAppParam);6）UssdChargeAck消息的回调函数typedefint (*LPONUS

8、SDCHGACK)( HANDLE hUssdDialog, DWORD dwErrorCode, DWORD dwUssdAppParam);4.1.2 UssdSendBegin通过此接口发送USSD业务应用给移动台的会话开始消息。 【接口函数】HANDLE UssdSendBegin(int * nError, TUssdData UssdData); 【功能说明】提交一条会话开始请求，需等待手机人工响应 【返回值】 成功时，返回一个本地的会话句柄 失败时，返回一个无效句柄 【详细描述】该函数提交一条会话请求，此请求的数据由UssdData指定。若失败，则nError中包含了错误代码，成

9、功则返回USSD会话句柄 【参数说明】nError- USSD错误码UssdData - 本次USSD会话请求的数据 【数据结构】struct TUssdDataDWORD m_dwUssdCmd; / USSD会话操作类型（1：Request、2：Notify）BYTE m_bUssdVersion; / USSD会话版本号（0x10：Phase I、0x20：Phase II、0x25：Phase II+）BYTE m_bCodeScheme; /编码方案DWORD m_dwErrorCode; / USSD错误代码（仅对UssdAbort和UssdError）char m_szMsIsd

10、n21;/ 移动台号码.char m_szServiceCode4;/ 业务码.char m_szOrg_Service_Code21; /源业务码（仅对回调函数使用）char m_szServiceCode21;/ 目的业务码.char m_szUssdString182; / USSD串内容。DWORD m_dwUssdAppParam;/ USSD业务应用程序自定义的参数。4.1.3 UssdSendContinue通过此接口发送USSD业务应用给移动台的会话通知消息。 【接口函数】int UssdSendContinue(HANDLE hUssdDialog, TUssdData Us

11、sdData); 【功能说明】提交一条会话通知 【返回值】 0 - 成功 其他 - USSD错误码 【详细描述】该函数提交一条会话通知，此通知对应的USSD会话由hUssdDialog指定，会话通知数据由UssdData指定。若失败，则返回值中包含了错误代码，成功则返回0 【参数说明】hUssdDialog：USSD会话句柄UssdData： 本次USSD会话通知的数据4.1.4 UssdSendRelease通过此接口发送USSD业务应用给移动台的会话释放消息。属于会话正常结束。 【接口函数】int UssdSendRelease(HANDLE hUssdDialog); 【功能说明】提交一

12、条会话释放消息，用于结束业务发起的USSD会话 【返回值】 0 - 成功 其他 - USSD错误码 【详细描述】该函数提交一条会话释放消息，该消息对应的USSD会话由hUssdDialog指定。若调用失败，则返回值中包含了错误代码，成功则返回0 【参数说明】hUssdDialog：要释放的USSD会话句柄4.1.5 UssdSendAbort通过此接口发送USSD业务应用给移动台的会话中止消息。属于会话异常中止。 【接口函数】int UssdSendAbort(HANDLE hUssdDialog, DWORD dwErrorCode); 【功能说明】 提交一条会话中止消息 【返回值】 0 -

13、 成功 其他 - USSD错误码 【详细描述】该函数提交一条会话中止消息，该消息对应的USSD会话由hUssdDialog指定为中止会话消息，中止原因码由dwErrorCode指定，若失败，则返回值中包含了错误代码，成功则返回0 【参数说明】hUssdDialog： USSD会话句柄dwErrorCode： USSD会话中止的错误原因代码4.1.6 UssdSendSwitch通过此接口发送USSD业务应用给USSD中心的业务转移消息。 【接口函数】int UssdSendSwitch(HANDLE hUssdDialog, TUssdSwitchInfo SwitchInfo); 【功能说明

14、】提交一条业务转移消息 【返回值】 0 - 成功 其他 - USSD错误码 【详细描述】该函数提交一条业务切换消息，该消息对应的USSD会话由hUssdDialog指定为业务转移消息，SwitchInfo中指明业务切换的信息。失败时返回值中包含了错误代码，成功则返回0 【参数说明】hUssdDialog： USSD会话句柄SwitchInfo： USSD业务转移信息 【数据结构】struct TUssdSwitchInfo BYTEm_bSwitchMode; /转移模式（0：全局转移、1：本地转移） charm_szMsIsdn21; /手机号码 charm_szServiceCode4;

15、/业务码 charm_szUssdString182; /USSD串内容4.1.7 UssdSendCharge通过此接口发送USSD业务应用给USSD中心的计费指示消息。 【接口函数】int UssdSendCharge(HANDLE hUssdDialog, TUssdChargeIndInfo ChargeIndInfo); 【功能说明】 提交一条计费指示消息 【返回值】 0 - 成功 其他 - USSD错误码 【详细描述】该函数提交一条计费指示消息，该消息对应的USSD会话由hUssdDialog指定为计费指示消息，ChargeIndInfo为计费指示信息。失败时返回值中包含了错误代码

16、，成功则返回0 【参数说明】hUssdDialog： USSD会话句柄ChargeIndInfo：计费指示信息 【数据结构】struct TUssdChargeIndInfo DWORDm_dwChargeRatio; /计费费率，其中0表示免费 DWORDm_dwChargeType; /计费类型，1为短消息，2为USSD，3为其他 charm_szChargeSource21; /计费源标识 BYTEm_bChargeLocation; /出话单地点，1为UssdServer出话单4.2 USSD会话4.2.1 会话管理USSD业务操作是基于会话的，USSD协议层应负责每一个USSD会话的

17、创建，应用和释放。4.2.2 超时处理当USSD协议层向移动台发出请求或通知消息时，它须建立一个时钟，此时钟指示业务方的最大等待时间，若该时钟触发时，业务方仍未收到移动台的任何响应消息，则表示当前会话已超时，此时，业务方应向USSD业务中心发出AbortDialog消息并释放当前会话。一般地，业务方等待移动台响应的超时应设为不小于120秒，以确保移动台用户有足够的时间输入响应内容。4.2.3 重连机制当USSD协议层和USSD业务中心的连接因某些错误原因断开后，USSD协议层应能够自动重连到USSD业务中心，以保证USSD业务的处理不会长时间中断。连接断开期间，应释放相关的USSD会话。4.3 缓存机制USSD协议层需提供消息收发的缓存机制。分别建立消息收发的先进先出缓存队列，当业务逻辑