X-ing API

설정방법 http://blog.naver.com/youhavegot/110085280180

X-ing API란?

• DLL(Dynamic Link Library) 형태로 제공되어지는 API(Application Programming Interface) 입니다.
• X-ing 서버와 데이터를 주고 받을 수 있는 Interface를 제공합니다.
• 체결/잔고 등의 계좌정보와 시세/시황 등의 투자정보 데이터를 제공합니다.
• 20개 이하(20여개의 데이터관리 함수 제외)의 API를 제공하며 10개 이하의 API 사용으로 X-ing 에서 제공하는 대부분의 화면을 개발할 수 있습니다.
• 요청 당시의 데이터를 전송해주는 조회 데이터 TR과 요청이후부터 데이터가 변경될때마다 전송해주는 실시간 데이터 TR, 두가지의 데이터 TR 조회로 X-ing 에서 제공하는 대부분의 화면개발이 가능합니다.
• Visual C++ 6.0 으로 제작되었으며 윈도우즈 프로그래밍이 가능한 모든 언어를 지원하기 위해 Regular DLL 로 제작되었기 때문에 Visual C++ 뿐만 아니라 Visual Basic, Delphi, C# 등으로도 개발이 가능합니다.

X-ing API 관련파일

• X-ing API 관련 파일
  • XingAPI.dll
• Microsoft MFC 관련 파일
  • MFC42.dll
  • MSVCRT.dll
• 암호화 관련 파일
  • XecureS.dll
• 공인인증 관련 파일
  • SKComdCM.dll
  • SKComdEM.dll
  • SKComdIF.dll
  • SKComdSC.dll
  • SKComdIC.dll 

• X-ing 서버와 연결을 맺은 이후에 아이디 인증 및 공인인증을 처리
• X-ing API가 복잡한 로그인 과정을 처리하며 결과값을 Window Message로 전송

로그인 처리 Diagram

• [로그인과정]
• 1. 로그인 함수(ETK_Login()) 호출
• 2. 로그인 인증 성공/실패는 로그인 호출시에 등록한 윈도우로 메시지(XM_LOGIN) 전송
• 3. 메시지의 wParam의 값이 “0000” 이면 성공, 그 외에는 실패 

• 
• 
• 

• TR이란?
  - Transaction의 약자로 서버로부터 데이터를 얻기 위해 요청하고 데이터를 받는 일련의 행동을 일컫는다.
  - TR은 조회TR과 실시간TR, 2가지가 존재한다.
• 조회TR과 실시간TR 을 가지고 서버로부터 트레이딩에 관련된 모든 데이터를 받을 수 있다.
• 조회TR : 서버로 데이터 요청 당시의 데이터를 전송
• 실시간TR : 서버로 데이터 요청(ETK_Advise()) 이후에 데이터가 변경될때마다 데이터를 전송하며 데이터 요청종료(ETK_Unadvise())를 하면 데이터 전송을 멈춘다.
• 실시간TR은 요청 당시의 데이터를 전송해주지 않으므로 시세등 실시간으로 변하는 데이터를 받기 위해서는 조회TR을 요청하여 당시의 데이터를 받은 이후에 실시간TR을 요청하여 실시간 데이터를 받아야 한다.

데이터 처리 Diagram

• 1. 조회TR 요청(ETK_RequestData(), ETK_RequestDataEx())
• 2. 조회TR에 대한 응답 : 조회TR 요청시 등록한 윈도우로 XM_RECEIVE_DATA 메시지 전송
• 3. 조회 데이터 처리
• 4. 실시간 데이터가 필요하면 실시간 등록 이후에 사용하며 사용이 완료된 이후에 실시간 해제 호출
• 5. 실시간 데이터 등록은 원할때에 해도 되지만 조회 Data를 받은 이후에 하는 것을 추천 

• 조회 TR은 서버에 데이터를 요청했을때 현재 데이터를 전송한다.
• 요청하여 데이터를 전송한 이후에 데이터가 변경이 되었을 경우 재전송이 이루어지지 않는다.
• 여러 TR을 하나의 윈도우에서 사용하는 경우 데이터를 요청했을때 획득하는 Request ID로 구별한다.
• Data를 받은 이후에 상황별로 데이터를 해제해주서야 한다.
• Data는 Data -> Message -> Release 순으로 오게 된다.
• System Error는 Data 처리 이전에 System 문제로 인하여 Data 처리가 불가능할 경우에 발생하며 이 경우엔 Data/Message/Release 가 전송되지 않는다.

조회성TR 처리 Diagram

• 1. 조회성 TR 전송 : Request ID 획득
• 2. 조회성 TR 수신 : 조회성TR 전송시 등록한 윈도우로 XM_RECEIVE_DATA 메시지 전송

  타입1

  WPARAM	내용	설명
  1	Data	- 요청한 Data를 전송 - Data가 없거나 에러가 발생한 경우 수신되지 않을 수 있음
  2	Message	- Data 처리에 대한 Message - Data 처리에 성공을 해도 실패를 해도 Message는 발생한다. - Message Data를 처리하고 더이상 사용하지 않을 경우 ETK_ReleaseMessageData()를 호출하여 Message를 해제하여야 한다.
  3	System Error	- Data 처리 이전에 System 문제로 인한 Error가 발생할 경우에 전송 - Message Data를 처리하고 더이상 사용하지 않을 경우 ETK_ReleaseMessageData()를 호출하여 Message를 해제하여야 한다. - System Error이 발생할 경우 Release가 전송되지 않으며 ETK_ReleaseMessageData()에서 자동으로 Request ID를 해제해준다.
  4	Release	- Data 처리가 완료된 경우에 전송 - Request ID를 해제하기 위해 ETK_ReleaseRequestData()를 호출하여야 한다.

  • Request ID란?
    - 서버에 데이터를 전송하게 되면 부여받게 되는 ID로 서버로부터 데이터를 받을때 ID 값을 같이 받게 되므로 전송한 값에 대한 수신값을 찾을 수 있다.
    - Request ID는 X-ing API에서 관리하므로 수신이 완료가 되면 해제해주서야 한다.
    - Request ID는 0~255사이의 값을 사용하며 해제하지 않으면 255개의 전송이 이루어진 이후에는 전송이 불가능하다. 

• 서버에 데이터를 요청한 이후에 데이터가 변경이 되었을 경우 전송이 이루어집니다.
• 데이터를 더이상 받고 싶지 않을 경우에는 요청취소를 해야 합니다.
• 요청한 시점의 데이터는 전송하지 않으므로 조회TR을 이용하여 현재의 데이터를 가져와야 합니다.

실시간TR 처리 Diagram

• 1. 실시간TR을 등록합니다.
• 2. 실시간 데이터가 변경되면 해당 데이터를 등록했을때 설정한 윈도우로 XM_RECEIVE_REAL_DATA 메시지를 통해서 전송합니다.
• 3. 더 이상 필요가 없다면 실시간TR을 해제합니다.

실시간 TR을 등록하는 시점은?

• 실시간TR을 등록할 당시의 데이터는 전송하지 않으므로 조회TR을 전송하여 데이터를 받아야 합니다.
• 조회TR을 서버로 전송함과 동시에 실시간TR을 등록하게 되면 조회TR을 받기 전에 실시간TR을 받을수 있으며
• 조회TR에 대한 수신을 받고 나서 실시간TR을 등록하게 되면 수신후의 등록시점까지 변경되는 데이터는 받을 수 없다는 문제가 있습니다.
• 이 두가지 중에 어떤것을 택하느냐는 개발자의 선택입니다.
• X-ing 에서는 대부분 수신을 받은후에 실시간TR을 등록하지만 상황에 따라서는 조회TR을 전송함과 동시에 등록하는 경우도 있습니다.  

• 1. 각 TR에는 Header Type이 정해져 있으며
• 2. X-ing 에서 사용하는 Header Type은 총 4가지가 있다.
• 3. Header Type은 해당 TR의 속성을 결정지으며 처리방식이 약간씩 다르다.
• 4. TR에 대한 Header Type은 다음과 같이 알아낼수 있다.

타입1

	A Type	B Type	C Type	D Type
데이터 성격	시세 투자정보	대부분 원장(계좌) 정보	대부분 원장(계좌)외의 Database 정보	대부분 계좌정보 중 주문/계좌관련 정보
Data Mode	Block	Non-Block	Non-Block	Non-Block
연속처리	Input TR의 필드로 처리	ETK_RequestDataEx()의 인자값으로 처리	Input TR의 필드로 처리	Input TR의 필드로 처리
ETK_RequestData() 사용	○	×	×	×
ETK_RequestDataEx() 사용	×	○	○	○

• 1. TR의 필드에는 Data Type 이 존재
• 2. Data Type 에 따라 전송/수신시 처리 방식이 다름

타입1

	String	Int	Float
성격	문자열	정수	실수
길이	문자열의 최대 길이 예) 12 : 최대 12자리의 문자열	정수의 최대 길이 예) 5 : 최대 5자리의 정수	정수부와 소수부로 나뉨 정수부는 소수부 포함 최대 길이 소수부는 소수부 최대 길이 예) 6.2 소수부분은 2자리 정수 부분이 3자리 혹은 4자리인 실수 정수부분에 “.” 가 생략되는 경우에는 정수부가 4자리 예) 123.45 => 123.45 123456 => 1234.56
서버 전송/수신시	왼쪽 정렬 남는 영역은 ‘ ‘ 로 채움 [예] 길이:5 데이터:"ABC"	오른쪽 정렬 남는 영역은 ‘0’ 으로 채움 [예] 길이:5 데이터:"123"	오른쪽 정렬 남는 영역은 ‘0’ 으로 채움 [예] <소수점을 포함하지 않는 경우> 길이:6.2 데이터:12.45 <소수점을 포함하는 경우 > 길이:6.2 데이터:12.45

• 1. 해당 필드의 속성을 결정
• 2. Attribute 속성이 있는 TR 이면 필드 뒤에 항시 1바이트의 Attribute를 가진다.
       예) 7의 길이를 가진 현재가 필드는 7바이트의 현재가와 1바이트의 Attribute로 전송/수신된다.
• 3. 1 Byte 의 Attribute는 각 비트마다 의미가 있다.

타입1

	제목	설명	구분값	비고
0번째 비트	Font Resize	화면 확대시 글꼴크기 변경 여부		사용하지 않음
1번째 비트	Reverse	글자색과 배경색이 바뀌는지 여부	0:바뀌지 않음 1:바뀜	현재가가 상하한가일 경우에 사용됨
2번째 비트	Protect	입력불가 여부	0:입력가능 1:입력불가	사용하지 않음
3번째 비트	Cursor			사용하지 않음
4번째 비트	Color	글자색	1:Black 2:Blue(하락) 3:Red(상승) 4:Green(보합) 5:Brown 6:Cyan 7:LightRed	현재가 등에서 글자색을 표시하기 위해 사용
5번째 비트
6번째 비트
7번째 비트	Use	Attribute 사용여부	0:사용하지 않음 1:사용	0으로 세팅될 경우 Attribute는 무시

---

• 1. Occurs는 배열 형식의 데이터를 일컫습니다.
• 2. 예를 들면 Grid 안에 들어가는 데이터(체결내역/잔고내역등)가 배열 형식의 데이터입니다.
• 3. Occurs는 DataMode에 따라 처리방식이 다릅니다.

• . 연속조회는 많은 양의 Occurs 데이터를 한번에 전송/수신 하지 않고 나누어서 전송/수신하는 것을 일컫습니다.
• 2. 주식시세 과거데이터등은 한번에 보내기에는 방대한 양이므로 연속조회를 이용합니다.
  
• 3. 체결/잔고 등의 Database를 이용하는 경우에도 한번에 많은 양의 Query가 이뤄지면 DB가 Lock이 걸리므로 연속조회를 이용하여 데이터를 보냅니다.
• 4. Data Header Type에 따라 연속조회 방식이 다릅니다.

  타입1

  Header Type	연속조회 방식
  A	직전에 받은 OutBlock의 특정필드(CTS_XXXX)값을 입력값으로 넣어줍니다.
  B	직전에 받은 RECV_PACKET 안의 Continue Key 값을 ETK_RequestDataEx()의 인자로 넣어줍니다.
  C	직전에 받은 OutBlock의 특정필드(CTS_XXXX)값을 입력값으로 넣어줍니다.
  D	직전에 받은 OutBlock의 특정필드(CTS_XXXX)값을 입력값으로 넣어주고 직전에 받은 RECV_PACKET 안의 Continue Key 값을 ETK_RequestDataEx()의 인자로 넣어줍니다.

• [연속조회 기본개념]
• 1. 초기 전송시 Next Key는 SPACE로 전송
• 2. 서버에서 다음 데이터가 있으면 다음 데이터의 시작위치를 Next Key로 전송
• 3. 서버로부터 Next Key를 받으면 다음 TR전송시 받은 Next Key를 같이 전송
• 4. 서버로부터 Next Key를 받지 못하였다면 더 이상 연속데이터는 없음 

• Connect / Disconnect
• Login
• 조회TR
• 실시간TR
• 계좌관련
• 정보
  

Connect / Disconnect

ETK_Connect	서버와 연결합니다.
ETK_IsConnected	서버와의 연결여부를 취득합니다..
ETK_Disconnect	서버와의 연결을 종료합니다.

Login

ETK_Login	서버에 로그인합니다.
ETK_Logout	서버에서 로그아웃합니다.

조회TR

ETK_RequestData	TR을 서버에 요청합니다.(Data Header = A)
ETK_RequestDataEx	TR을 서버에 요청합니다.(Data Header = B, C, D)
ETK_ReleaseRequestData	수신 데이터를 삭제하고 RequestID를 해제합니다.
ETK_ReleaseMessageData	수신 메시지를 삭제합니다.

실시간TR

ETK_AdviseRealData	실시간 TR을 등록합니다.
ETK_UnadviseRealData	등록된 실시간 TR을 해제합니다.
ETK_UnadviseWindow	윈도우에 등록된 모든 실시간 TR을 해제합니다.

계좌관련

ETK_GetAccountListCount	계좌의 개수를 취득합니다.
ETK_GetAccountList	계좌를 취득합니다.

정보

ETK_GetCommMedia	통신매체를 취득합니다.
ETK_GetETKMedia	당사매체를 취득합니다.
ETK_GetClientIP	PC의 IP(Virtual IP)를 취득합니다.
ETK_GetServerName	접속한 서버의 이름을 취득합니다.
ETK_GetLastError	마지막에 발생한 Error Code를 취득합니다.
ETK_GetErrorMessage	Error Code에 대한 메시지를 취득합니다.

XM_RECEIVE_REAL_DATA = 4

XM_LOGIN = 5

XM_LOGOUT = 6

XM_TIMEOUT = 7

RECV_PACKET

서버로부터 조회 데이터를 받았을때 해당 Structure로 데이터가 들어온다.

필드	Data형	크기	설명
RequestID	정수	4	ETK_RequestData(), ETK_RequestDataEx() 함수를 호출했을때 Return 값
Data Length	정수	4	Data 의 메모리 크기
Total Data Buffer Size	정수	4	Data 의 메모리에 할당된 크기
ElapsedTime	정수	4	데이터 요청에서부터 데이터를 수신했을때까지 걸린 시간(1/1000초 단위)
DataMode	정수	4	1 : Block Mode 2 : Non Block Mode
TR Code	문자열	6	요청한 TR Code (마지막 1 Byte는 NULL)
Continue	문자열	1	'0' : 연속조회 없음 '2' : 연속조회 있음
Continue Key	문자열	19	연속조회가 있을 경우 Data Header가 B 일 경우 이 값이 다음 조회시 Key 가 된다. (마지막 1 Byte는 NULL)
User Data	문자열	31	사용안함
Block Name	문자열	17	Block 명, Block Mode 일 경우에 의미있다. (마지막 1 Byte는 NULL)
Data	문자열 포인터	4	수신된 TR 데이터

RECV_REAL_PACKET

서버로부터 실시간 데이터를 받았을때 해당 Structure로 데이터가 들어온다.

필드	Data형	크기	설명
TR Code	문자열	4	TR Code (마지막 1 Byte는 NULL)
Key Length	정수	4
Key	문자열	33	(마지막 1 Byte는 NULL)
RegKey	문자열	33	(마지막 1 Byte는 NULL)
Data Length	정수	4
Data	문자열 포인터	4	실시간 데이터

MSG_PACKET

서버로부터 데이터를 받았을때 해당 Structure로 데이터가 들어온다.

필드	Data형	크기	설명
Request ID	정수	4	Request ID
System Error	정수	4	0 : Message 1 : System Error
Message Code	문자열	6	Message Code (마지막 1 Byte는 NULL)
Message Data Length	정수	4	Message Data 길이
Message Data	문자열 포인터	4	Message Data

• 주식/ELW:
• 시세
• 주문
• 계좌
  
• 선물/옵션 :
• 시세
• 주문
• 계좌
  
• 투자정보
• 챠트
• 업종
• 투자자
• 프로그램
• 기타

전체 TR