# 서비스 및 통신 프로토콜

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

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

### 1. 서비스 정의

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

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

[![image.png](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-11/scaled-1680-/78Timage.png)](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-11/78Timage.png)

**<eXDevice+ 서비스 호출 과정>**

### 2. eXDevice+ 요청 프로토콜

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

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

- service 
    - 호출하고자 하는 서비스 이름입니다.
    - 가이드 문서에 명시된 서비스 이름을 사용합니다.
- requestKey 
    - WebSocket Client에서 발급하는 랜덤한 키 값입니다.
    - WebSocket 통신 특성 상 비동기적으로 eXDevice+에게 메시지를 송수신 하므로, 응답 수신 시 어떤 요청에 대한 응답인지 식별하기 위한 값입니다.
    - requestKey는 서비스 호출에 대한 응답을 수신할 때 까지 WebSocket Client에서 관리 되어야 합니다.
- param 
    - 서비스를 호출하기 위해 요구되는 파라미터 정보입니다.
    - 가이드 문서에 명시된 각각의 서비스에서 요구하는 파라미터를 입력해야합니다.

### 3. eXDevice+ 응답 프로토콜

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

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

- service 
    - WebSocket Client가 호출한 서비스 명칭입니다.
    - requestKey와 조합해 어떤 호출에 대한 응답인지 식별할 수 있습니다.
- requestKey 
    - WebSocket Client가 서비스를 호출하기 위해 발급한 랜덤한 키 값입니다.
    - service와 조합해 어떤 호출에 대한 응답인지 식별할 수 있습니다.
- statusCode 
    - 서비스 호출에 대한 eXDevice+ 상태 코드입니다.
    - "0000"이 리턴 된 경우 정상적으로 서비스를 호출했음을 의미하며, 그 외의 값은 서비스 호출 전 일련의 이유로 서비스를 호출하지 못했음을 의미합니다.
- return 
    - 서비스를 호출한 결과 입니다.
    - int, string, double, Array, JSON 등 다양한 값이 리턴 될 수 있습니다.
    - 각 서비스에 대한 호출 결과는 가이드 문서에 명시된 서비스들을 참고하시길 바랍니다.

### 4. eXDevice+ 상태 코드

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

##### 4.1. 1000번대

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

- WebSocket Client 요청 메시지 검증
- WebSocket Client 요청 서비스 데이터 타입 변환 실패
- 잘못된 WebSocket Client 요청

<table border="1" id="bkmrk-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EB%B6%84%EB%A5%98-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EC%83%81%EC%84%B8-%EB%B9%84%EA%B3%A0-1" style="border-collapse: collapse; width: 100%; height: 297.969px;"><colgroup><col style="width: 8.46246%;"></col><col style="width: 25.0325%;"></col><col style="width: 41.4753%;"></col><col style="width: 25.0298%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">**상태코드**</td><td class="align-center" style="height: 29.7969px;">**분류**</td><td class="align-center" style="height: 29.7969px;">**상태코드 상세**</td><td class="align-center" style="height: 29.7969px;">**비고**</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1000</td><td style="height: 29.7969px;">정의되지 않은 통신 예외</td><td style="height: 29.7969px;">-</td><td style="height: 29.7969px;">Log 파일 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1001</td><td style="height: 29.7969px;">JSON 포맷이 아닌 요청</td><td style="height: 29.7969px;">요청 메시지가 JSON 포맷이 아님</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1002</td><td style="height: 29.7969px;">요청 프로토콜 불일치</td><td style="height: 29.7969px;">요청 프로토콜과 일치 하지 않는 JSON 포맷</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1003</td><td style="height: 29.7969px;">필수 정보 누락</td><td style="height: 29.7969px;">Service 호출에 필요한 필수 정보 누락</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1004</td><td style="height: 29.7969px;">지원하는 서비스 없음</td><td style="height: 29.7969px;">서비스 설정 파일(module.json)에 기재된 서비스 없음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1005</td><td style="height: 29.7969px;">지원하지 않는 서비스</td><td style="height: 29.7969px;">지원하지 않는 서비스 요청</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1006</td><td style="height: 29.7969px;">파라미터 불일치</td><td style="height: 29.7969px;">요청 메시지 파라미터가 서비스 호출 파라미터와 불일치</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1007</td><td style="height: 29.7969px;">파라미터 타입 변환 실패</td><td style="height: 29.7969px;">파라미터 데이터 타입 불일치</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">1008</td><td style="height: 29.7969px;">serviceId 누락</td><td style="height: 29.7969px;">요청 메시지에 serviceId 정보 누락</td><td style="height: 29.7969px;">-</td></tr></tbody></table>

##### 4.2. 2000번대

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

- 서비스 DLL/ActiveX 로드 실패
- 서비스 설정 파일 에러
- 서비스 객체 생성 실패

<table border="1" id="bkmrk-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EB%B6%84%EB%A5%98-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EC%83%81%EC%84%B8-%EB%B9%84%EA%B3%A0-2" style="border-collapse: collapse; width: 100%; height: 446.953px;"><colgroup><col style="width: 8.46246%;"></col><col style="width: 26.3409%;"></col><col style="width: 41.7145%;"></col><col style="width: 23.4822%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">**상태코드**</td><td class="align-center" style="height: 29.7969px;">**분류**</td><td class="align-center" style="height: 29.7969px;">**상태코드 상세**</td><td class="align-center" style="height: 29.7969px;">**비고**</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2000</td><td style="height: 29.7969px;">정의되지 않은 서비스 예외</td><td style="height: 29.7969px;">-</td><td style="height: 29.7969px;">Log 파일 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2001</td><td style="height: 29.7969px;">libType 정보 누락</td><td style="height: 29.7969px;">설정 파일에 정보 누락</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2002</td><td style="height: 29.7969px;">지원하지 않는 libType</td><td style="height: 29.7969px;">설정 파일에 유효하지 않은 정보 기재되어 있음</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2003</td><td style="height: 29.7969px;">libFile 정보 누락</td><td style="height: 29.7969px;">설정 파일에 정보 누락  
</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2004</td><td style="height: 29.7969px;">delegator 정보 누락</td><td style="height: 29.7969px;">설정 파일에 정보 누락  
</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2005</td><td style="height: 29.7969px;">지원하지 않는 delegator</td><td style="height: 29.7969px;">설정 파일에 유효하지 않은 정보 기재되어 있음</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2006</td><td style="height: 29.7969px;">destDir 정보 누락</td><td style="height: 29.7969px;">설정 파일에 정보 누락</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2007</td><td style="height: 29.7969px;">CLSID 정보 누락</td><td style="height: 29.7969px;">설정 파일에 정보 누락</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2008</td><td style="height: 29.7969px;">지원하지 않는 param 타입</td><td style="height: 29.7969px;">설정 파일에 유효하지 않은 정보 기재되어 있음</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2009</td><td style="height: 29.7969px;">지원하지 않는 return 타입</td><td style="height: 29.7969px;">설정 파일에 유효하지 않은 정보 기재되어 있음</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2010</td><td style="height: 29.7969px;">지원하지 않는 returnObject 타입</td><td style="height: 29.7969px;">설정 파일에 유효하지 않은 정보 기재되어 있음</td><td style="height: 29.7969px;">modules.json 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2011</td><td style="height: 29.7969px;">delegator 생성 실패</td><td style="height: 29.7969px;">객체 생성 실패</td><td style="height: 29.7969px;">Log 파일 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2012</td><td style="height: 29.7969px;">subForm 생성 실패</td><td style="height: 29.7969px;">객체 생성 실패</td><td style="height: 29.7969px;">Log 파일 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">2013</td><td style="height: 29.7969px;">libType 오용</td><td style="height: 29.7969px;">serviceId를 발급 받을 수 없는 서비스에 serviceId 사용</td><td style="height: 29.7969px;">modules.json 확인</td></tr></tbody></table>

##### 4.3. 3000번대

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

<table border="1" id="bkmrk-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EB%B6%84%EB%A5%98-%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C-%EC%83%81%EC%84%B8-%EB%B9%84%EA%B3%A0-3" style="border-collapse: collapse; width: 100%; height: 804.516px;"><colgroup><col style="width: 8.46246%;"></col><col style="width: 28.3671%;"></col><col style="width: 41.2377%;"></col><col style="width: 21.9327%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">**상태코드**</td><td class="align-center" style="height: 29.7969px;">**분류**</td><td class="align-center" style="height: 29.7969px;">**상태코드 상세**</td><td class="align-center" style="height: 29.7969px;">**비고**</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3000</td><td style="height: 29.7969px;">정의되지 않은 서비스 호출 예외</td><td style="height: 29.7969px;">-</td><td style="height: 29.7969px;">Log 파일 확인</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3001</td><td style="height: 29.7969px;">파일 누락</td><td style="height: 29.7969px;">대상 서비스 파일이 로컬에 존재하지 않음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3002</td><td style="height: 29.7969px;">레지스트리 등록 누락</td><td style="height: 29.7969px;">대상 서비스 파일이 레지스트리에 등록되지 않음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3003</td><td style="height: 29.7969px;">라이브러리 식별 실패</td><td style="height: 29.7969px;">native Dll/managed Dll 식별 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3004</td><td style="height: 29.7969px;">라이브러리 로드 실패</td><td style="height: 29.7969px;">라이브러리 메모리 로드 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3005</td><td style="height: 29.7969px;">지원하지 않는 라이브러리</td><td style="height: 29.7969px;">eXDevice+에서 지원하지 않는 라이브러리 확장자 로드</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3006</td><td style="height: 29.7969px;">export된 class 없음</td><td style="height: 29.7969px;">라이브러리에서 export된 class 없음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3007</td><td style="height: 29.7969px;">대상 class 찾을 수 없음</td><td style="height: 29.7969px;">라이브러리에서 대상 class 찾을 수 없음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3008</td><td style="height: 29.7969px;">export된 method 없음</td><td style="height: 29.7969px;">class에서 export 된 method 없음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3009</td><td style="height: 29.7969px;">대상 method 찾을 수 없음</td><td style="height: 29.7969px;">class에서 대상 method 찾을 수 없음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3010</td><td style="height: 29.7969px;">참조 타입 변환 실패</td><td style="height: 29.7969px;">ref 데이터 타입 변환 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3011</td><td style="height: 29.7969px;">Method IL 생성 실패</td><td style="height: 29.7969px;">Method IL 생성 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3012</td><td style="height: 29.7969px;">ActiveX 컨트롤 생성 실패</td><td style="height: 29.7969px;">요청한 서비스를 제공할 ActiveX 컨트롤 생성 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3013</td><td style="height: 29.7969px;">ActiveX 컨트롤 생성되지 않음</td><td style="height: 29.7969px;">요청한 서비스를 제공하는 ActiveX 컨트롤 생성되지 않음</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3014</td><td style="height: 29.7969px;">참조 데이터 획득 실패</td><td style="height: 29.7969px;">ref/out 타입의 데이터 값 획득 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3015</td><td style="height: 29.7969px;">호출 결과 값 타입 변환 실패</td><td style="height: 29.7969px;">Invoke 결과 값 데이터 타입 변환 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3016</td><td style="height: 29.7969px;">결과 값 Dictionary 변환 실패</td><td style="height: 29.7969px;">Invoke 결과 값 Dictionary&lt;string, T&gt; 변환 실패</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3017</td><td style="height: 29.7969px;">Client 연결 해제됨</td><td style="height: 29.7969px;">서비스 객체를 소유한 Client의 WebSocket 연결 해제</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3018</td><td style="height: 29.7969px;">서비스 객체 검색 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 서비스 객체 검색 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3019</td><td style="height: 29.7969px;">서비스 객체 추가 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 서비스 객체로 추가 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3020</td><td style="height: 29.7969px;">등록되지 않은 serviceId 요청</td><td style="height: 29.7969px;">등록되지 않은 serviceId가 요청 됨</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3021</td><td style="height: 29.7969px;">추상 서비스 객체 검색 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 추상 서비스 객체 검색 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3022</td><td style="height: 29.7969px;">추상 서비스 객체 추가 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 추상 서비스 객체 추가 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3023</td><td style="height: 29.7969px;">추상 서비스 객체 제거 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 추상 서비스 객체 제거 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3024</td><td style="height: 29.7969px;">Client의 소유 서비스 제거 실패</td><td style="height: 29.7969px;">대상 Client가 보유한 서비스 객체 제거 실패</td><td style="height: 29.7969px;">stateful 서비스</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3025</td><td style="height: 29.7969px;">serviceId 이미 등록됨</td><td style="height: 29.7969px;">대상 serviceId가 이미 등록되어 있음</td><td style="height: 29.7969px;">stateful 서비스</td></tr></tbody></table>

##### 4.4. 4000번대

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

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