서비스 및 통신 프로토콜

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

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

1. 서비스 정의

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

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

<eXDevice+ 서비스 호출 과정>

2. eXDevice+ 요청 프로토콜

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

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

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

3. eXDevice+ 응답 프로토콜

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

{
  "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 요청

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

4.2. 2000번대

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

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

상태코드	분류	상태코드 상세	비고
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번이 발생한 경우, 호출한 서비스에서 제공하는 상태 코드를 확인하시길 바랍니다.