CTP 接口COM封装使用指南
盈佳发布了一个基于COM标准的CTP-API接口封装,通过这个COM接口,用户可以利用任何支持COM的语言来接入CTP;该COM 组件在内部进行仓位和资金的自动计算,并对用户屏蔽了上期所的平今和平昨的差别(优先平今),对用户非常友好。
1.1 COM包构成
该COM组件在运行时,需要下面几个文件:
?ctpcom.dll
?thosttraderapi.dll
?thostmduserapi.dll
?config.xml(可以有多个,不同的期货公司需要不同的配置文
件,在登录时指定这个配置文件的名称)
?error.xml,error.dtd ctp中错误信息定义
1.2 COM注册
在使用COM组件之间,需要先注册注本COM组件,步骤如下:
?运行cmd,
?cd到ctpcom.dll所在的目录,
?运行Regsvr32 ctpcom.dll
1.3 COM接口方法
该COM提供的接口(c++语言描述)如下:
?Login([in] BSTR ConfigFile,[in] BSTR UserID,[in] BSTR
Password,[out] int *ErrorID);
说明:
登录到CTP系统。必须首先调用该方法成功登录后,
才能调用其他方法。
参数:
ConfigFile,配置文件的名称,该配置文件必须和
ctpcom.dll放在同一个目录下。通过指定不通的配置文件,
可以创建多个ctpcom对象,连接到不同的期货经纪公司。
UserID, 投资者账户名
Password,投资者密码;
ErrorID,返回登录错误代码,为0时表示登录成功,
其他值表示登录失败。
?Buy([in] BSTR pszInstrumentID,[in] int volume,[in] double
price,[out] long* OrderID);
说明:
对指定的合约买入开仓;
参数:
pszInstrumentID,合约代码,区分大小写;
volume,开仓手数,
以停板价+立即撤单来模拟)
OrderID,返回该报单的唯一编号,可以通过这个编号
来跟踪此报单;
?Sell([in] BSTR pszInstrumentID,[in] int volume,[in] double
price,[out] long* OrderID);
说明:
对指定的合约卖出平仓;
参数:
pszInstrumentID,合约代码,区分大小写;
volume,平仓手数,
price,平仓价格,0表示以市价平仓(对于上期所,
以停板价+立即撤单来模拟)
OrderID,返回该报单的唯一编号,可以通过这个编号
来跟踪此报单;
?Short([in] BSTR pszInstrumentID,[in] int volume,[in] double
price,[out] long* OrderID);
说明:
对指定的合约卖出开仓;
参数:
pszInstrumentID,合约代码,区分大小写;
volume,开仓手数,
以停板价+立即撤单来模拟)
OrderID,返回该报单的唯一编号,可以通过这个
编号来跟踪此报单;
?Cover([in] BSTR pszInstrumentID,[in] int volume,[in] double
price,[out] long* OrderID);
说明:
对指定的合约买入平仓;
参数:
pszInstrumentID,合约代码,区分大小写;
volume,平仓手数,
price,平仓价格,0表示以市价平仓(对于上期所,
以停板价+立即撤单来模拟)
OrderID,返回该报单的唯一编号,可以通过这个编号来跟踪此报单;
?PlaceOrder([in] BSTR pszInstrumentID, [in] int buySell, [in] int
openClose, [in] int volume,[in] double price,[out] long* OrderID); 说明:
对指定的合约买入平仓;
参数:
pszInstrumentID,合约代码,区分大小写;
buySell, 买卖,0为买,1为卖;
openClose, 开平,0为开,1为平;
volume,平仓手数,
price,平仓价格,0表示以市价平仓(对于上期所,
以停板价+立即撤单来模拟)
OrderID,返回该报单的唯一编号,可以通过这个编号来跟踪此报单;
?CancelOrder([in] long OrderID,[out]int* status);
说明:
对指定的报单进行撤单操作;
参数:
OrderID,指定的报单号;
Status,返回代码,>0表示已经对该报单发出撤单指令,<=0表示该报单不存在,或者已经不可撤;
?SubscribeMD([in] BSTR InstrumentID);
说明:
订阅某个合约的行情数据。在订阅了后,会通过OnMarketData事件将该合约的行情发出。
参数:
InstrumentID –合约代码,区分大小写。
?GetLongPos([in] BSTR InstrumentID,[out] long * LongPos,[out]
double *PositionPrice);
说明:
返回某个合约的多头(买持)仓位。
参数:
InstrumentID –合约代码,区分大小写。
LongPos –返回的多头(买持)仓位大小;
PositionPrice-多头仓位的持仓均价;
?GetLongClosable([in] BSTR InstrumentID,[out] long *
LongClosable);
说明:
返回某个合约的多头(买持)可平仓位。
参数:
InstrumentID –合约代码,区分大小写。
LongClosable–返回的多头(买持)仓位可平量;
?GetShortPos([in] BSTR InstrumentID,[out] long * ShortPos,[out]
double *PositionPrice);
说明:
返回某个合约的空头(卖持)仓位。
参数:
InstrumentID –合约代码,区分大小写。
LongPos –返回的空头(卖持)仓位大小;
PositionPrice-多头仓位的持仓均价;
?GetShortClosable([in] BSTR InstrumentID,[out] long *
ShortClosable);
说明:
返回某个合约的空头(卖持)可平仓位。
参数:
InstrumentID –合约代码,区分大小写。
ShortClosable–返回的空头(卖持)仓位的可平量;
?IsOrderOpen([in] long OrderID,[out] BOOL *IsOpen);
说明:
判断某个报单是否处于可撤状态。
参数:
OrderID –报单编号。
IsOpen–不为0表示处于可撤状态,0表示不可撤;
?GetMarketData([in] BSTR InstrumentID,[out] double *YdClose,
[out] double *YdSettlement, [out] double *Open,[out] double *Last,[out] double *Bid1,[out] double *Ask1,[out] int *Bid1V olume, [out] int * Ask1V olume,[out] double * Highest,[out] double * Lowest,[out] int * TradedV olume,[out] double *TradedAmmount);
说明:
获取一个合约当前最新行情数据。
参数:
InstrumentID–指定合约编号。
YdClose–昨日收盘价;
YdSettlement-昨日结算价
Open-今日开盘价
Last-今日最新价
Bid1-买一价
Ask1-卖一价
Bid1V olume-买一量
Ask1V olume-卖一量
Highest-今日最高价
Lowest-今日最低价
TradedV olume-今日成交量
TradedAmmount-今日成交额
?GetAccount([out] double * Balance,[out] double *Available);
说明:
获取当前帐户的用户权益和可用资金。
参数:
Balance-当前帐户的用户权益可用资金
Available-当前帐户的可用资金
?GetInstruments([out] SAFEARRAY(InstrumentField) *
ppIns,[out] int *Count)
说明:
获取所有合约列表;
参数:
ppIns – InstrumentField指针数组;
Count-合约数目,
?GetInstrumentInfo([in] BSTR InstrumentID,[out] int * Multiply,
[out] double * PriceUnit);
说明:
获得一个合约的乘数和最小价格变动单位;该方法需要在OnInitFinished事件之后调用。
参数:
InstrumentID –合约编号
Multiply –合约乘数;
PriceUnit –合约最小价格变动单位;
?GetMarginRate([in] BSTR InstrumentID,[out] double
*MarginRate,[out] BSTR *ExpireDate);
说明:
获得一个合约的保证金率乘数和到期日,该方法需要在OnInitFinished事件之后调用,MarginRate在第一次调用时可能不能返回,此时可以在OnMarginRate事件中接受。
参数:
InstrumentID –合约编号
MarginRate–合约乘数;
ExpireDate–合约最小价格变动单位;
?CreateKBars(BSTR InstrumentID, int Period, int Interval);
说明:
创建一个Bar序列,之后,COM会通过OnBar事件将生成的Bar推送出来。
参数:
InstrumentID –合约代码;
Period –周期类型,0 –分钟线1- 小时线;
Interval- 周期大小;大于1
1.4 COM触发事件
客户端通过事件来接受行情、资金和仓位等信息。该COM组件发出的事件如下:
OnAccount –当投资者账户信息发生变化时,此事件被触发;
参数:
PreBalance期初用户权益
Balance 当前用户权益
Available 当前可用资金
Commission 今日以发生手续费
FrozenCommission 今日冻结手续费
Margin 占用保证金
FrozenMargin 今日冻结保证金
CloseProfit 今日平仓盈亏
PositionProfit 持仓盈亏
?OnMarketData - 当某个合约有新行情到达时,此事件被触
发;
参数:
InstrumentID 合约编号
BidPrice1 买一价
BidV olume1买一量
AskPrice1卖一价
AskV olume1 卖一量
OpenPrice 开盘价
HighestPrice 最高价
LowestPrice 最低价
LastPrice 最新价
OpenInterest 持仓量
V olume 成交量
UpperLimitPrice 涨停价
LowerLimitPrice 跌停价
PreSettlementPrice 昨结算价
AveragePrice 今日平均价
UpdateTime行情更新时间
UpdateMilliSecond更新毫秒数为0或500
?OnOrder –当某个报单信息发生变化时,此事件被触发;
参数:
OrderID 报单编号
InstrumentID 和约编号
IsBuy 是否为买,非0为买,否则为卖;
IsOpen 是否开仓,非0为开仓,否则为平仓
V olume 委托数量
Price 委托价格
TradedV olume已成交数量
AvgTradePrice 成交均价
OrderStatus 报单当前状态
OrderSysID 交易所报单号
InsertTime 委托时间
StatusMsg 状态信息,如果该报单失败,则为失败原因。
?OnOrderCanceled - 当出现报单错误或者报单被撤时,此事
件被触发;
参数:
OrderID-报单编号
ErrorID-当为错单时的错误编号;
ErrorMsg-当为错单时的错误信息;
?OnOrderFinished –当某个报单全部成交后,此事件被触
发;此事件总是在一个报单的所有OnTrade事件之后发生。
参数:
OrderID 报单编号
?OnPosition –当某个合约的仓位信息发生变化时,此事件
被触发;
参数:
InstrumentID-合约代码
IsLong- 是否为多仓
V olume-持仓量
CloseProfit-今日平仓盈亏
PositionProfit 持仓盈亏
AvgPositionPrice 持仓均价昨仓,是结算之后的均价;
AvgOpenPrice 开仓均价;按开仓价计算的均价;
TotalClosable 总可平量
TodayClosable 今日可平量
?OnTrade - 当所发出的报单有成交时,此事件被触发;
参数:
OrderID 报单编号
InstrumentID 合约代码
IsBuy 是否为买,非0为买,否则为卖;
IsOpen 是否开仓,非0为开,否则为平;
ThisTradeV olume 本次成交数量
ThisTradePrice 本次成交均价
TradeTime 成交时间;
?OnTradeConnected - 当交易连线后,此事件被触发;
?OnTradeDisconnected - 当交易断线后,此事件被触发;?OnMDConnected - 当行情连线后,此事件被触发;
?OnMDDisconnected - 当行情断线后,此事件被触发;
?OnOrderActionFailed([in] long OrderID,[in] int ErrorID);当
撤单失败时,此事件被触发;
?OnInstrumentStatus –交易所状态信息通知
参数:
InstrumentID –交易所随机选择的一个合约;
ExchangeID –交易所代码:CFFEX 中金所;
SHFE 上期所;
DCE 大商所;
CZCE 郑商所;
EnterTime –进入本状态时间;
NewState –当前状态;其值如下所示:
//开盘前
#define THOST_FTDC_IS_BeforeTrading '0'
///非交易
#define THOST_FTDC_IS_NoTrading '1'
///连续交易
#define THOST_FTDC_IS_Continous '2'
///集合竞价报单
#define THOST_FTDC_IS_AuctionOrdering '3'
///集合竞价价格平衡
#define THOST_FTDC_IS_AuctionBalance '4'
///集合竞价撮合
#define THOST_FTDC_IS_AuctionMatch '5'
///收盘
#define THOST_FTDC_IS_Closed '6'
?OnInitFinished –相关初始化工作完成,在这个事件通知之
后,可以通过GetInstruments方法获得所有合约列表。
?OnMarginRate
Desc:
Fired when an instruments’ margin rate was queried back. Params:
InstrumentID
longMarginRate
shortMarginRate
?OnCommissionRate
Desc:
Fired when an instruments’commission rate was queried back.
Params:
InstrumentID
OpenCommissionRateByMoney
OpenCommissionRateByV olume
CloseCommissionRateByMoney
CloseCommissionRateByV olume
CloseTodayCommissionRateByMoney
CloseTodayCommissionRateByV olume
?OnBar –新创建了Bar或者某个Bar被关闭;
参数:
InstrumentID –合约编号;
BeginTime –本Bar的开始时间;
Period –周期类型,0 –分钟线;1 –小时线;
Interval –周期大小;
Open –本Bar的开盘价,
High–本Bar的最高价;
Low- 本Bar的最低价;
Close –本Bar的收盘价;
V olume- 本bar时间内的成交量;
Position- 本Bar结束时的持仓量;
Status –本Bar的状态,0-未关闭,1 –关闭;
注1:接口中涉及到的ErrorID和ErrorMsg参见发布包中的error.xml;
注2: OrderStatus的取值如下:
///全部成交
#define THOST_FTDC_OST_AllTraded '0'
///部分成交还在队列中
#define THOST_FTDC_OST_PartTradedQueueing '1'
///部分成交不在队列中
#define THOST_FTDC_OST_PartTradedNotQueueing '2'
///未成交还在队列中
#define THOST_FTDC_OST_NoTradeQueueing '3'
///未成交不在队列中
#define THOST_FTDC_OST_NoTradeNotQueueing '4'
///撤单
#define THOST_FTDC_OST_Canceled '5'
///未知
#define THOST_FTDC_OST_Unknown 'a'
///尚未触发
#define THOST_FTDC_OST_NotTouched 'b'
///已触发
#define THOST_FTDC_OST_Touched 'c'
1.5 COM使用示例
1.5.1 Excel示例
见ctpcom_sample.xls
1.5.2 VB6.0示例
Dim WithEvents ctp As ICTPClientAPI
Private Sub Login_Click()
Dim errorID As Long
Dim succ As Long
Set ctp = New CTPCOMLib.ICTPClientAPI
Call ctp.Login("config.xml", "00100", "888888", errorID)
If errorID = 0 Then
MsgBox "登录ok"
Else
MsgBox "登录错误:" & errorID
End If
End Sub
Private Sub Buy_Click()
Dim OrderID As Long
Dim index As Integer
Dim tm1, tm2 As Date
Call ctp.Buy("IF1008", 1, 0, OrderID)
End Sub
Private SubMD_Click()
Call ctp.SubscribeMD("IF1008")
End Sub
Private Sub Close_Click()
Set ctp = Nothing
End Sub
Private Sub Sell_Click()
Dim OrderID As Long
Call ctp.Sell("IF1008", 1, 0, OrderID)
End Sub
Private Sub ctp_OnAccount(ByVal PreBalance As Double, ByVal Balance As Double, ByVal Available As Long, ByVal Commission As Double, ByVal FrozenCommission As Double, ByVal Margin As Double, ByVal FrozenMargin As Double, ByVal CloseProfit As Double, ByVal PositionProfit As Double)
Label1.Caption = Available
End Sub
Private Sub ctp_OnMarketData(ByVal InstrumentID As String, ByVal BidPrice1 As Double, ByVal BidV olume1 As Long, ByVal AskPrice1 As Double, ByVal AskV olume1 As Long, ByVal OpenPrice As Double, ByVal HighestPrice As Double, ByVal LowestPrice As Double, ByVal LastPrice As Double, ByVal OpenInterest As Long, ByVal V olume As Long, ByVal UpperLimitPrice As Double, ByVal LowerLimitPrice As Double, ByVal PreSettlementPrice As Double, ByVal AveragePriceAs Double,ByVal UpdateTime As String, ByVal UpdateMilliSecond As Long)
End Sub
Private Sub ctp_OnPosition(ByVal InstrumentID As String, ByVal IsLong As Long, ByVal V olume As Long, ByVal CloseProfit As Double, ByVal PositionProfit As Double, ByVal TotalClosable As Long, ByVal TodayClosable As Long)
Label2.Caption = V olume
End Sub
1.5.3 VC6.0示例
在VC中创建一个CEventHandler类,如下:
class CCTPComEventHandler
:public IDispEventImpl<1,CCTPComEventHandler>
{
private:
CComPtr
void ShowHResultMessage(HRESULT hr){
CString cs;
CString msg = _com_error(hr).ErrorMessage();
cs.Format(_T("Error 0x%08x: %s"), hr, msg);
AfxMessageBox(cs);
}
public:
IICTPClientAPI* CreateCTPCom(){
HRESULT hr;
hr =m_pCtpClient.CoCreateInstance(CLSID_ICTPClientAPI);
if(hr != S_OK){
ShowHResultMessage(hr);
return NULL;
}
hr = AtlGetObjectSourceInterface(m_pCtpClient, &this->m_libid,
&this->m_iid, &this->m_wMajorVerNum, &this->m_wMinorVerNum);
if(FAILED(hr)){
ShowHResultMessage(hr);
return NULL;
}
hr = DispEventAdvise(m_pCtpClient,&DIID__IICTPClientAPIEvents);
if(FAILED(hr)){
ShowHResultMessage(hr);
}
IICTPClientAPI *pCtpCom=NULL;
hr =m_pCtpClient->QueryInterface(IID_IICTPClientAPI,(void **)&pCtpCom);
if(hr != S_OK){
ShowHResultMessage(hr);
return NULL;
}
return pCtpCom;
}
BEGIN_SINK_MAP(CCTPComEventHandler)
SINK_ENTRY(1, 1, OnMarketData)
SINK_ENTRY(1, 2, OnAccount)
SINK_ENTRY(1, 3, OnOrder)
SINK_ENTRY(1, 4, OnTrade)
SINK_ENTRY(1, 5, OnOrderCanceled)
SINK_ENTRY(1, 6, OnOrderFinished)
SINK_ENTRY(1, 7, OnTradeConnected)
SINK_ENTRY(1, 8, OnTradeDisconnected)
SINK_ENTRY(1, 9, OnMDConnected)
SINK_ENTRY(1, 10, OnMDDisconnected)
SINK_ENTRY(1, 11, OnPosition)
SINK_ENTRY(1, 12, OnOrderActionFailed)
END_SINK_MAP()
STDMETHODIMP OnMarketData(BSTR InstrumentID, DOUBLE BidPrice1, INT BidV olume1, DOUBLE AskPrice1, INT AskV olume1, DOUBLE OpenPrice, DOUBLE HighestPrice, DOUBLE LowestPrice, DOUBLE LastPrice,LONG OpenInterest, LONG
V olume, DOUBLE UpperLimitPrice, DOUBLE LowerLimitPrice, DOUBLE PreSettlementPrice, DOUBLE AveragePrice, BSTR UpdateTime, INT UpdateMilliSecond){
//TODO 在这里处理行情;
return S_OK;
}
STDMETHODIMP OnAccount(DOUBLE PreBalance, DOUBLE Balance, INT Available, DOUBLE Commission, DOUBLE FrozenCommission, DOUBLE Margin, DOUBLE FrozenMargin,DOUBLE CloseProfit, DOUBLE PositionProfit)
{
//TODO 在这里处理账户通知;
return S_OK;
}
STDMETHODIMP OnOrder(LONG OrderID, BSTR InstrumentID, INT IsBuy, INT