MCI Server (TCP) 통신 서비스

eXDevice+ Agent를 중계 서버로 활용하여 웹 브라우저가 외부 한화생명 MCI(Message Communication Interface) 서버와 직접 TCP 소켓 통신을 수행할 수 있도록 지원하는 전용 프로토콜 서비스입니다.

sequenceDiagram
    autonumber
    actor User as 웹 브라우저 (JS)
    participant Agent as eXDevice+ Agent
    participant MCI as 한화생명 MCI Server

    User->>Agent: mcipush.Connect (IP, Port, Timeout, Alive Check 주기)
    Agent->>MCI: TCP Socket Connect
    MCI-->>Agent: 연결 완료
    Agent-->>User: 응답 (statusCode: 0000, serviceId 발급)

    User->>Agent: mcipush.SaveDisposeMessage (serviceId, 종료시전송메시지)
    Agent-->>User: 저장 완료

    loop Alive Check (주기적)
        Agent->>MCI: Ping ("00000003req")
        MCI-->>Agent: Pong ("00000003res")
    end

    User->>Agent: mcipush.SendMessage (serviceId, 전문내용)
    Agent->>MCI: TCP 전문 전송 ("8bytes Length" + 전문내용)

    MCI->>Agent: Async Push 메시지 수신 ("8bytes Length" + 메시지)
    Agent->>User: mcipush.Listener 이벤트 알림

    User->>Agent: mcipush.Disconnect (serviceId)
    Agent->>MCI: 사전 저장된 Dispose Message 송신 후 소켓 Close
    Agent-->>User: 연결 해제 완료

1. 통신 아키텍처 및 다중 소켓 접속 구조

tcpsvc.dll은 하나의 웹소켓 클라이언트(브라우저)에서 다중 TCP 서버와의 소켓 연결을 지원하며, 단일 웹소켓 연결 상에서 동일한 TCP 서버에 대해 2개 이상의 다중 소켓 세션을 동시에 수립하고 독립적으로 제어할 수 있습니다.

flowchart TD
    subgraph Browser["웹 브라우저"]
        WSClient1["ws client 1"]
        WSClient2["ws client 2"]
    end

    subgraph Agent["eXDevice+ Agent (tcpsvc.dll)"]
        Sock1["tcpsvc socket 1"]
        Sock2["tcpsvc socket 2"]
        Sock3["tcpsvc socket 3"]
        Sock4["tcpsvc socket 4"]
    end

    subgraph Servers["한화생명 MCI 서버군"]
        Server1["TCP Server (1)"]
        Server2["TCP Server (2)"]
    end

    WSClient1 -->|"동일 Client에서 다중 TCP 소켓 연결"| Sock1
    WSClient1 -->|"동일 Client에서 다중 TCP 소켓 연결"| Sock2
    WSClient2 --> Sock3
    WSClient2 --> Sock4

    Sock1 --> Server1
    Sock2 --> Server1
    Sock3 --> Server2
    Sock4 --> Server2

2. TCP 패킷 통신 프로토콜 (Packet Frame Format)

eXDevice+와 한화생명 MCI 서버 간의 TCP 데이터 송수신은 "고정 8바이트 메시지 길이 헤더(Length)" + "가변 전송 메시지 본문(Body)" 규격을 준수합니다.

+------------------------------------+----------------------------------------------------+
|       Length (고정 8 Bytes)        |          Body (가변 길이 전송 메시지 본문)          |
+------------------------------------+----------------------------------------------------+
| 0 | 0 | 0 | 0 | 0 | 0 | 1 | 5      | T | o |   | S | e | n | d |   | M | e | s | s | a | g | e |
+------------------------------------+----------------------------------------------------+

3. Keep-Alive (Ping-Pong) 동작 메커니즘

4. 브라우저 TCP 세션 식별 키 관리

하나의 웹소켓 연결에서 여러 TCP 소켓을 식별하고 제어하기 위해 브라우저는 다음 두 가지 키값을 관리해야 합니다.

No. Key 명칭 확인 가능 시점 주요 용도 및 역할
1 requestKey 브라우저에서 mcipush.Connect 호출 시 생성한 키 서버로부터 비동기 mcipush.Listener 푸시 메시지 수신 시 어떤 TCP 서버/소켓에서 온 메시지인지 식별하기 위한 식별자
2 serviceId mcipush.Connect 호출 성공 시 응답받은 세션 ID 해당 TCP 소켓을 대상으로 추가 서비스(mcipush.SendMessage, mcipush.SaveDisposeMessage, mcipush.Disconnect)를 요청할 때 식별자로 사용

서비스 리스트

No. 서비스명 API명 비고
1 MCI 서버 TCP 연결 mcipush.Connect TCP 소켓 연결 및 serviceId 발급
2 Disconnect 메시지 등록 mcipush.SaveDisposeMessage 소켓 해제 시 자동 송신 메시지 등록
3 메시지 전송 mcipush.SendMessage MCI 서버로 전문 송신
4 MCI Push 메시지 수신 mcipush.Listener 비동기 Push 수신 이벤트 (직접 호출 불가)
5 MCI 서버 연결 해제 mcipush.Disconnect TCP 소켓 연결 종료

서비스 상태 코드 리스트

1. 서비스 응답 상태 코드 (tcpsvcCode)

mcipush 서비스 API 호출 결과 객체의 return 또는 return.returnValue 값 매핑표입니다.

리턴코드 내용 조치 가이드
0 성공 정상 처리되었습니다.
-1 정의되지 않은 예외 eXDevice+ 로그 파일을 확인하시길 바랍니다.
1 이미 연결됨 MCI Server와 이미 연결되어 있습니다. 기존 연결 해제 후 재연결을 수행하시길 바랍니다.
2 잘못된 IP 주소 유효하지 않은 IP 주소가 입력되었습니다. 입력한 IP 주소를 확인하시길 바랍니다.
3 잘못된 Port 번호 유효하지 않은 Port 넘버가 입력되었습니다. 입력한 Port 넘버를 확인하시길 바랍니다.
4 MCI 서버 연결 불가 MCI Server와 연결할 수 없습니다. MCI Server의 주소 또는 네트워크 연결을 확인하시길 바랍니다.
5 연결 종료됨 사용자/eXDevice+에 의해 MCI Server와의 연결이 종료되었습니다.
6 연결 타임아웃 MCI Server와 연결 중 타임아웃이 발생했습니다. MCI Server의 주소 또는 네트워크 연결을 확인하시길 바랍니다.
7 미연결 상태 MCI Server에 연결되어 있지 않습니다. serviceId 유효성 및 사전 연결을 확인하시길 바랍니다.
8 Disconnect 실패 MCI Server로부터 Disconnect에 실패했습니다.
9 메시지 전송 실패 MCI Server에 메시지 전송에 실패했습니다.
10 LogFormat 설정 오류 유효하지 않은 LogFormat이 입력되었습니다. modules.json을 확인하시길 바랍니다.

2. 푸시 리스너 상태 코드 (listenerCode)

리턴코드 내용 상세 설명
0 성공 정상적으로 푸시 메시지를 수신했습니다.
-1 정의되지 않은 예외 로그 파일을 확인하시길 바랍니다.
1 연결 해제됨 MCI 서버와 연결이 해제되었습니다.
2 Pong 미수신 MCI 서버로부터 pong을 받지 못했습니다.
3 전문 길이 포맷 오류 MCI 서버로부터 수신한 Message length 데이터가 Integer 값이 아닙니다.

1. MCI 서버 TCP 연결

API명

정의

호출 예시

{
  "service": "mcipush.Connect",
  "requestKey": "MCI_SOCK_01",
  "param": {
    "serverIp": "127.0.0.1",
    "serverPort": "9480",
    "socketTimeout": "3000",
    "retry": "3",
    "pingTimeout": "3000",
    "pingInterval": "600000"
  }
}

응답 예시

{
  "service": "mcipush.Connect",
  "requestKey": "MCI_SOCK_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "serviceId": "0c089b51-083b-4654-8261-aa2220ebf809"
  }
}

2. Disconnect 메시지 등록

API명

정의

호출 예시

{
  "service": "mcipush.SaveDisposeMessage",
  "requestKey": "REQ_SAVE_DISP_01",
  "param": {
    "serviceId": "0c089b51-083b-4654-8261-aa2220ebf809",
    "message": "DISCONNECT|CLIENT_SESSION_CLOSE"
  }
}

응답 예시

{
  "service": "mcipush.SaveDisposeMessage",
  "requestKey": "REQ_SAVE_DISP_01",
  "statusCode": "0000",
  "return": 0
}

3. 메시지 전송

API명

정의

호출 예시

{
  "service": "mcipush.SendMessage",
  "requestKey": "REQ_MCI_SEND_01",
  "param": {
    "serviceId": "0c089b51-083b-4654-8261-aa2220ebf809",
    "message": "TR001|20260901|REQ_LOAN_STATUS|CUSTOMER_001"
  }
}

응답 예시

{
  "service": "mcipush.SendMessage",
  "requestKey": "REQ_MCI_SEND_01",
  "statusCode": "0000",
  "return": 0
}

4. MCI Push 메시지 수신

API명

정의

수신 메시지 예시 (브라우저 수신 형태)

{
  "service": "mcipush.Listener",
  "requestKey": "MCI_SOCK_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "message": "TR001|RES_LOAN_STATUS|SUCCESS|BALANCE:5000000"
  }
}

5. MCI 서버 연결 해제

API명

정의

호출 예시

{
  "service": "mcipush.Disconnect",
  "requestKey": "REQ_MCI_DISC_01",
  "param": {
    "serviceId": "0c089b51-083b-4654-8261-aa2220ebf809"
  }
}

응답 예시

{
  "service": "mcipush.Disconnect",
  "requestKey": "REQ_MCI_DISC_01",
  "statusCode": "0000",
  "return": 0
}
버전 #1