eXDevice+ 공통

eXDevice+ 기본 API

서비스 및 통신 프로토콜

 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+는 다음과 같은 서비스를 제공합니다.

기능 기준: 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+ 정보 획득 서비스

 현재 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"}
  }
}

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+간 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 메시지"
}

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+가 설치된 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}
    ]
  }
}

프로세스 제어 관련 서비스

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

서비스 리스트

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

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+가 인식하는 프로세스의 창 영역은 다음과 같습니다.

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
}

파일 관련 서비스

 로컬 파일을 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
}

프린터 관련 서비스

프린터 관련 서비스

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

서비스 리스트

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}
      ]
    }
  }
}