eXDevice+ 1.0 API 가이드

eXDevice+ 고객 지원 가이드 문서

eXDevice+ 공통

eXDevice+ 기본 API

eXDevice+ 공통

서비스 및 통신 프로토콜

 eXDevice+는 WebSocket을 통해 브라우저(WebSocket Client)들과 통신을 수행합니다.

 브라우저는 eXDevice+에 WebSocket 메시지를 전송해 eXDevice+가 제공하는 서비스들을 호출할 수 있으며, 요청/응답 프로토콜은 사전 정의된 JSON 프로토콜을 따릅니다.

1. 서비스 정의

 eXDevice+ 에서 정의하는 서비스란 브라우저 제약 사항으로 인해 브라우저에서 수행할 수 없는 기능들을 의미합니다.

 본 가이드 문서에서 제공하는 서비스들은 Installer를 통해 eXDevice+를 PC에 설치하는 경우 기본적으로 사용할 수 있는 서비스들에 대해 작성되어 있습니다.

image.png

<eXDevice+ 서비스 호출 과정>

2. eXDevice+ 요청 프로토콜

 WebSocket Client가 eXDevice+의 특정 서비스를 호출하기 위한 포맷입니다.

{
  "service":"호출할 서비스 명칭",
  "requestKey":"어떤 서비스에 대한 응답인지 식별할 Key값",
  "param":{
    "파라미터 명칭":"파라미터 값",
    ...
  }
}

3. eXDevice+ 응답 프로토콜

 WebSocket Client가 eXDevice+에게 요청한 서비스의 응답을 수신하기 위한 포맷입니다.

{
  "service":"WebSocket Client가 요청한 서비스 명칭",
  "requestKey":"WebSocket Client가 송신한 Key값",
  "statusCode":"eXDevice+ 상태 코드"
  "return":"서비스 호출 결과 값"
}

4. eXDevice+ 상태 코드

 eXDevice+ 상태 코드는 기본적으로 "0000"이 리턴되는 경우 정상적으로 서비스를 호출한 상태입니다. 즉, "0000"을 제외한 상태 코드는 eXDevice+가 서비스를 호출하지 못한 이유에 대한 코드입니다.

4.1. 1000번대

 1000번대 상태 코드는 일반적으로 WebSocket Client가 전송한 요청 메시지에 의해 발생합니다. 해당 상태 코드가 출력되는 경우 WebSocket Client에서 송신하는 요청 메시지와 가이드 문서의 서비스를 확인하시길 바랍니다.

상태코드 분류 상태코드 상세 비고
1000 정의되지 않은 통신 예외 - Log 파일 확인
1001 JSON 포맷이 아닌 요청 요청 메시지가 JSON 포맷이 아님 -
1002 요청 프로토콜 불일치 요청 프로토콜과 일치 하지 않는 JSON 포맷 -
1003 필수 정보 누락 Service 호출에 필요한 필수 정보 누락 -
1004 지원하는 서비스 없음 서비스 설정 파일(module.json)에 기재된 서비스 없음 -
1005 지원하지 않는 서비스 지원하지 않는 서비스 요청 -
1006 파라미터 불일치 요청 메시지 파라미터가 서비스 호출 파라미터와 불일치 -
1007 파라미터 타입 변환 실패 파라미터 데이터 타입 불일치 -
1008 serviceId 누락 요청 메시지에 serviceId 정보 누락 -

4.2. 2000번대

 2000번대 상태 코드는 일반적으로 서비스 식별 및 생성 단계에서 발생합니다. 해당 상태 코드가 반복적으로 출력되는 경우 서비스 설정 파일(modules.json)을 확인하거나, 기술지원을 받으시길 바랍니다.

상태코드 분류 상태코드 상세 비고
2000 정의되지 않은 서비스 예외 - Log 파일 확인
2001 libType 정보 누락 설정 파일에 정보 누락 modules.json 확인
2002 지원하지 않는 libType 설정 파일에 유효하지 않은 정보 기재되어 있음 modules.json 확인
2003 libFile 정보 누락 설정 파일에 정보 누락
 modules.json 확인
2004 delegator 정보 누락 설정 파일에 정보 누락
 modules.json 확인
2005 지원하지 않는 delegator 설정 파일에 유효하지 않은 정보 기재되어 있음 modules.json 확인
2006 destDir 정보 누락 설정 파일에 정보 누락 modules.json 확인
2007 CLSID 정보 누락 설정 파일에 정보 누락 modules.json 확인
2008 지원하지 않는 param 타입 설정 파일에 유효하지 않은 정보 기재되어 있음 modules.json 확인
2009 지원하지 않는 return 타입 설정 파일에 유효하지 않은 정보 기재되어 있음 modules.json 확인
2010 지원하지 않는 returnObject 타입 설정 파일에 유효하지 않은 정보 기재되어 있음 modules.json 확인
2011 delegator 생성 실패 객체 생성 실패 Log 파일 확인
2012 subForm 생성 실패 객체 생성 실패 Log 파일 확인
2013 libType 오용 serviceId를 발급 받을 수 없는 서비스에 serviceId 사용 modules.json 확인

4.3. 3000번대

 3000번대 상태 코드는 일반적으로 서비스 호출 단계에서 발생합니다.

상태코드 분류 상태코드 상세 비고
3000 정의되지 않은 서비스 호출 예외 - Log 파일 확인
3001 파일 누락 대상 서비스 파일이 로컬에 존재하지 않음 -
3002 레지스트리 등록 누락 대상 서비스 파일이 레지스트리에 등록되지 않음 -
3003 라이브러리 식별 실패 native Dll/managed Dll 식별 실패 -
3004 라이브러리 로드 실패 라이브러리 메모리 로드 실패 -
3005 지원하지 않는 라이브러리 eXDevice+에서 지원하지 않는 라이브러리 확장자 로드 -
3006 export된 class 없음 라이브러리에서 export된 class 없음 -
3007 대상 class 찾을 수 없음 라이브러리에서 대상 class 찾을 수 없음 -
3008 export된 method 없음 class에서 export 된 method 없음 -
3009 대상 method 찾을 수 없음 class에서 대상 method 찾을 수 없음 -
3010 참조 타입 변환 실패 ref 데이터 타입 변환 실패 -
3011 Method IL 생성 실패 Method IL 생성 실패 -
3012 ActiveX 컨트롤 생성 실패 요청한 서비스를 제공할 ActiveX 컨트롤 생성 실패 -
3013 ActiveX 컨트롤 생성되지 않음 요청한 서비스를 제공하는 ActiveX 컨트롤 생성되지 않음 -
3014 참조 데이터 획득 실패 ref/out 타입의 데이터 값 획득 실패 -
3015 호출 결과 값 타입 변환 실패 Invoke 결과 값 데이터 타입 변환 실패 -
3016 결과 값 Dictionary 변환 실패 Invoke 결과 값 Dictionary<string, T> 변환 실패 -
3017 Client 연결 해제됨 서비스 객체를 소유한 Client의 WebSocket 연결 해제 stateful 서비스
3018 서비스 객체 검색 실패 대상 Client가 보유한 서비스 객체 검색 실패 stateful 서비스
3019 서비스 객체 추가 실패 대상 Client가 보유한 서비스 객체로 추가 실패 stateful 서비스
3020 등록되지 않은 serviceId 요청 등록되지 않은 serviceId가 요청 됨 stateful 서비스
3021 추상 서비스 객체 검색 실패 대상 Client가 보유한 추상 서비스 객체 검색 실패 stateful 서비스
3022 추상 서비스 객체 추가 실패 대상 Client가 보유한 추상 서비스 객체 추가 실패 stateful 서비스
3023 추상 서비스 객체 제거 실패 대상 Client가 보유한 추상 서비스 객체 제거 실패 stateful 서비스
3024 Client의 소유 서비스 제거 실패 대상 Client가 보유한 서비스 객체 제거 실패 stateful 서비스
3025 serviceId 이미 등록됨 대상 serviceId가 이미 등록되어 있음 stateful 서비스

4.4. 4000번대

 4000번 상태 코드는 eXDevice+에서 발생한 예외가 아닌, eXDevice+가 호출한 서비스를 보유한 DLL에서 발생한 예외입니다.  즉, eXDevice+가 서비스를 호출하기 직전까지는 예외가 발생하지 않았음(1000, 2000, 3000 해당 없음)을 의미합니다.

 4000번이 발생한 경우, 호출한 서비스에서 제공하는 상태 코드를 확인하시길 바랍니다.

eXDevice+ 공통

제공 서비스 리스트

 eXDevice+는 다음과 같은 서비스를 제공합니다.

기능 기준: agent, syssvc.dll 버전

서비스 그룹 서비스명 API명 agent 버전 syssvc 버전
eXDevice+ 정보 획득 제품 버전 확인 eXDeviceInfo 1.0.3 >= -

WebSocket client간 Websocket 통신

 Client 등록 및 수정 UpdateWsInfo 1.0.3 >= -
Client 리스트 획득 GetWsClients 1.0.3 >= -
자신의 식별 정보 조회 GetWsOwnInfo 1.0.3 >= -
push PushWsMessage 1.0.3 >= -
broadcast BroadcastWsMessage 1.0.3 >= -
push 수신 ReceiveWsPush 1.0.3 >= -
broadcast 수신 ReceiveWsBroadcast 1.0.3 >= -

원격 eXDevice+간 TCP Socket 통신

 Socket 서버 open OpenTcpServer 1.0.3 >= -
Socket 서버 close CloseTcpServer 1.0.3 >= -
Socket 서버 정보 획득 GetTcpServerInfo 1.0.3 >= -
endpoint 리스트 획득 GetTcpEndpoints 1.0.3 >= -
TCP 메시지 송신 SendTcpMessage 1.0.3 >= -
TCP 메시지 수신 ReceiveTcpMessage 1.0.3 >= -
Network 관련
 로컬 IPv4 주소 획득 WinInfo.GetIpAddress - 1.0.3.7 >=
로컬 MAC 주소 획득 WinInfo.GetMacAddress - 1.0.3.7 >=
모니터 관련
 연결된 모니터 개수 획득 WinInfo.GetConnectedScreenNumber - 1.0.3.7 >=
주 모니터 식별 WinInfo.PrimaryScreen - 1.0.3.7 >=
전체 모니터 식별 WinInfo.GetAllScreens - 1.0.3.7 >=
주 모니터 해상도 획득 WinInfo.GetPrimaryResolution - 1.0.3.7 >=
지정 모니터 해상도 획득 WinInfo.GetSpecialScreenResolution - 1.0.3.7 >=
전체 모니터 해상도 획득 WinInfo.GetAllScreenResolutions - 1.0.3.7 >=
프로세스 제어 관련
 타이틀 기반
프로세스 구동 체크		 WinInfo.CheckProcessRunningByTitle - 1.0.3.7 >=
PID 기반
프로세스 구동 체크		 Wininfo.CheckProcessRunningByPID - 1.0.3.7 >=
타이틀 기반
특정 프로세스 창 이동		 WinInfo.SetWindowPosition - 1.0.3.7 >=
타이틀 기반
특정 프로세스 창 최상단 배치		 WinInfo.BringWindowToTop - 1.0.3.7 >=
PID 기반
특정 프로세스 창 이동		 WinInfo.SetProcessWindowPosition - 1.0.3.9 >=
프로세스 IME 모드 변경 WinInfo.SetImeMode - 1.0.3.23 >=
프로세스 IME 모드 획득 WinInfo.GetImeMode - 1.0.3.23 >=
스크린샷 관련
 모니터 스크린샷 획득 WinInfo.GetScreenShot - 1.0.3.7 >=
모니터 스크린샷 저장 WinInfo.SaveScreenShot - 1.0.3.7 >=
타이틀 기반
프로세스 창 스크린샷 획득		 WinInfo.GetWindowScreenShot - 1.0.3.7 >=
타이틀 기반
프로세스 창 스크린샷 저장		 WinInfo.SaveWindowScreenShot - 1.0.3.7 >=
PID 기반
프로세스 창 스크린샷 획득		 WinInfo.GetProcessScreenShot - 1.0.3.7 >=
PID 기반
프로세스 창 스크린샷 저장		 WinInfo.SaveProcessScreenShot - 1.0.3.7 >=
파일 관련
 파일 open WinInfo.OpenFile - 1.0.3.14 >=
파일 read WinInfo.ReadFile - 1.0.3.14 >=
파일 write WinInfo.WriteFile - 1.0.3.14 >=
파일 delete WinInfo.DeleteFile - 1.0.3.14 >=
파일 copy WinInfo.CopyFile - 1.0.3.14 >=
파일 실행 WinInfo.RunFile - 1.0.3.14 >=
디렉토리 open WinInfo.OpenDirectory - 1.0.3.14 >=
파일 open dialog WinInfo.FileOpenDialog - 1.0.3.14 >=
파일 read dialog WinInfo.FileReadDialog - 1.0.3.14 >=
파일 write dialog WinInfo.FileWriteDialog - 1.0.3.14 >=
파일 리스트 획득 WinInfo.GetFileList - 1.0.3.14 >=
바로가기 생성 WinInfo.CreateShortcut - 1.0.3.28>=
프린터 관련

 기본 프린터 조회 WinInfo.GetDefaultPrinter - 1.0.3.22 >=
전체 프린터 조회 WinInfo.GetPrinterList - 1.0.3.22 >=
기본 프린터 설정 WinInfo.SetDefaultPrinter - 1.0.3.22 >=
기본 설정 조회 WinInfo.GetPrinterDefaultSettings - 1.0.3.27 >=

지원 트레이 리스트 조회

 WinInfo.GetPrinterTrays - 1.0.3.27 >=
지원 용지 리스트 조회 WinInfo.GetPrinterPapers - 1.0.3.27 >=
상세 정보 조회 WinInfo.GetPrinterDetails - 1.0.3.27 >=

eXDevice+ 공통

eXDevice+ 정보 획득 서비스

 현재 PC에 설치된 eXDevice+ 제품의  정보를 획득합니다.

서비스 리스트

 eXDevice+ 정보 획득 관련 서비스 리스트는 다음과 같습니다.

No. 서비스명 API 명 비고
1 제품 버전 확인 eXDeviceInfo

1. 제품 버전 확인

API명

정의 

설명

호출 예시

{
  "service":"eXDeviceInfo",
  "requestKey":"Randon Request Key",
  "param":{}
}

응답 예시

{
  "service":"eXDeviceInfo",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "name":"eXDevicePlus",
    "version":{"installer":"1.0.3.42","agent":"1.0.3.17"}
  }
}
eXDevice+ 공통

WebSocket client간 Websocket 통신 서비스

 현재 PC에서 구동 중인 Websocket client(브라우저, exe 등)들이 eXDevice+에 Websocket으로 연결하여 서로 Websocket 통신을 수행하기 위한 기능들을 제공합니다.

 eXDevice+를 사용한 client간 메시지를 송수하는 프로세스는 다음과 같습니다.

image.png

<WebSocket client간 Message Push>

image.png

<WebSocket client간 Message Broadcast>

서비스 리스트

 WebSocket client간 메시지를 주고 받는 서비스 리스트는 다음과 같습니다.

No. 서비스명 API명 비고
1 Client 등록 및 수정 UpdateWsInfo
2 Client 리스트 획득 GetWsClients
3 자신의 식별 정보 조회 GetWsOwnInfo
4 push PushWsMessage

- Unicast, Multicast 지원

- ReceiveWsPush로 메시지 수신
5 broadcast BroadcastWsMessage ReceiveWsBroadcast로 메시지 수신
6 push 수신 ReceiveWsPush 직접 호출 불가
7 broadcast 수신 ReceiveWsBroadcast 직접 호출 불가

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
1 PUSH 메시지를 수신할 client가 존재하지 않음 PushWsMessage -
2 일부 client에게 메시지 송신 실패 PushWsMessage, BroadcastWsMessage -
3 자신 외 다른 client가 연결되어 있지 않음 BroadcastWsMessage -
4 등록 요청한 식별 정보가 이미 등록되어 있음 UpdateWsInfo -
5 등록할 수 없는 식별 정보 데이터 UpdateWsInfo -

1. Client 등록 및 수정

API명

정의

설명

Client의 식별 정보(Info)는 고유한 정보이므로, 이미 다른 client가 등록한 식별 정보가 있는 경우 다른 client는 동일한 값의 식별 정보를 등록할 수 없습니다.

호출 예시

{
  "service": "UpdateWsInfo",
  "requestKey": "Random Request Key",
  "param": {
    "info": "Client를 설명할 수 있는 정보"
  }
}

응답 예시

{
  "service":"UpdateWsInfo",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

2. Client 리스트 획득

API명

정의 

UpdateWsInfo로 식별 정보를 등록한 client의 경우 식별 정보 값을 획득 할 수 있으며, 식별 정보를 등록하지 않은 client는 빈 값("")이 리턴 됩니다.

호출 예시

{
  "service": "GetWsClients",
  "requestKey": "Random Request Key",
  "param":{}
}

응답 예시

{
  "service": "GetWsClients",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue": 0,
    "infos": [
      {"id": "aaa-bbb-ccc", "info": "eXDevice+ Sample"},
      {"id": "000-111-222", "info": ""}
    ]
  }
}

3. 자신의 식별 정보 조회

API명

정의

UpdateWsInfo로 식별 정보를 등록한 client의 경우 식별 정보 값을 획득 할 수 있으며, 식별 정보를 등록하지 않은 client는 빈 값("")이 리턴 됩니다.

호출 예시

{
  "service": "GetWsOwnInfo",
  "requestKey": "Random Request Key",
  "param": {}
}

응답 예시

{
  "service": "GetWsOwnInfo",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue": 0,
    "id": "aaa-bbb-ccc", 
    "info": "eXDevice+ Sample"
  }
}

4. push

API명

정의

 Push 메시지를 수신 받는 WebSocket client의 수신 프로토콜은 ReceiveWsPush를 참고하시길 바랍니다.

송신 상태 코드 리스트

상태코드 상태 코드 내용 비고
1 메시지 수신 대상 WebSocket client 연결이 해제됨  
2 대상 WebSocket client에게 메시지 송신 실패  
3 서비스 요청한 WebSocket client 외 다른 WebSocket client가 연결되어 있지 않음  
4 대상 WebSocket client가 eXDevice+에 연결되어 있지 않음  

호출 예시

1. Unicast

 Unicast는 하나의 WebSocket client에게 Websocket 메시지를 송신하는 방식입니다. Unicast로 메시지 송신 시 "ID", "식별 정보", "ID&식별 정보"를 사용해 메시지를 송신할 WebSocket client를 지정할 수 있습니다.

 1) ID(GUID)를 사용한 Unicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param":{ 
    "receiver": "aaa-bbb-ccc",
    "message": "message to unicast"
  }
}

2) 식별 정보를 사용한 Unicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param":{ 
    "receiver":{
      "info": "Test WebSocket Client"
    },
    "message": "message to unicast"
  }
}

3) ID와 식별 정보 모두를 사용한 Unicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param":{ 
  "receiver":{
    "id" :"aaa-bbb-ccc", 
    "info": "Test Websocket Client"
  },
  "message": "message to unicast"
  }
}

2. Multicast

 Multicast는 다수의 WebSocket client에게 Websocket 메시지를 송신하는 방식입니다. Multicast로 메시지 송신 시 "ID", "식별 정보", "ID&식별 정보"를 사용해 메시지를 송신할 WebSocket client를 지정할 수 있습니다.

1) ID(GUID)를 사용한 Multicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param": { 
    "receiver": ["aaa-bbb-ccc", "000-111-222"],
    "message": "message to multicast"
  }
}

2) 식별 정보를 사용한 Multicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param": { 
    "receiver": [
      {"info": "Test Client1"}, 
      {"info": "Test Client2"}
    ],
    "message" :"message to multicast"
  }
}

3) ID와 식별 정보 모두를 사용한 Multicast

{
  "service": "PushWsMessage",
  "requestKey": "Random Request Key",
  "param": { 
    "receiver": [
      {"id": "aaa-bbb-ccc", "info": "Test Client1"},
      {"id": "000-111-222", "info": "Test Client2"}
    ],
    "message": "message to multicast"
  }
}

응답 예시

1. Push 성공

 Unicast, Multicast시 메시지 송신에 성공하면 eXDevice+로부터 다음과 같은 응답 메시지를 수신 받습니다.

 Push 실패 판단은 returnValue의 값에 따라 판단합니다.

{
  "service": "PushWsMessage",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue":0,
    "clients":[]
  }
}

2. Push 실패

 Unicast, Multicast시 메시지 송신에 실패하면 returnValue로 0 외의 값을 리턴 받습니다.

 각 client별 송신 실패 원인은 status의 송신 상태 코드를 통해 확인할 수 있습니다.

{
  "service": "PushWsMessage",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue":2,
    "clients":[
      {"id": "aaa-bbb-ccc", "info": "Test WebSocket Client", "status":1}
    ]
  }
}

5. broadcast

API명

정의

 Broadcast 메시지를 수신 받는 WebSocket client의 수신 프로토콜은 ReceiveWsBroadcast를 참고하시길 바랍니다.

송신 상태 코드 리스트

상태코드 상태 코드 내용 비고
1 메시지 수신 대상 WebSocket client 연결이 해제됨  
2 대상 WebSocket client에게 메시지 송신 실패  
3 서비스 요청한 WebSocket client 외 다른 WebSocket client가 연결되어 있지 않음  
4 대상 WebSocket client가 eXDevice+에 연결되어 있지 않음  

호출 예시

{
  "service": "BroadcastWsMessage",
  "requestKey": "Random Request Key",
  "param": {
    "mode":1
    "message": "message to broadcast"
  }
}

응답 예시

1. Broadcast 성공

 Broadcast시 메시지 송신에 성공하면 eXDevice+로부터 다음과 같은 응답 메시지를 수신 받습니다.

 Broadcast 실패 판단은 returnValue의 값에 따라 판단합니다.

{
  "service": "BroadcastWsMessage",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue":0,
    "clients":[]
  }
}

2. Broadcast 실패

 Broadcast시 메시지 송신에 실패하면 returnValue로 0 외의 값을 리턴 받습니다. 

 각 client별 송신 실패 원인은 status의 송신 상태 코드를 통해 확인할 수 있습니다.

{
  "service": "BroadcastWsMessage",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue":2,
    "clients":[
      {"id": "aaa-bbb-ccc", "info": "Test WebSocket Client", "status":1}
    ]
  }
}

6. push 수신

 API명

정의

설명

본 서비스는 직접 호출할 수 없습니다.

응답 예시

{
  "service":"ReceiveWsPush",
  "sender":{
    "id":"aaa-bbb-ccc",
    "info":"Sender test websocket"
  },
  "message":"Push message test."
}

7. broadcast 수신

 API명

정의

설명

본 서비스는 직접 호출할 수 없습니다.

응답 예시

{
  "service":"ReceiveWsBroadcast",
  "sender":{
    "id":"aaa-bbb-ccc",
    "info":"Sender test websocket"
  },
  "message":"Push message test."
}
eXDevice+ 공통

원격 eXDevice+간 TCP Socket 통신 서비스

 eXDevice+는 다른 원격 PC에 설치되어 있는 eXDevice+에게 메시지를 송신하기 위한 서비스를 제공합니다. 이때,  eXDevice+간 통신은 TCP Socket 통신을 통해 이루어집니다.

image.png

<eXDevice+간 TCP Socket 통신 구조>

 eXDevice+간 TCP Socket 통신을 위해 다음과 같은 정보가 필요하며, 해당 정보에 대한 관리는 별도의 서버 또는 시스템에서 CRUD가 지원되어야 합니다.

데이터 종류 설명 용도 비고
IP eXDevice+ TCP 서버 IP TCP 메시지를 수신 받기 위한 서버 IP 로컬 IP
Port eXDevice+ TCP 서버 port TCP 메시지를 수신 받기 위한 서버 port 지정 port
endpoint 메시지를 수신할 client 정보 최종적으로 메시지를 수신 받기 위한 client 식별 정보 지정 endpoint 명

 endpoint는 OpenTcpServer 서비스를 호출하며 등록하는 정보이며, 원격 WebSocket client가 어떤 WebSocket client에게 메시지를 전송할지 식별하기 위한 정보입니다. 다시 말해, endpoint는 일종의 사용자 ID와 유사한 역할을 수행합니다.

서비스 리스트

 원격 eXDevice+간 TCP Socket 통신 서비스 리스트는 다음과 같습니다.

No. 서비스명 API명 비고
1 Socket 서버 open OpenTcpServer 서버 open, endpoint 등록
2 Socket 서버 close CloseTcpServer 서버 close, endpoint 제거
3 Socket 서버 정보 획득 GetTcpServerInfo
4 endpoint 리스트 획득 GetTcpEndpoints
5 TCP 메시지 송신 SendTcpMessage ReceiveTcpMessage로 메시지 수신
6 TCP 메시지 수신 ReceiveTcpMessage 직접 호출 불가

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
1 TCP 서버 open실패 OpenTcpServer -
2 동일한 requestKey가 이미 등록됨 OpenTcpServer -
3 동일한 endpoint가 이미 등록됨 OpenTcpServer -
4 endpoint 등록 실패 OpenTcpServer -
5 TCP 서버가 open 되어 있지 않음

CloseTcpServer,

SendTcpMessage,

GetTcpServerInfo,

GetTcpEndpoint

 -
6 endpoint가 등록되어 있지 않음

CloseTcpServer,

GetTcpEndpoint

 -
7 endpoint 제거 실패 CloseTcpServer -
8 TCP 서버 종료 실패 CloseTcpServer -
9 TCP 메시지 전송 실패 SendTcpMessage -
10 원격 eXDevice+ TCP 서버 연결 실패 SendTcpMessage -
11 원격 eXDevice+의 endpoint가 연결 해제됨 SendTcpMessage -
12 원격 eXDevice+로 부터 TCP 수신 응답 획득 실패 SendTcpMessage -
13 원격 eXDevice+가 TCP 메시지 처리 중 오류 발생 SendTcpMessage -
14 원격 eXDevice+에 요청한 endpoint가 등록되어 있지 않음 SendTcpMessage -
15 원격 eXDevice+가 endpoint에게 메시지 전송 중 연결 해제됨 SendTcpMessage -
16 지정한 port 외 다른 port로 TCP 서버 open 됨 OpenTcpServer -
17 지정한 port가 다른 프로그램에서 사용 중 OpenTcpServer -

1. Socket 서버 open

API명

정의

설명

TCP 메시지를 수신 받는 WebSocket client의 프로토콜은 ReceiveTcpMessage를 참고하시길 바랍니다.

 eXDevice+는 TCP 서버 open 시 해당 PC의 IPv4 주소와, 입력한 port 넘버를 기준으로 서버를 open 합니다. 이때, eXDevice+는 하나의 TCP 서버만 open 할 수 있습니다.

호출 예시

{
  "service": "OpenTcpServer",
  "requestKey": "Random Request Key",
  "param": {
    "endpoint": "administrator"
  }
}

응답 예시

{
  "service":"OpenTcpServer",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

2. Socket 서버 close

API명

정의

설명

endpoint는 자신이 등록한 endpoint만을 제거할 수 있습니다.

호출 예시

{
  "service": "CloseTcpServer",
  "requestKey": "Random Request Key",
  "param": {
    "endpoint": "제거할 endpoint"
  }
}

응답 예시

{
  "service":"CloseTcpServer",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

3. Socket 서버 정보 획득

API명

정의

호출 예시

{
  "service": "GetTcpServerInfo",
  "requestKey": "Random Request Key",
  "param": {}
}

응답 예시

{
  "service":"GetTcpServerInfo",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue": 0,
    "ip": "123.123.123.123",
    "port":13441
  }
}

4. endpoint 리스트 획득

API명

정의

 다른 WebSocket client가 등록한 endpoint의 정보는 조회할 수 없습니다.

호출 예시

{
  "service": "GetTcpEndpoints",
  "requestKey": "Random Request Key...",
  "param": {}
}

응답 예시

{
  "service": "GetTcpEndpoints",
  "requestKey": "호출시 사용한 Request Key",
  "statusCode": "0000",
  "return":{
    "returnValue": 0,
    "endpointInfo": [
      {"requestKey":"9e1f-7026-863f","endpoint":"endpoint1"},
      {"requestKey":"797a-250c-7c94","endpoint":"endpoint2"}
    ]
  }
}

5. TCP 메시지 송신

API명

정의

설명

송신 타입 설명 비고
TCP 메시지 송신 TCP 메시지를 송신하되, WebSocket client의 응답을 받지 않습니다.
응답이 필요한 TCP 메시지 송신 TCP 메시지를 송신하고, WebSocket client의 응답을 받습니다.

응답 필요 유무는 서비스 호출 시 송신자의 endpoint 정보 포함 유무에 따라 나뉩니다.

호출 예시

1. TCP 메시지 송신

 응답이 필요하지 않은 TCP 메시지를 송신할 때, 송신자는 수신자가 자신을 식별할 수 있는 이름(name) 정보만 기입합니다.

{
  "service": "SendTcpMessage",
  "requestKey": "Random Request Key",
  "param": {
    "sender":{
      "name":"수신자가 식별할 수 있는 이름"
    },
    "receiver":{
      "ip":"123.123.123.123",
      "port":13441,
      "endpoint":"수신자가 eXDevice+에 등록한 endpoint"
    },
    "message":"송신하고자 하는 메시지"
  }
}

2. 응답이 필요한 TCP 메시지 송신

 응답이 필요한 TCP 메시지를 송신할 때 송신자는 OpenTcpServer를 통해 응답 메시지를 수신 받을 TCP 서버를 반드시 open 해야 합니다. 송신자는 TCP 메시지 송신 시 수신자가 송신자인 WebSocket client를 식별할 수 있는 endpoint 정보를 함께 기입합니다.

{
  "service": "GetTcpEndpoints",
  "requestKey": "Random Request Key",
  "param": {
    "sender":{
      "name":"수신자가 식별할 수 있는 이름",
      "endpoint":"응답 메시지를 수신 받기 위해 등록한 endpoint"
    },
    "receiver":{
      "ip":"123.123.123.123",
      "port":13441,
      "endpoint":"수신자가 eXDevice+에 등록한 endpoint"
    },
    "message":"송신하고자 하는 메시지"
  }
}

응답 예시

{
  "service":"SendTcpMessage",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

6. TCP 메시지 수신

API명

정의

설명

본 서비스는 직접 호출할 수 없습니다.

응답 예시

1. TCP 메시지 수신

 일반 TCP 메시지의 경우 송신자의 최소 정보(송신자 식별 정보)만이 메시지에 포함됩니다.

{
  "service":"ReceiveTcpMessage",
  "requestKey":"OpenTcpServer 호출 시 전달한 requestKey",
  "sender":{
    "name":"송신자 식별 정보"
  },
  "message":"TCP 메시지"
}

2. 응답이 필요한 TCP 메시지 수신

 응답이 필요한 TCP 메시지는 송신자의 eXDevice+ TCP 서버 정보 및, 메시지를 수신 받기 위한 WebSocket client의 식별 정보가 함께 전달됩니다.

{
  "service":"ReceiveTcpMessage",
  "requestKey":"OpenTcpServer 호출 시 전달한 requestKey",
  "sender":{
    "ip":"123.123.123.123",
    "port":13441,
    "endpoint":"WebSocket Client 식별 정보"
    "name":"송신자 식별 정보"
  },
  "message":"TCP 메시지"
}
eXDevice+ 공통

Network 관련 서비스

 본 서비스는 eXDevice+가 설치된 로컬 PC의 네트워크 관련 정보 획득을 지원합니다.

서비스 리스트

 Network 관련 서비스 리스트는 다음과 같습니다.

No. 서비스명 API 명 비고
1 로컬 IPv4 주소 획득 WinInfo.GetIpAddress
2 로컬 MAC 주소 획득 WinInfo.GetMacAddress

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
1 시스템 Lan 카드 정보 획득 실패 WinInfo.GetIpAddress -

1. 로컬 IPv4 주소 획득

API명

정의

호출 예시

{
  "service":"WinInfo.GetIpAddress",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetIpAddress",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "systemIpv4":"123.123.123.123"
  }
}

2. 로컬 MAC 주소 획득

API명

정의

호출 예시

{
  "service":"WinInfo.GetMacAddress",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetMacAddress",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "systemMacAddr":"ABCDEF12345"
  }
}
eXDevice+ 공통

모니터 관련 서비스

 본 서비스는 eXDevice+가 설치된 PC에 연결된 모니터의 정보 획득을 지원합니다.

서비스 리스트

 모니터 관련 서비스 리스트는 다음과 같습니다.

No. 서비스명 API명 비고
1 연결된 모니터 개수 획득 WinInfo.GetConnectedScreenNumber
2 주 모니터 식별 WinInfo.PrimaryScreen
3 전체 모니터 식별 WinInfo.GetAllScreens
4 주 모니터 해상도 획득 WinInfo.GetPrimaryResolution
5 지정 모니터 해상도 획득 WinInfo.GetSpecialScreenResolution
6 전체 모니터 해상도 획득 WinInfo.GetAllScreenResolutions

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
2 PC와 연결된 모니터 리스트 획득 실패

GetConnectedScreenNumber,

GetAllScreens

 -
3 요청 모니터 정보 획득 실패

PrimaryScreen,

GetPrimaryResolution
4 모니터 해상도 획득 실패 GetPrimaryResolution

1. 연결된 모니터 개수 획득

API명

정의

호출 예시

{
  "service":"WinInfo.GetConnectedScreenNumber",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetConnectedScreenNumber",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenNumber":3
  }
}

2. 주 모니터 식별

API명

정의

설명

모니터 이름은 시스템이 해당 모니터를 식별하기 위해 임의로 발급한 이름입니다. 즉, 본 서비스를 통해 획득하는 모니터의 이름은 제조사, 모델명과 무관한 이름입니다.

호출 예시

{
  "service":"WinInfo.GetPrimaryScreen",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetPrimaryScreen",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "primaryScreen":"DISPLAY5"
  }
}

3. 전체 모니터 식별

API명

정의

설명

모니터 이름은 시스템이 해당 모니터를 식별하기 위해 임의로 발급한 이름입니다. 즉, 본 서비스를 통해 획득하는 모니터의 이름은 제조사, 모델명과 무관한 이름입니다.

호출 예시

{
  "service":"WinInfo.GetAllScreens",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetAllScreens",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenInfos":{
      "Screen0":"DISPLAY1",
      "Screen1":"DISPLAY5",
      "Screen2":"DISPLAY4"
    }
  }
}

4. 주 모니터 해상도 획득

API명

정의

설명

K-017.png

<Windows 모니터 해상도 식별 방식>

호출 예시

{
  "service": "WinInfo.GetPrimaryResolution",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetPrimaryResolution",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenResolution":{
      "width":1920,
      "height":1080,
      "left":0,
      "top":0
    }
  }
}

5. 지정 모니터 해상도 획득

API명

정의

설명

image.png<해상도가 동일한 주 모니터, 보조 모니터 좌표 예시>

호출 예시

{
  "service": "WinInfo.GetSpecialScreenResolution",
  "requestKey": "Random Request Key",
  "param": { 
    "screenIndex": 1
  }
}

응답 예시

{
  "service":"WinInfo.GetSpecialScreenResolution",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenResolution":{
      "width":1920,
      "height":1080,
      "left":-1920,
      "top":0
    }
  }
}

6. 전체 모니터 해상도 획득

API명

정의

설명

image.png<해상도가 동일한 주 모니터, 보조 모니터 좌표 예시>

호출 예시

{
  "service":"WinInfo.GetAllScreenResolutions",
  "requestKey":"Random Request Key",
  "param":{}
}

응답 예시

{
  "service":"WinInfo.GetAllScreenResolutions",
  "requestKey":"f3a5-4de9-8fbb",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenResolution":[
      {"name":"DISPLAY1","width":1920,"height":1080,"left":-1920,"top":0},
      {"name":"DISPLAY5","width":1920,"height":1080,"left":0,"top":0},
      {"name":"DISPLAY4","width":1080,"height":1920,"left":1920,"top":-543}
    ]
  }
}
eXDevice+ 공통

프로세스 제어 관련 서비스

 본 서비스는 시스템에서 실행 중인 특정 프로세스 또는 특정 프로세스의 창을 조작하기 위한 기능을 지원합니다.

서비스 리스트

 프로세스 제어 관련 서비스 리스트는 다음과 같습니다.

No. 서비스명 API명 비고
1 타이틀 기반 프로세스 구동 체크 CheckProcessRunningByTitle
2 PID 기반 프로세스 구동 체크 CheckProcessRunningByPID
3 타이틀 기반 특정 프로세스 창 이동 SetWindowPosition
4 타이틀 기반 특정 프로세스 창 최상단 배치 BringWindowToTop
5 PID 기반 특정 프로세스 창 이동 SetProcessWindowPosition
6 프로세스 IME 모드 변경 WinInfo.SetImeMode

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
2 PC와 연결된 모니터 리스트 획득 실패

SetWindowPosition,

SetProcessWindowPosition

 -
3 요청 모니터 정보 획득 실패

SetWindowPosition,

SetProcessWindowPosition

 -
4 모니터 해상도 획득 실패

SetWindowPosition,

SetProcessWindowPosition

 -
5 지원하지 않는 창 크기 설정 옵션

SetWindowPosition,

SetProcessWindowPosition

 -
6 대상 타이틀을 가진 프로세스가 없음

SetWindowPosition,

BringWindowToTop,

SetProcessWindowPosition,

SetImeMode

 -
16 지원되지 않는 프로세스

SetImeMode, GetImeMode

 -
17 IME 접근 권한이 없는 프로세스

SetImeMode, GetImeMode

 -
18 IME 핸들 획득 실패

SetImeMode, GetImeMode

 -
19 IME 변경 실패

SetImeMode, GetImeMode

 -

1. 타이틀 기반 프로세스 구동 체크

API명

정의

호출예시

{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"Random Request Key",
  "param":{ 
    "processTitle":"TOMATO SYSTEM"
  }
}

응답예시

{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"976a-75cf-5b52",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isRunning":true
  }
}

2. PID 기반 프로세스 구동 체크

API명

정의

호출예시

{
  "service": "WinInfo.CheckProcessRunningByPID",
  "requestKey": "Random Request Key",
  "param": { 
    "processId": "28700"
  }
}

응답예시

{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"976a-75cf-5b52",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isRunning":true
  }
}

3. 타이틀 기반 특정 프로세스 창 이동

API명

정의

모니터와 관련된 정보는 "모니터 관련 서비스" 문서를 참고하시길 바랍니다.

설명

K-018.png

<Windows 모니터 및 프로세스 창 해상도 식별 방식>

호출예시

{
  "service": "WinInfo.SetWindowPosition",
  "requestKey": "Random Request Key",
  "param": { 
    "processTitle": "TOMATOSYSTEM",
    "screenIndex": 1,
    "screenSizeMode": 1,
    "left": 0,
    "top": 0,
    "width": 900,
    "height": 800
  }
}

응답예시

{
  "service":"WinInfo.SetWindowPosition",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

4. 타이틀 기반 특정 프로세스 창 최상단 배치

API명

정의

호출예시

{
  "service": "WinInfo.BringWindowToTop",
  "requestKey": "Random Request Key",
  "param": { 
    "processTitle": "TOMATOSYSTEM"
  }
}

응답예시

{
  "service":"WinInfo.BringWindowToTop",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

5. PID 기반 특정 프로세스 창 이동

API명

정의

모니터와 관련된 정보는 "모니터 관련 서비스" 문서를 참고하시길 바랍니다.

설명

K-018.png

<Windows 모니터 및 프로세스 창 해상도 식별 방식>

호출예시

{
  "service": "WinInfo.SetProcessWindowPosition",
  "requestKey": "Random Request Key",
  "param": { 
    "processId": "28700",
    "screenIndex": 1,
    "screenSizeMode": 1,
    "left": 0,
    "top": 0,
    "width": 900,
    "height": 800
  }
}

응답예시

{
  "service":"WinInfo.SetProcessWindowPosition",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

6. 프로세스 IME 모드 변경

API명

정의

호출예시

{
  "service": "WinInfo.SetImeMode",
  "requestKey": "Random Request Key",
  "param": { 
    "toNative": true
  }
}

응답예시

{
  "service":"WinInfo.SetImeMode",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

7. 프로세스 IME 모드 획득

API명

정의

호출예시

{
  "service": "WinInfo.GetImeMode",
  "requestKey": "Random Request Key",
  "param": {}
}

응답예시

{
  "service":"WinInfo.GetImeMode",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isNative":true
  }
}

eXDevice+ 공통

스크린샷 관련 서비스

 특정 모니터 또는 특정 프로세스 창의 스크린샷을 획득 또는 저장하기 위한 기능들을 제공합니다.

 본 서비스에서 eXDevice+가 인식하는 프로세스의 창 영역은 다음과 같습니다.

image.png

<eXDevice+가 인식하는 프로세스 창 영역>

 또한 웹 브라우저의 경우 Windows 정책 상 현재 포커스 된 창의 포커스 된 탭의 타이틀만 식별할 수 있습니다. 즉, 특정 브라우저에 포커스가 가 있지 않은 경우 해당 브라우저의 마지막으로 오픈한 창의 오픈된 탭의 타이틀을 검색할 수 있습니다.

image.png

<eXDevice+ 브라우저 타이틀 인식 예시>

서비스 리스트

 스크린샷 관련 서비스 리스트는 다음과 같습니다.

No. 서비스명 API명 비고
1 모니터 스크린샷 획득 WinInfo.GetScreenShot  
2 모니터 스크린샷 저장 WinInfo.SaveScreenShot  
3 타이틀 기반 프로세스 창 스크린샷 획득 WinInfo.GetWindowScreenShot  
4 타이틀 기반 프로세스 창 스크린샷 저장 WinInfo.SaveWindowScreenShot  

서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
2 PC와 연결된 모니터 리스트 획득 실패

GetScreenShot,

SaveScreenShot

  
3 요청 모니터 정보 획득 실패

GetScreenShot,

SaveScreenShot

  
6 대상 타이틀을 가진 프로세스가 없음

GetWindowScreenShot,

SaveWindowScreenShot,

GetProcessScreenShot,

SaveProcessScreenShot

  
10 창 최소화 모드에서 스크린샷 획득 불가

GetWindowScreenShot,

SaveWindowScreenShot,

GetProcessScreenShot,

SaveProcessScreenShot
11 스크린샷 획득 실패

GetWindowScreenShot,

SaveWindowScreenShot,

GetProcessScreenShot,

SaveProcessScreenShot
12 파일 저장 실패

SaveScreenShot,

SaveWindowScreenShot,

SaveProcessScreenShot

  

1. 모니터 스크린샷 획득

API명

정의

모니터와 관련된 정보는 "모니터 관련 서비스" 문서를 참고하시길 바랍니다.

호출예시

{
  "service":"WinInfo.GetScreenShot",
  "requestKey":"Random Request Key",
  "param":{ 
    "screenIndex": 4
  }
}

응답예시

{
  "service":"WinInfo.GetScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenShotBase64":"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAMCAgMCAgMDAwMEA..."
  }
}

2. 모니터 스크린샷 저장

API명

정의

모니터와 관련된 정보는 "모니터 관련 서비스" 문서를 참고하시길 바랍니다.

호출예시

{
  "service": "WinInfo.SaveScreenShot",
  "requestKey": "Random Request Key",
  "param": { 
    "screenIndex": 4,
    "filePath": "D:\\test.jpg"
  }
}

응답예시

{
  "service":"WinInfo.SaveScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

3. 타이틀 기반 프로세스 창 스크린샷 획득

API명

정의

프로세스의 창이 최소화 모드인 경우 해당 창의 스크린샷을 획득할 수 없습니다.

호출예시

{
  "service":"WinInfo.GetWindowScreenShot",
  "requestKey":"Random Request Key",
  "param": {
    "processTitle":"TOMATOSYSTEM"
  }
}

응답예시

{
  "service":"WinInfo.GetWindowScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenShotBase64":"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAA..."
  }
}

4. 타이틀 기반 프로세스 창 스크린샷 저장

API명

정의

프로세스의 창이 최소화 모드인 경우 해당 창의 스크린샷을 획득할 수 없습니다.

호출예시

{
  "service":"WinInfo.SaveWindowScreenShot",
  "requestKey":"Random Request Key...",
  "param":{
    "processTitle":"TOMATOSYSTEM",
    "filePath":"C:\\test.jpg"
  }
}

응답예시

{
  "service":"WinInfo.SaveWindowScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

5. PID 기반 프로세스 창 스크린샷 획득

API명

정의

프로세스의 창이 최소화 모드인 경우 해당 창의 스크린샷을 획득할 수 없습니다.

호출예시

{
  "service":"WinInfo.GetProcessScreenShot",
  "requestKey":"Random Request Key",
  "param":{
    "processId":1234
  }
}

응답예시

{
  "service":"WinInfo.GetProcessScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "screenShotBase64":"/9j/4AAQSkZJRgABAQEAYABgAAD/2w..."
  }
}

6. PID 기반 프로세스 창 스크린샷 저장

API명

정의

호출예시

{
  "service":"WinInfo.SaveProcessScreenShot",
  "requestKey":"Random Request Key",
  "param":{
    "processId":1234,
    "filePath":"C:\\test.jpg"
  }
}

응답예시

{
  "service":"WinInfo.SaveProcessScreenShot",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
eXDevice+ 공통

파일 관련 서비스

 로컬 파일을 Create, Read, Write, Copy, Delete 등 로컬 파일을 제어하는 기능들을 제공합니다.

서비스 리스트

No. 서비스명 API명 비고
1 파일 open WinInfo.OpenFile  
2 파일 read WinInfo.ReadFile  
3 파일 write WinInfo.WriteFile  
4 파일 delete WinInfo.DeleteFile
5 파일 copy WinInfo.CopyFile
6 파일 실행 WinInfo.RunFile 시스템 환경변수 호환되는 API
7 디렉토리 open WinInfo.OpenDirectory
8 파일 open dialog WinInfo.FileOpenDialog
9 파일 read dialog WinInfo.FileReadDialog
10 파일 write dialog WinInfo.FileWriteDialog
11 파일 리스트 획득 WinInfo.GetFileList
12 바로가기 생성 WinInfo.CreateShortcut

서비스 상태 코드 리스트

본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
9 해당 경로에 파일/디렉토리가 존재하지 않음 OpenFile, ReadFile, DeleteFile, CopyFile, OpenDirectory, GetFileList -
14 해당 경로에 동일한 파일이 존재 WriteFile, CopyFile, WinInfo.CreateShortcut fileWriteMode가 0인 경우
15 사용자에 의한 취소

FileOpenDialog, FileReadDialog,

FileWriteDialog

 dialog 닫기/취소 클릭한 경우
98 유효하지 않은 파라미터

공통

 -

1. 파일 open

API명

정의

본 API는 "Calc.exe", "msedge.exe"와 같은 환경변수는 호환되지 않으며, 오로지 절대 경로의 파일을 오픈할 때 사용합니다. 환경변수로 파일을 오픈하려면 "11. 파일 open(환경변수 호환)"을 확인해주세요.

호출예시

{
  "service": "WinInfo.OpenFile",
  "requestKey": "Random Request Key",
  "param": { 
    "filePath": "D:\\test.exe",
    "args": "-q"
  }
}

응답예시

{
  "service":"WinInfo.OpenFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

2. 파일 read

API명

정의

호출예시

{
  "service":"WinInfo.ReadFile",
  "requestKey":"Random Request Key",
  "param": { 
    "filePath": "D:\\test.txt",
    "fileEncodingType":"UTF-8",
    "timeFormat": 0
  }
}

응답예시

{
  "service":"WinInfo.ReadFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "data":"읽어들인 파일 내용",
    "startTime":"1765346851091",
    "endTime":"1765346851091"
  }
}

3. 파일 write

API명

정의

호출예시

{
  "service":"WinInfo.WriteFile",
  "requestKey":"Random Request Key",
  "param":{
    "filePath": "D:\\test.csv",
    "fileWriteMode": 0
    "data": "사번,이름,부서,직책,이메일,입사일,재직상태...",
    "timeFormat": 0
  }
}

응답예시

{
  "service":"WinInfo.WriteFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "startTime":"1765350096544",
    "endTime":"1765350096547"
  }
}

4. 파일 delete

API명

정의

호출예시

{
  "service": "WinInfo.DeleteFIle",
  "requestKey": "Random Request Key",
  "param": { 
    "filePath":"D:\\test.csv"
  }
}

응답예시

{
  "service":"WinInfo.DeleteFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

5. 파일 copy

API명

정의

호출예시

{
  "service": "WinInfo.CopyFile",
  "requestKey": "Random Request Key...",
  "param": { 
    "srcFilePath": "D:\\test.txt",
    "destFilePath": "D:\\test-copy.txt",
    "fileCopyMode": 0
  }
}

응답예시

{
  "service":"WinInfo.CopyFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

6. 파일 실행

API명

정의

본 API 호출시 디렉토리 경로를 입력하게 되면, Windows 특성상 파일탐색기로 해당 경로를 오픈하게 되나, 안정성의 이유로 디렉토리 오픈시 "7. 디렉토리 open"을 사용하길 권장합니다.

호출예시

{
  "service":"WinInfo.GetFileList",
  "requestKey":"Random Request Key",
  "param":{
    "filePath":"msedge.exe",
    "args": "--app=https://www.tomatosystem.co.kr"
  }
}

응답예시

{
  "service":"WinInfo.RunFile",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

7. 디렉토리 open

API명

정의

호출예시

{
  "service":"WinInfo.OpenDirectory",
  "requestKey":"Random Request Key",
  "param":{
    "dirPath":"D:\\test\\target"
  }
}

응답예시

{
  "service":"WinInfo.OpenDirectory",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

8. 파일 open dialog

API명

정의

호출예시

{
  "service":"WinInfo.FileOpenDialog",
  "requestKey":"Random Request Key",
  "param":{
    "initDirPath":"D:\\",
    "dialogTitle":"오픈할 파일을 선택하세요",
    "filter":"텍스트|*.txt|JSON|*.json|CSV|*.csv|모든파일|*.*",
    "initFileName":"test.csv",
    "args":""
  }
}

응답예시

{
  "service":"WinInfo.FileOpenDialog",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "selectedFilePath":"D:\\test.csv"
  }
}

9. 파일 read dialog

API명

정의

호출예시

{
  "service":"WinInfo.FileReadDialog",
  "requestKey":"Random Request Key",
  "param":{
    "initDirPath": "C:\\",
    "dialogTitle": "Read할 파일 선택",
    "filter": "텍스트|*.txt|JSON|*.json|CSV|*.csv|모든파일|*.*",
    "timeFormat": 0
  }
}

응답예시

{
  "service":"WinInfo.FileReadDialog",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "selectedFilePath":"D:\\write-test.csv",
    "data":"읽어 들인 파일 내용",
    "startTime":"1765523201801",
    "endTime":"1765523201801"
  }
}

10. 파일 write dialog

API명

정의

호출예시

{
  "service":"WinInfo.FileWriteDialog",
  "requestKey":"Random Request Key",
  "param":{
    "initDirPath":"D:\\",
    "dialogTitle":"파일 저장",
    "filter":"텍스트|*.txt|모든파일|*.*",
    "initFileName":"test.txt",
    "data":"파일에 Write할 데이터",
    "timeFormat":0
  }
}

응답예시

{
  "service":"WinInfo.FileWriteDialog",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "selectedFilePath":"C:\\test.csv",
    "startTime":"1765524493661",
    "endTime":"1765524493662"
  }
}

11. 파일 리스트 획득

API명

정의

호출예시

{
  "service":"WinInfo.GetFileList",
  "requestKey":"Random Request Key",
  "param":{
    "dirpath":"D:\\"
  }
}

응답예시

{
  "service":"WinInfo.GetFileList",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "fileNames":["test-copy.txt","test.txt","write-test.csv"]
  }
}

12. 바로가기 생성

API명

정의

호출예시

{
  "service":"WinInfo.CreateShortcut",
  "requestKey":"Random Request Key",
  "param":{
    "targetPath":"msedge.exe",
    "arguments":"--app=https://www.tomatosystem.co.kr",
    "shortcutPath":"%USERPROFILE%\\Desktop\\TomatoSystemApp.lnk",
    "fileWriteMode":1,
    "iconPath":"D:\test.ico"
  }
}

응답예시

{
  "service":"WinInfo.CreateShortcut",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
eXDevice+ 공통

프린터 관련 서비스

프린터 관련 서비스

로컬 프린터를 조회하거나, 프린터를 조작하는 기능들을 제공합니다.

서비스 리스트

No. 서비스명 API명 비고
1 기본 프린터 조회
WinInfo.GetDefaultPrinter
  
2 전체 프린터 조회
WinInfo.GetPrinterList
  
3 기본 프린터 설정
WinInfo.SetDefaultPrinter
  
4 기본 설정 조회
WinInfo.GetPrinterDefaultSettings
 default tray, default paper
5 지원 트레이 리스트 조회
WinInfo.GetPrinterTrays
6 지원 용지 리스트 조회
WinInfo.GetPrinterPapers
7 상세 정보 조회
WinInfo.GetPrinterDetails
 default settings, tray list, paper list

서비스 상태 코드 리스트

본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

이 상태 코드는 응답 JSON 메시지 중 return 또는 returnValue의 값에 해당합니다.

리턴코드 리턴 코드 내용 대상 서비스 비고
-1 정의되지 않은 예외 공통 Log 파일에서 내용 확인 필요
0 정상 공통 -
20 기본 프린터 변경 실패 SetDefaultPrinter 대상 프린터 없음 등
98 유효하지 않은 파라미터

공통

 -

기본프린터 조회 방법

Windows는 "프린터 및 스캐너"에서 설정된 기본 프린터를 확인할 수 있으며, 기본 프린터를 확인하기 위해서는 반드시 "Windows에서 내 기본 프린터를 관리 할 수 있도록 허용" 옵션을 꺼야한다.

Win11-옵션.png

Win11-기본프린터.png

1. 기본 프린터 조회

API명

정의

호출예시

{
  "service": "WinInfo.GetDefaultPrinter",
  "requestKey": "Random Request Key",
  "param": {}
}

응답예시

{
  "service":"WinInfo.GetDefaultPrinter",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "name":"FAX"
  }
}

2. 전체 프린터 조회

API명

정의

호출예시

{
  "service": "WinInfo.GetPrinterList",
  "requestKey": "Random Request Key",
  "param": {}
}

응답예시

{
  "service":"WinInfo.GetPrinterList",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "list":[
      {"name":"OneNote for Windows 10","isDefault":false},
      {"name":"Send To OneNote 2016","isDefault":false},
      {"name":"Microsoft XPS Document Writer","isDefault":false},
      {"name":"Microsoft Print to PDF","isDefault":false},
      {"name":"Fax","isDefault":true}
    ]
  }
}

3. 기본 프린터 설정

API명

정의

호출예시

{
  "service":"WinInfo.SetDefaultPrinter",
  "requestKey":"Random Request Key",
  "param":{
    "name":"OneNote for Windows 10"
  }
}

응답예시

{
  "service":"WinInfo.SetDefaultPrinter",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}

4. 기본 설정 조회

API명

정의

호출예시

{
  "service":"WinInfo.GetPrinterDefaultSettings",
  "requestKey":"Random Request Key",
  "param":{
    "name": "FUJIFILM Apeos C2560"
  }
}

프린터의 이름은 "전체 프린터 조회" 기능을 통해 확인할 수 있습니다.

응답예시

{
  "service":"WinInfo.GetPrinterDefaultSettings",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "defSettings":{
      "paper":{"width":2100,"height":2970,"kind":9},
      "tray":{"kind":15}
    }
  }
}

본 서비스는 용지의 이름과 트레이의 이름을 리턴하지 않고 식별ID(Kind)를 리턴합니다. 용지와 트레이 ID로 각각의 이름을 획득하려면 WinInfo.GetPrinterPapers 및 WinInfo.GetPrinterTrays를 사용하길 바랍니다.

5. 지원 트레이 리스트 조회

API명

정의

호출예시

{
  "service":"WinInfo.GetPrinterTrays",
  "requestKey":"Random Request Key",
  "param":{
    "name": "FUJIFILM Apeos C2560"
  }
}

프린터의 이름은 "전체 프린터 조회" 기능을 통해 확인할 수 있습니다.

응답예시

{
  "service":"WinInfo.GetPrinterTrays",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "trays":[
      {"name":"자동","kind":15},
      {"name":"자동선택","kind":7},
      {"name":"트레이 1","kind":1},
      {"name":"트레이 5(수동)","kind":4}
    ]
  }
}

6. 지원 용지 리스트 조회

API명

정의

호출예시

{
  "service":"WinInfo.GetPrinterPapers",
  "requestKey":"Random Request Key",
  "param":{
    "name": "FUJIFILM Apeos C2560"
  }
}

프린터의 이름은 "전체 프린터 조회" 기능을 통해 확인할 수 있습니다.

응답예시

{
  "service":"WinInfo.GetPrinterPapers",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "papers":[
      {"name":"A1(594x841mm)","width":594,"height":841,"kind":0},
      {"name":"A2(420x594mm)","width":420,"height":594,"kind":66},
      {"name":"A3(297x420mm)","width":297,"height":420,"kind":8},
      {"name":"B4(257x364mm)","width":257,"height":364,"kind":12},
      {"name":"A4(210x297mm)","width":210,"height":297,"kind":9}
    ]
  }
}

7. 상세 정보 조회

API명

정의

호출예시

{
  "service":"WinInfo.GetPrinterDetails",
  "requestKey":"Random Request Key",
  "param":{
    "name": "FUJIFILM Apeos C2560"
  }
}

프린터의 이름은 "전체 프린터 조회" 기능을 통해 확인할 수 있습니다.

응답예시

{
  "service":"WinInfo.GetPrinterDetails",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "details":{
      "name":"FUJIFILM Apeos C2560(5층)",
      "isDefault":true,
      "defSettings":{
        "paper":{"name":"A4(210x297mm)","width":210,"height":297,"kind":9},
        "tray":{"name":"자동","kind":15}},
      "trays":[
        {"name":"자동","kind":15},
        {"name":"자동선택","kind":7},
        {"name":"트레이 1","kind":1},
        {"name":"트레이 5(수동)","kind":4}
      ],
      "papers":[
        {"name":"A1(594x841mm)","width":594,"height":841,"kind":0},
        {"name":"A2(420x594mm)","width":420,"height":594,"kind":66},
        {"name":"A3(297x420mm)","width":297,"height":420,"kind":8},
        {"name":"B4(257x364mm)","width":257,"height":364,"kind":12},
        {"name":"A4(210x297mm)","width":210,"height":297,"kind":9}
      ]
    }
  }
}

한화생명

한화생명 API 가이드 문서

한화생명

제공 서비스 리스트

한화생명 전용 API는 다음과 같은 서비스를 제공합니다.

서비스 그룹 서비스명 API명 (service) 대상 모듈 비고
핀패드 상태/설정 조회 핀패드 초기화 TSP90.Init TSP90Wrapper.dll(1.0.3.3 이상) 포트 오픈 및 하드웨어 초기화
버전 정보 조회 TSP90.GetVersion TSP90Wrapper.dll(1.0.3.3 이상) 펌웨어/DLL 버전 획득
스피커 볼륨 조회 TSP90.GetVolume TSP90Wrapper.dll(1.0.3.3 이상) 1~10
버튼 볼륨 조회 TSP90.GetButtonVolume TSP90Wrapper.dll(1.0.3.3 이상) 1~10
밝기 조회 TSP90.GetBright TSP90Wrapper.dll(1.0.3.3 이상) 1~10
폰트 조회 TSP90.GetFont TSP90Wrapper.dll(1.0.3.3 이상) 설정된 폰트명 반환
핀패드 하드웨어 설정 스피커 볼륨 설정 TSP90.SetVolume TSP90Wrapper.dll(1.0.3.3 이상) 1~10
버튼 볼륨 설정 TSP90.SetButtonVolume TSP90Wrapper.dll(1.0.3.3 이상) 1~10
밝기 설정 TSP90.SetBright TSP90Wrapper.dll(1.0.3.3 이상) 1~10
폰트 설정 TSP90.SetFont TSP90Wrapper.dll(1.0.3.3 이상) 굴림체 / 엽서체
대기화면 설정 TSP90.SetWindow TSP90Wrapper.dll(1.0.3.3 이상) 대기 이미지/비디오 인덱스 지정
핀패드 보안 입력 비밀번호 입력 TSP90.Read TSP90Wrapper.dll(1.0.3.3 이상) 비밀번호(최대 4자리) 입력
주민등록번호 입력 TSP90.SSNRead TSP90Wrapper.dll(1.0.3.3 이상) 주민번호(최대 13자리) 입력
다이얼로그 입력 TSP90.ReadProcess TSP90Wrapper.dll(1.0.3.3 이상) 화면 다이얼로그 문구 노출 모드
비다이얼로그 입력 TSP90.ReadNDProcess TSP90Wrapper.dll(1.0.3.3 이상) 다이얼로그 없는 입력 모드
자동 확인/종료 TSP90.PINAutoConfirmed TSP90Wrapper.dll(1.0.3.3 이상) 최소 입력 충족 시 즉시 반환
입력 프로세스 강제종료 TSP90.Off TSP90Wrapper.dll(1.0.3.3 이상) 진행 중인 입력 즉시 취소
핀패드 디스플레이 출력 미디어 출력 TSP90.MediaOut TSP90Wrapper.dll(1.0.3.3 이상) 이미지/텍스트/음성 동합 출력
핀패드 폼(그리드) 출력 TSP90.PinpadFormOut TSP90Wrapper.dll(1.0.3.3 이상) 테이블 형태 Grid 데이터 출력
한화생명 MCI 통신 MCI 서버 TCP 연결 mcipush.Connect tcpsvc.dll (1.0.3.2 이상) TCP 연결 및 serviceId 발급
종료 메시지 등록 mcipush.SaveDisposeMessage tcpsvc.dll (1.0.3.2 이상) 세션 해제 시 자동 송신 메시지
MCI 서버 연결 해제 mcipush.Disconnect tcpsvc.dll (1.0.3.2 이상) TCP 소켓 세션 Close
메시지 전송 mcipush.SendMessage tcpsvc.dll (1.0.3.2 이상) 서버로 전문 송신
MCI Push 메시지 수신 mcipush.Listener tcpsvc.dll (1.0.3.2 이상) 서버 Push 비동기 리스너
한화생명

TSP90 핀패드 제어 서비스

SP90 핀패드 단말기를 제어하기 위한 API 그룹입니다.

서비스 리스트

No. 서비스명 API명 비고
1 핀패드 초기화 TSP90.Init 포트 오픈 및 하드웨어 초기화
2 버전 정보 조회 TSP90.GetVersion 펌웨어/DLL 버전 획득
3 스피커 볼륨 조회 TSP90.GetVolume 1~10
4 버튼 볼륨 조회 TSP90.GetButtonVolume 1~10
5 밝기 조회 TSP90.GetBright 1~10
6 폰트 조회 TSP90.GetFont 설정된 폰트명 반환
7 스피커 볼륨 설정 TSP90.SetVolume 1~10
8 버튼 볼륨 설정 TSP90.SetButtonVolume 1~10
9 밝기 설정 TSP90.SetBright 1~10
10 폰트 설정 TSP90.SetFont 굴림체 / 엽서체
11 대기화면 설정 TSP90.SetWindow 대기 이미지/비디오 인덱스 지정
12 비밀번호 입력 TSP90.Read 비밀번호(최대 4자리) 입력
13 주민등록번호 입력 TSP90.SSNRead 주민번호(최대 13자리) 입력
14 다이얼로그 입력 TSP90.ReadProcess 화면 다이얼로그 문구 노출 모드
15 비다이얼로그 입력 TSP90.ReadNDProcess 다이얼로그 없는 입력 모드
16 자동 확인 TSP90.PINAutoConfirmed 최소 입력 충족 시 즉시 반환
17 입력 프로세스 강제종료 TSP90.Off 진행 중인 입력 즉시 취소
18 미디어 출력 TSP90.MediaOut 이미지/텍스트/음성 통합 출력
19 핀패드 폼(그리드) 출력 TSP90.PinpadFormOut 테이블 형태 Grid 데이터 출력

서비스 상태 코드 리스트

본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트입니다. 응답 JSON 메시지 중 return 또는 return.returnValue 값에 해당합니다.

리턴코드 내용 상세 설명
0 성공 정상적으로 서비스를 호출했습니다.
-1 정의되지 않은 예외 로그 파일 확인이 필요합니다.
1 Fail(0) 리턴 핀패드 제어 DLL Method 호출 결과 Fail(0)이 리턴되었습니다.
2 PINOn Fail PINOn() 호출 결과 Fail(0)이 리턴되었습니다.
3 PINStart Fail PINStart() 호출 결과 Fail(0)이 리턴되었습니다.
4 PINRead Fail PINRead() 호출 결과 Fail(0)이 리턴되었습니다.
5 PINStartSSN Fail PINStartSSN() 호출 결과 Fail(0)이 리턴되었습니다.
6 이미지 파일 부재 SetDefaultWindow()에서 핀패드에 지정된 인덱스의 이미지 파일이 존재하지 않음(-1)이 리턴되었습니다.
7 하드웨어 에러 SetDefaultWindow()에서 하드웨어 에러(0)가 리턴되었습니다.
8 지원 범위 초과 파라미터 지원 범위를 벗어난 파라미터가 입력되었습니다.
9 유효하지 않은 파라미터 유효하지 않은 파라미터가 입력되었습니다.
10 사용자 취소 ReadProcess() 진행 중 사용자가 취소 버튼을 클릭했습니다.
11 유효하지 않은 데이터 핀패드에서 전달받은 데이터가 유효하지 않은 데이터입니다.
12 데이터 변환 실패 핀패드에서 전달받은 데이터를 변환하지 못했습니다.
13 폰트 데이터 변환 실패 파라미터로 전달받은 폰트 데이터 변환에 실패했습니다.
14 다이얼로그 데이터 변환 실패 파라미터로 전달받은 다이얼로그 메시지 데이터 변환에 실패했습니다.
15 이미지 리스트 변환 실패 파라미터로 전달받은 이미지 리스트 Array의 데이터 변환에 실패했습니다.
16 데이터 추출 실패 핀패드에서 전달받은 비밀번호/주민번호 데이터 추출에 실패했습니다.
17 작업 중복 이미 다른 입력 작업이 수행 중입니다.
18 취소/타임아웃 발생 핀패드 Read 중 사용자에 의한 취소 또는 타임아웃에 의한 취소가 발생했습니다.
19 Off 불가 상태 Off로 종료할 수 없는 입력 프로세스가 진행 중입니다.
101~121 Invoke 에러 핀패드 DLL 내부 메서드 호출 중 예외가 발생했습니다. (101: PINInit, 102: GetPinpadVersion, 103: SetDefaultWindow, 104: GetVolume, 105: SetVolume, 106: GetBright, 107: SetBright, 108: GetFont, 109: SetFont, 110: PINOn, 111: PINStart, 112: PINRead, 113: PINOff, 114: PINStartSSN, 115: PINReadProcess, 116: PINReadProcessND, 117: PINAutoConfirmed, 118: MediaOut, 119: PinpadFormOut, 120: GetButtonVolume, 121: SetButtonVolume)

1. 핀패드 초기화

API명

정의

호출 예시

{
  "service": "TSP90.Init",
  "requestKey": "REQ_PIN_INIT_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.Init",
  "requestKey": "REQ_PIN_INIT_01",
  "statusCode": "0000",
  "return": 0
}

2. 버전 정보 조회

API명

정의

호출 예시

{
  "service": "TSP90.GetVersion",
  "requestKey": "REQ_PIN_VER_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.GetVersion",
  "requestKey": "REQ_PIN_VER_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "version": "2.0.3.4"
  }
}

3. 스피커 볼륨 조회

API명

정의

호출 예시

{
  "service": "TSP90.GetVolume",
  "requestKey": "REQ_PIN_VOL_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.GetVolume",
  "requestKey": "REQ_PIN_VOL_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "volume": "5"
  }
}

4. 버튼 볼륨 조회

API명

정의

호출 예시

{
  "service": "TSP90.GetButtonVolume",
  "requestKey": "REQ_PIN_BVOL_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.GetButtonVolume",
  "requestKey": "REQ_PIN_BVOL_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "volume": "5"
  }
}

5. 밝기 조회

API명

정의

호출 예시

{
  "service": "TSP90.GetBright",
  "requestKey": "REQ_PIN_BRT_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.GetBright",
  "requestKey": "REQ_PIN_BRT_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "bright": "8"
  }
}

6. 폰트 조회

API명

정의

호출 예시

{
  "service": "TSP90.GetFont",
  "requestKey": "REQ_PIN_FONT_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.GetFont",
  "requestKey": "REQ_PIN_FONT_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "font": "굴림체"
  }
}

7. 스피커 볼륨 설정

API명

정의

호출 예시

{
  "service": "TSP90.SetVolume",
  "requestKey": "REQ_PIN_SETVOL_01",
  "param": {
    "volume": "7"
  }
}

응답 예시

{
  "service": "TSP90.SetVolume",
  "requestKey": "REQ_PIN_SETVOL_01",
  "statusCode": "0000",
  "return": 0
}

8. 버튼 볼륨 설정

API명

정의

호출 예시

{
  "service": "TSP90.SetButtonVolume",
  "requestKey": "REQ_PIN_SETBVOL_01",
  "param": {
    "volume": "7"
  }
}

응답 예시

{
  "service": "TSP90.SetButtonVolume",
  "requestKey": "REQ_PIN_SETBVOL_01",
  "statusCode": "0000",
  "return": 0
}

9. 밝기 설정

API명

정의

호출 예시

{
  "service": "TSP90.SetBright",
  "requestKey": "REQ_PIN_SETBRT_01",
  "param": {
    "bright": "8"
  }
}

응답 예시

{
  "service": "TSP90.SetBright",
  "requestKey": "REQ_PIN_SETBRT_01",
  "statusCode": "0000",
  "return": 0
}

10. 폰트 설정

API명

정의

호출 예시

{
  "service": "TSP90.SetFont",
  "requestKey": "REQ_PIN_SETFONT_01",
  "param": {
    "font": "굴림체"
  }
}

응답 예시

{
  "service": "TSP90.SetFont",
  "requestKey": "REQ_PIN_SETFONT_01",
  "statusCode": "0000",
  "return": 0
}

11. 대기화면 설정

API명

정의

호출 예시

{
  "service": "TSP90.SetWindow",
  "requestKey": "REQ_PIN_SETWIN_01",
  "param": {
    "type": "1",
    "size": "0",
    "imageIndex": "[21,22,23]",
    "interval": "3"
  }
}

응답 예시

{
  "service": "TSP90.SetWindow",
  "requestKey": "REQ_PIN_SETWIN_01",
  "statusCode": "0000",
  "return": 0
}

12. 비밀번호 입력

API명

정의

호출 예시

{
  "service": "TSP90.Read",
  "requestKey": "REQ_PIN_READ_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4"
  }
}

응답 예시

{
  "service": "TSP90.Read",
  "requestKey": "REQ_PIN_READ_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "password": "E2F5B6A8C9D01234..."
  }
}

13. 주민등록번호 입력

API명

정의

호출 예시

{
  "service": "TSP90.SSNRead",
  "requestKey": "REQ_PIN_SSN_01",
  "param": {
    "sound": "1",
    "min": "13",
    "max": "13"
  }
}

응답 예시

{
  "service": "TSP90.SSNRead",
  "requestKey": "REQ_PIN_SSN_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "idNumber": "8A9B0C1D2E3F4567..."
  }
}

14. 다이얼로그 동반 입력

API명

정의

호출 예시

{
  "service": "TSP90.ReadProcess",
  "requestKey": "REQ_PIN_PROC_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4",
    "dialogMessage": "핀패드에 비밀번호 4자리를 입력해주세요."
  }
}

응답 예시

{
  "service": "TSP90.ReadProcess",
  "requestKey": "REQ_PIN_PROC_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "data": "A1B2C3D4E5F6..."
  }
}

15. 비다이얼로그 입력

API명

정의

호출 예시

{
  "service": "TSP90.ReadNDProcess",
  "requestKey": "REQ_PIN_ND_01",
  "param": {
    "sound": "1",
    "min": "4",
    "max": "4"
  }
}

응답 예시

{
  "service": "TSP90.ReadNDProcess",
  "requestKey": "REQ_PIN_ND_01",
  "statusCode": "0000",
  "return": {
    "returnValue": 0,
    "data": "9876543210AB..."
  }
}

16. 자동 확인

API명

정의

호출 예시

{
  "service": "TSP90.PINAutoConfirmed",
  "requestKey": "REQ_PIN_AUTOCONF_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.PINAutoConfirmed",
  "requestKey": "REQ_PIN_AUTOCONF_01",
  "statusCode": "0000",
  "return": 0
}

17. 입력 프로세스 강제종료

API명

정의

호출 예시

{
  "service": "TSP90.Off",
  "requestKey": "REQ_PIN_OFF_01",
  "param": {}
}

응답 예시

{
  "service": "TSP90.Off",
  "requestKey": "REQ_PIN_OFF_01",
  "statusCode": "0000",
  "return": 0
}

18. 미디어 복합 출력

API명

정의

호출 예시

{
  "service": "TSP90.MediaOut",
  "requestKey": "REQ_PIN_MEDIA_01",
  "param": {
    "audio": "0",
    "video": "0",
    "image": "0",
    "text": "1",
    "startLine": "1",
    "textAlign": "3",
    "fontsize": "16",
    "textStr": "한화생명 고객 안내 메시지",
    "time": "5"
  }
}

응답 예시

{
  "service": "TSP90.MediaOut",
  "requestKey": "REQ_PIN_MEDIA_01",
  "statusCode": "0000",
  "return": 0
}

19. 핀패드 폼(그리드) 출력

API명

정의

주의사항

  1. 셀(Cell) 구분자는 |(파이프 기호), 행(Row) 구분자는 \n(줄바꿈)을 사용합니다.
  2. 예시 포맷: 항목1|항목2|항목3\n내용1|내용2|내용3\n
  3. 연속된 파이프 기호(||) 등으로 인해 열 개수가 초과될 경우 마지막 열 데이터가 핀패드 화면에서 누락될 수 있으므로 정확한 규격을 준수하시길 바랍니다.

호출 예시

{
  "service": "TSP90.PinpadFormOut",
  "requestKey": "REQ_PIN_FORM_01",
  "param": {
    "formType": "1",
    "textStr": "계약자|홍길동|납입금액|100,000원\n피보험자|김영희|보험상태|정상유지\n",
    "time": "60"
  }
}

응답 예시

{
  "service": "TSP90.PinpadFormOut",
  "requestKey": "REQ_PIN_FORM_01",
  "statusCode": "0000",
  "return": 0
}
한화생명

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
}