1、客户管理行情客户端系统（客户管理）行情客户端系统行情客户端应用程序接口2006年10月19日文件版本号修正日期备注V1.012007-03-28首次发布V1.022009-08-07修改示例程序，添加Join等待第1章介绍1第2章体系结构12.1通讯模式12.2数据流2第3章运行模式13.1工作线程13.2本地文件1第4章开发接口14.1CFfexFtdcMduserSpi 接口14.1.1OnFrontConnected 方法14.1.2OnFrontDisconnected 方法14.1.3OnHeartBeatWarning方法24.1.4OnRspUserLogin方法24.1.5On
2、RspUserLogout 方法34.1.6OnRtnDepthMarketData方法44.1.7OnRspError 方法64.2CFfexFtdcMduserApi接口74.2.1CreateFtdcMduserApi方法74.2.2Release 方法74.2.3Init 方法84.2.4Join 方法84.2.5GetTradingDay方法84.2.6RegisterSpi 方法84.2.7RegisterFront 方法94.2.8SubscribeMarketDataTopic方法94.2.9ReqUserLogin 方法94.2.10ReqUserLogout 方法10第5章
3、开发示例12第1章 介绍行情客户端系统API是壹个基于C+的类库,通过使用和扩展类库提供的接口来实现行情数据的接收。该类库包含以下5个文件：文件名版本文件大小文件描述CFfexFtdcMduserApi.hV1.0211,441字节行情接口头文件CFfexFtdcUserApiStruct.hV1.0240,238字节定义了UserAPI所需的壹系列数据类型的头文件CffexFtdcUserApiDataType.hV1.02142,601字节定义了壹系列业务关联的数据结构的头文件CFfexmduserapi.dllV1.02983,121字节动态链接库二进制文件Cffexmduserapi.
4、libV1.023,530字节导入库文件支持MSVC6.0，MSVC.NET2003编译器。需要打开多线程编译选项/MT。第2章 体系结构行情API使用建立于TCP协议之上FTD协议和交易所的行情发布服务器进行通讯。行情发布服务器负责行情信息的产生和发布，但不参和交易过程。参和交易需要使用另外的“交易员API”。2.1 通讯模式FTD协议中的所有通讯均基于某个通讯模式。通讯模式实际上就是通讯双方协同工作的方式。行情发布涉及的通讯模式共有二种： 对话通讯模式 广播通讯模式对话通讯模式是指由会员端主动发起的通讯请求。该请求被交易所端接收和处理，且给予响应。例如登入和登出。这种通讯模式和普通的客户/
5、服务器模式相同。广播通讯模式是指交易所端主动，向市场中的关联会员发出相同的信息。例如行情等。通讯模式和网络的连接不壹定存于简单的壹对壹的关系。也就是说，壹个网络连接中可能传送多种不同通讯模式的报文，壹种通讯模式的报文也能够于多个不同的连接中传送。无论哪种通讯模式，其通讯过程均如图1所示：图1) 各通讯模式的工作过程2.2 数据流行情发布支持对话通讯模式、广播通讯模式：对话通讯模式下支持对话数据流：对话数据流是壹个双向数据流，会员系统发送请求，行情发布系统反馈应答。交易系统不维护对话流的状态。系统故障时，对话数据流会重置，通讯途中的数据可能会丢失。广播通讯模式下支持行情数据流：行情数据流是壹个单
6、向数据流，由行情发布系统发向会员系统，用于发送行情信息；行情流是壹个可靠的数据流，行情系统维护整个系统的行情流，于壹个交易日内，会员系统断线恢复连接时，能够请求行情系统发送指定序号之后的行情流数据。行情服务所提供的行情内容是按照主题组织的。每个主题包括壹组合约的行情，仍包括了行情发布内容和发布方式，包括行情深度、采样频率、延迟时间等。交易所会公布各行情主题的具体内容，且设定每个行情用户所能订阅的行情主题。每个行情主题对应着壹个行情流。要获得行情通知，客户端必需于连接行情服务器时，订阅壹个或多个行情发布主题。第3章 运行模式3.1 工作线程交易员客户端应用程序至少由俩个线程组成，壹个是应用程序主
7、线程，壹个是交易员API工作线程。应用程序和交易系统的通讯是由API工作线程驱动的。CFfexFtdcMduserApi提供的接口是线程安全的，能够有多个应用程序线程同时发出请求。CFfexFtdcMduserSpi提供的接口回调是由API工作线程驱动，如果重载的某个回调函数阻塞，则等于阻塞了API工作线程，API和交易系统的通讯会停止。因此，于CFfexFtdcTraderSpi派生类的回调函数中，通常应迅速返回，能够利用将数据放入缓冲区或通过Windows的消息机制来实现。3.2 本地文件交易员API于运行过程中，会将壹些数据写入本地文件中。调用CreateFtdcMduserApi函数，
8、能够传递壹个参数，指明存贮本地文件的路径。该路径必须于运行前已创建好。本地文件的扩展名均是”.con”。第4章 开发接口行情客户端系统API提供了二个接口，分别为CFfexFtdcMduserApi和CFfexFtdcMduserSpi。4.1 CFfexFtdcMduserSpi接口CFfexFtdcMduserSpi实现了事件通知接口。用户必需派生CFfexFtdcMduserSpi接口，编写事件处理方法来处理感兴趣的事件。4.1.1 OnFrontConnected方法当客户端和行情发布服务器建立起通信连接时（仍未登录前），该方法被调用。函数原型：voidOnFrontConnected
9、()；本方法于完成初始化后调用，能够于其中完成用户登录任务。4.1.2 OnFrontDisconnected方法当客户端和交易后台通信连接断开时，该方法被调用。当发生这个情况后，API会自动重新连接，客户端可不做处理。函数原型：voidOnFrontDisconnected(intnReason)；参数：nReason：连接断开原因0x1001网络读失败0x1002网络写失败0x2001接收心跳超时0x2002发送心跳失败0x2003收到错误报文4.1.3 OnHeartBeatWarning方法心跳超时警告。当长时间未收到报文时，该方法被调用。函数原型：voidOnHeartBeatWar
10、ning(intnTimeLapse)；参数：nTimeLapse：距离上次接收报文的时间4.1.4 OnRspUserLogin方法当客户端发出登录请求之后，该方法会被调用，通知客户端登录是否成功。函数原型：voidOnRspUserLogin(CFfexFtdcRspUserLoginField*pRspUserLogin,CFfexFtdcRspInfoField*pRspInfo,intnRequestID,boolbIsLast)；参数：pRspUserLogin：返回用户登录信息的地址。用户登录信息结构：structCFfexFtdcRspUserLoginField/交易日TFf
11、exFtdcDateTypeTradingDay;/登录成功时间TFfexFtdcTimeTypeLoginTime;/最大本地报单号TFfexFtdcOrderLocalIDTypeMaxOrderLocalID;/交易用户代码TFfexFtdcUserIDTypeUserID;/会员代码TFfexFtdcParticipantIDTypeParticipantID;pRspInfo：返回用户响应信息的地址。特别注意于有连续的成功的响应数据时，中间有可能返回NULL，但第壹次不会，以下同。错误代码为0时，表示操作成功，以下同。响应信息结构：structCFfexFtdcRspInfoFiel
12、d/错误代码TFfexFtdcErrorIDTypeErrorID;/错误信息TFfexFtdcErrorMsgTypeErrorMsg;nRequestID：返回用户登录请求的ID，该ID由用户于登录时指定。bIsLast：指示该次返回是否为针对nRequestID的最后壹次返回。4.1.5 OnRspUserLogout方法当客户端发出登出请求之后，该方法会被调用，通知客户端登出是否成功。函数原型：voidOnRspUserLogout(CFfexFtdcRspUserLogoutField*pRspUserLogout,CFfexFtdcRspInfoField*pRspInfo,int
13、nRequestID,boolbIsLast)；参数：pRspUserLogout：返回用户登出信息的地址。用户登出信息结构：structCFfexFtdcRspUserLogoutField/交易用户代码TFfexFtdcUserIDTypeUserID;/会员代码TFfexFtdcParticipantIDTypeParticipantID;pRspInfo：返回用户响应信息的地址。响应信息结构：structCFfexFtdcRspInfoField/错误代码TFfexFtdcErrorIDTypeErrorID;/错误信息TFfexFtdcErrorMsgTypeErrorMsg;nRe
14、questID：返回用户登出请求的ID，该ID由用户于登出时指定。bIsLast：指示该次返回是否为针对nRequestID的最后壹次返回。4.1.6 OnRtnDepthMarketData方法行情通知，行情服务器会主动通知客户端。函数原型：voidOnRtnDepthMarketData(CFfexFtdcDepthMarketDataField*pDepthMarketData)；参数：pDepthMarketData：返回市场行情信息的地址。深度市场行情信息结构：structCFfexFtdcDepthMarketDataField/交易日TFfexFtdcDateTypeTradin
15、gDay;/结算组代码TFfexFtdcSettlementGroupIDTypeSettlementGroupID;/结算编号TFfexFtdcSettlementIDTypeSettlementID;/最新价TFfexFtdcPriceTypeLastPrice;/昨结算TFfexFtdcPriceTypePreSettlementPrice;/昨收盘TFfexFtdcPriceTypePreClosePrice;/昨持仓量TFfexFtdcLargeVolumeTypePreOpenInterest;/今开盘TFfexFtdcPriceTypeOpenPrice;/最高价TFfexFtd
16、cPriceTypeHighestPrice;/最低价TFfexFtdcPriceTypeLowestPrice;/数量TFfexFtdcVolumeTypeVolume;/成交金额TFfexFtdcMoneyTypeTurnover;/持仓量TFfexFtdcLargeVolumeTypeOpenInterest;/今收盘TFfexFtdcPriceTypeClosePrice;/今结算TFfexFtdcPriceTypeSettlementPrice;/涨停板价TFfexFtdcPriceTypeUpperLimitPrice;/跌停板价TFfexFtdcPriceTypeLowerLim
17、itPrice;/昨虚实度TFfexFtdcRatioTypePreDelta;/今虚实度TFfexFtdcRatioTypeCurrDelta;/最后修改时间TFfexFtdcTimeTypeUpdateTime;/最后修改毫秒TFfexFtdcMillisecTypeUpdateMillisec;/合约代码TFfexFtdcInstrumentIDTypeInstrumentID;/申买价壹TFfexFtdcPriceTypeBidPrice1;/申买量壹TFfexFtdcVolumeTypeBidVolume1;/申卖价壹TFfexFtdcPriceTypeAskPrice1;/申卖量壹
18、TFfexFtdcVolumeTypeAskVolume1;/申买价二TFfexFtdcPriceTypeBidPrice2;/申买量二TFfexFtdcVolumeTypeBidVolume2;/申卖价二TFfexFtdcPriceTypeAskPrice2;/申卖量二TFfexFtdcVolumeTypeAskVolume2;/申买价三TFfexFtdcPriceTypeBidPrice3;/申买量三TFfexFtdcVolumeTypeBidVolume3;/申卖价三TFfexFtdcPriceTypeAskPrice3;/申卖量三TFfexFtdcVolumeTypeAskVolume
19、3;/申买价四TFfexFtdcPriceTypeBidPrice4;/申买量四TFfexFtdcVolumeTypeBidVolume4;/申卖价四TFfexFtdcPriceTypeAskPrice4;/申卖量四TFfexFtdcVolumeTypeAskVolume4;/申买价五TFfexFtdcPriceTypeBidPrice5;/申买量五TFfexFtdcVolumeTypeBidVolume5;/申卖价五TFfexFtdcPriceTypeAskPrice5;/申卖量五TFfexFtdcVolumeTypeAskVolume5;4.1.7 OnRspError方法针对用户请求的出
20、错通知。函数原型：voidOnRspError(CFfexFtdcRspInfoField*pRspInfo,intnRequestID,boolbIsLast)参数：pRspInfo：返回用户响应信息的地址。响应信息结构：structCFfexFtdcRspInfoField/错误代码TFfexFtdcErrorIDTypeErrorID;/错误信息TFfexFtdcErrorMsgTypeErrorMsg;nRequestID：返回用户登出请求的ID，该ID由用户于登出时指定。bIsLast：指示该次返回是否为针对nRequestID的最后壹次返回。4.2 CFfexFtdcMduserA
21、pi接口CFfexFtdcMduserApi接口提供给客户登陆、登出行情查询服务器，进行行情查询等功能。4.2.1 CreateFtdcMduserApi方法产生壹个CFfexFtdcMduserApi的壹个实例，不能通过new来产生。函数原型：staticCFfexFtdcMduserApi*CreateFtdcMduserApi(constchar*pszFlowPath=);参数：pszFlowPath：常量字符指针，用于指定壹个文件目录来存贮行情服务发布消息的状态。默认值代表当前目录。返回值：返回壹个指向CFfexFtdcMduserApi实例的指针。4.2.2 Release方法释放
22、壹个CFfexFtdcMduserApi实例。函数原型：voidRelease()；4.2.3 Init方法使客户端开始和行情发布服务器建立连接，连接成功后能够进行登陆。函数原型：voidInit()；4.2.4 Join方法客户端等待壹个接口实例线程的结束。函数原型：voidJoin()；4.2.5 GetTradingDay方法获得当前交易日。只有当和服务器连接建立后才会取到正确的值。函数原型：constchar*GetTradingDay()；返回值：返回壹个指向日期信息字符串的常量指针。4.2.6 RegisterSpi方法注册壹个派生自CFfexFtdcMduserSpi接口类的实例
23、，该实例将完成事件处理。函数原型：voidRegisterSpi(CFfexFtdcMduserSpi*pSpi);参数：pSpi：实现了CFfexFtdcMduserSpi接口的实例指针。4.2.7 RegisterFront方法设置行情发布服务器的地址。函数原型：voidRegisterFront(char*pszFrontAddress);参数：pszFrontAddress：指向后台服务器地址的指针。服务器地址的格式为：“protocol:/ipaddress:port”，如：”tcp:/127.0.0.1:17001”。“tcp”代表传输协议，“127.0.0.1”代表服务器地址。”
24、17001”代表服务器端口号。4.2.8 SubscribeMarketDataTopic方法客户端订阅自己需要的行情。订阅后行情服务器会自动发出行情通知给客户端。函数原型：voidSubscribeMarketDataTopic(intnTopicID,TE_RESUME_TYPEnResumeType)；参数：nTopicID：代表深度行情的主题，由交易所公布。nResumeType：市场行情重传方式TERT_RESTART:从本交易日开始重传TERT_RESUME:从上次收到的续传TERT_QUICK:先传送当前行情快照,再传送登录后市场行情的内容4.2.9 ReqUserLogin方法
25、用户发出登陆请求。函数原型：intReqUserLogin(CFfexFtdcReqUserLoginField*pReqUserLoginField,intnRequestID)；参数：pReqUserLoginField：指向用户登录请求结构的地址。用户登录请求结构：structCFfexFtdcReqUserLoginField/交易日TFfexFtdcDateTypeTradingDay;/交易用户代码TFfexFtdcUserIDTypeUserID;/会员代码TFfexFtdcParticipantIDTypeParticipantID;/密码TFfexFtdcPasswordTy
26、pePassword;nRequestID：用户登录请求的ID，该ID由用户指定，管理。返回值：0，代表成功。其它值代表失败。4.2.10 ReqUserLogout方法用户发出登出请求。函数原型：intReqUserLogout(CFfexFtdcReqUserLogoutField*pReqUserLogout,intnRequestID)；参数：pReqUserLogout：指向用户登出请求结构的地址。用户登出请求结构：structCFfexFtdcReqUserLogoutField/交易用户代码TFfexFtdcUserIDTypeUserID;/会员代码TFfexFtdcParti
27、cipantIDTypeParticipantID;nRequestID：用户登出请求的ID，该ID由用户指定，管理。返回值：0，代表成功。其它值代表失败。第5章 开发示例/mdusertest.cpp:/壹个简单的例子，介绍CFfexFtdcMduserApi和CFfexFtdcMduserSpi接口的使用。#includestdio.h#includeFtdcMduserApi.hclassCSimpleHandler:publicCFfexFtdcMduserSpipublic:/构造函数，需要壹个有效的指向CFfexFtdcMduserApi实例的指针CSimpleHandler(CF
28、fexFtdcMduserApi*pUserApi):m_pUserApi(pUserApi)CSimpleHandler()/当客户端和行情发布服务器建立起通信连接，客户端需要进行登录voidOnFrontConnected()CFfexFtdcReqUserLoginFieldreqUserLogin;strcpy(reqUserLogin.TradingDay,m_pUserApi-GetTradingDay();strcpy(reqUserLogin.ParticipantID,P001);strcpy(reqUserLogin.UserID,U001);strcpy(reqUserL
29、ogin.Password,P001);m_pUserApi-ReqUserLogin(&reqUserLogin,0);/当客户端和行情发布服务器通信连接断开时，该方法被调用voidOnFrontDisconnected()/当发生这个情况后，API会自动重新连接，客户端可不做处理printf(OnFrontDisconnected.n);/当客户端发出登录请求之后，该方法会被调用，通知客户端登录是否成功voidOnRspUserLogin(CFfexFtdcRspUserLoginField*pRspUserLogin,CFfexFtdcRspInfoField*pRspInfo,intnRequestID,boolbIsLast)printf(OnRspUserLogin:n);printf(ErrorCode=%d,ErrorMsg=%sn,pRspInfo-ErrorID,pRspInfo-ErrorMsg);printf(RequestID=%d,Chain=%dn,nRequestID,bIsLast);if(pRspInfo-ErrorID!=0)/端登失败，客户端需进行错误处理prin
