====== Media 디바이스API 가이드 프로그램 ====== ===== 개요 ===== MediaAPI 가이드 프로그램은 모바일 디바이스 API 실행환경을 활용하여 하이브리드 앱을 개발하시는 분들이 디바이스 기기내 Media를 이용하여 서버에 전송하는 기능 구현 시, 참고 및 활용될 수 있도록 구현된 전자정부 디바이스 API에 대한 가이드 앱으로써, 모바일 스마트 디바이스의 Media 관련 기능을 JavaScript 기반으로 구성된 Media DeviceAPI 를 통하여 조회할 수 있도록 지원한다. 또한, 전자정부 표준 프레임워크 기반의 웹 서버 어플리케이션과 연계하여 디바이스 내, Media 정보를 서버로 전송 및 조회할 수 있는 기능으로 구성되어 있다. ==== 특징 ==== 본 가이드 프로그램 에서는 알람 기능을 가이드 할 수 있도록 **Media 파일 목록 서버로부터 수신하기** , **Media 플레이어** 기능을 제공하고 있다.\\ Media API를 이용하여, 미디어 파일을 재생하거나, 녹음 기능을 활용하여 생성한 미디어 파일을 서버에 전송한다. ==== 기능흐름도 ==== {{:egovframework:hyb:guide:add:egovframework_hyb_guide_add_media_미디어기능흐름도.png?740|}} ==== 기능시퀀스 ==== {{:egovframework:hyb:guide:add:미디어_기능시퀀스.png|}} ==== 전제 조건 ==== ^ 구분 ^ 내용 ^ |Local 디바이스 개발 환경|전자정부표준프레임워크 개발환경2.5, Android SDK Revision 18(적용빌드번호 : GINGERBREAD EL21)| |서버 사이드 개발 환경|전자정부표준프레임워크 개발환경2.5| |Mash up Open API 연계|N/A| |테스트 디바이스 |갤럭시S2 | |테스트 플랫폼 |Android 2.2| |추가 라이브러리 적용|N/A | ==== 제약사항 ==== ^ 구분 ^ 내용 ^ |크로스 도메인 사용|폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,\\ Res/xml/config.xml에서 에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.| ===== 설명 ===== Media 디바이스API 가이드 프로그램은 크게 서버에 저장된 미디어 파일을 재생하는 기능과 녹음 기능을 활용하여 설정한 알림 정보를 웹 서버 어플리케이션으로 전송 및 조회하는 기능으로 구성되어 있다.(관련기능 부분참조) === 클래스 다이어그램 === {{:egovframework:hyb:guide:add:egovframework_hyb_guide_add_media_클래스다이어그램.png}} ==== Device Application ==== === 관련 소스 === ^유형^대상소스명^비고^ |Activity|kr.go.egovframework.hyb.mediaapi.MediaAPIGuide_AndroidActivity|MediaAPI 가이드 프로그램 Activity Class| |CSS|assets/www/css/egovframwork/mbl/hyb/MediaAPI.css |MediaAPI 가이드 프로그램 주요 Cascading Style Sheets| |IMAGE |assets/www/images/egovframwork/mbl/hyb/ |MediaAPI 가이드 프로그램 주요 Image 폴더| |JS |assets/www/js/egovframwork/mbl/hyb/MediaAPI.js |MediaAPI 가이드 프로그램 주요 JavaScript| |JS |assets/www/js/egovframwork/mbl/hyb/messages_ko.js |Validate 메세지 처리 JavaScript| |RES |assets/www/res/ |MediaAPI 가이드 프로그램 주요 Resource 폴더| |XML |AndroidManiFest.xml |안드로이드 어플리케이션 설정 XML| |HTML|assets/www/MediaAPI.html|MediaAPI 메인 페이지| |HTML|assets/www/Intro.html|MediaAPI Intro 페이지| |HTML|assets/www/license.html|MediaAPI 라이센스 페이지| |HTML|assets/www/overview.html|MediaAPI 기능설명 페이지| === 활용 API === == Media == * 디바이스 내의 오디오 파일 재생 또는 녹음 기능을 제공하는 역할을 하는 객체이다. \\ var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]); == media.getCurrentPosition == * 미디어 파일의 현재 재생 위치 값을 구한다. \\ media.getCurrentPosition(mediaSuccess, [mediaError]); == media.getDuration == * 미디어 파일의 재생 지연 시간을 구한다. \\ media.getDuration(); == media.pause == * 오디오 파일의 재생을 멈춘다. \\ media.pause(); == media.play == * 미디어 파일을 재생을 한다. \\ media.play(); == media.release== * 운영체제(OS) 혹은 메모리 내의 Media 객체에 등록된 오디오 파일을 해제한다. \\ media.release(); == mediaError == * Media API 에 대한 에러 코드 ^에러코드^설명^비고^ | MEDIA_ERR_ABORTED|사용자에 의해 중단된 비디오 재생| | | MEDIA_ERR_NETWORK|네트워크 에러| | | MEDIA_ERR_DECODE|디코딩 에러(코덱문제)| | | MEDIA_ERR_SRC_NOT_SUPPORTED|지원하지 않는 형식의 오디오| | == LocalFileSystem == * 단말기의 루트(root) 파일 시스템에 접근할 수 있도록 지원하는 파일 시스템. window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, onError); == DirectoryEntry == * W3C Directories and Systems을 따르는 파일 시스템 디렉토리 관련 객체. * entry.getDirectory : 폴더를 가져오거나, 생성한다. var entry = entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail); == FileTransfer [upload] == * 서버에 파일을 업로드할 수 있도록 하는 파일 전송 객체. var options = new FileUploadOptions(); options.fileKey="file"; options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1); options.mimeType="text/plain"; var params = new Object(); params.value1 = "test"; params.value2 = "param"; options.params = params; var ft = new FileTransfer(); ft.upload(fileURI, "http://some.server.com/upload.php", transferSuccess, transferFail, options); == FileUploadOptions == * 파일 업로드시, 전달할 매개변수를 정의하는 업로드 속성객체 ^Option^설명^비고^ |fileKey|업로드할 파일의 변수명|설정하지 않으면 “file”로 정의된다.| |fileName|서버에 저장될 파일의 변수명.|설정하지 않으면 "image.jpg“ 로 정의된다.| |mimeType|데이터를 업로드시, mimeType을 설정한다.|설정하지 않으면 "image/jpeg“ 로 정의된다.| |params|서버에 추가로 전달할 매개변수.| | |chunkedMode|대형 스트림 모드 여부.|설정하지 않으면 "true“ 로 정의된다.| ==== Server Application ==== === 관련 소스 === ^유형^대상소스명^비고^ |Controller|egovframework.hyb.add.mda.web.EgovMediaAndroidAPIController.java|MediaAPI 가이드 프로그램 Controller Class| |Service|egovframework.hyb.add.mda.service.EgovMediaAndroidAPIService.java|MediaAPI 가이드 프로그램 Service Class| |ServiceImpl|egovframework.hyb.add.mda.service.impl.EgovMediaAndroidAPIServiceImpl.java|MediaAPI 가이드 프로그램 ServiceImpl Class| |VO|egovframework.hyb.add.mda.service.MediaAndroidAPIDefaultVO.java|MediaAPI 가이드 프로그램 VO Class| |VO|egovframework.hyb.add.mda.service.MediaAndroidAPIFileVO.java|MediaAPI 가이드 프로그램 VO Class| |VO|egovframework.hyb.add.mda.service.MediaAndroidAPIVO.java|MediaAPI 가이드 프로그램 VO Class| |VO|egovframework.hyb.add.mda.service.MediaAndroidAPIXmlVO.java|MediaAPI 가이드 프로그램 XML 관련 VO Class| |DAO|egovframework.hyb.add.mda.service.impl.MediaAndroidAPIDAO.java|MediaAPI 가이드 프로그램 Dao Class| |QUERY XML|resources/egovframework/sqlmap/hyb/add/mda/EgovMediaAndroidAPIGuide_XXX_mysql.xml|MediaAPI 가이드 프로그램 QUERY XML| |Idgen XML|resources/egovframework/spring/com/context-idgen.xml|MediaAPI 가이드 프로그램 Id생성 Idgen XML| === ID Generation === * ID Generation Service를 활용하기 위해서 Sequence 저장테이블인 COMTECOPSEQ에 FILE (파일 정보 ID) 항목을 추가해야 한다. === 관련 테이블 === ^테이블명^테이블명(영문)^비고^ |미디어|MEDIA|미디어 정보 관리| |파일상세정보|FILE_DETAIL_INFO|파일상세정보 관리| === 테이블 정의서 === * MEDIA ^No^컬럼ID^컬럼명^타입^길이^NULL^ |1|SN|일련번호|NUMERIC|6|NotNull| |2|UUID|UUID|VARCHAR|50|NotNull| |3|FILE_SN|파일연번|NUMERIC|20|NotNull| |4|MD_CODE|미디어구분코드|VARCHAR|40|Null| |5|MD_SJ|사진제목|VARCHAR|255|Null| |6|USEYN|활성화여부|CHAR|1|Null| |7|REVIV_CO|재생횟수|VARCHAR|40|Null| * FILE_DETAIL_INFO ^No^컬럼ID^컬럼명^타입^길이^NULL^ |1|FILE_SN |파일연번 |NUMERIC |20 |NotNull| |2|FILE_STRE_COURS |파일저장경로 |VARCHAR |2000 |Null| |3|STRE_FILE_NM |저장파일명 |VARCHAR |255 |Null| |4|ORIGNL_FILE_NM |원파일명 |VARCHAR |255 |Null| |5|FILE_EXTSN |파일확장자 |VARCHAR |20 |Null| |6|FILE_CN | |파일내용 |BLOB |Null| |7|FILE_SIZE |파일크기 |NUMERIC |8 |Null| === ERD === {{:egovframework:hyb:guide:ios:erd.jpg|}} ==== 유의 사항 ==== === 파일 생성 === * Media 객체를 통해 녹음 기능 사용 시, LocalFileSystem 내의 root의 egovMediaAPI 폴더 내에 Media 파일이 생성된다. === 파일 업로드 === * 파일 업로드 시, Phonegap에서 제공하고 있는 File API의 FileTransfer 객체를 통해 파일을 저장한다. === 스트리밍 === * 미디어 재생 시, 기존 Web에서 사용하는 스트리밍 방식을 이용하기 때문에 네트워크 상태가 Wi-fi 가 아닌 상태에서는 데이터 사용량을 유의하여야 한다. * 스트리밍 방식으로 인하여, 네트워크 상태에 따라 Media 오류 또는 재생이 지연된다. (지연시간 : 2초) function fn_setMediaDuration() { var counter = 0; timerDur = setInterval(function() { counter = counter + 50; if (counter > 2000) { clearInterval(timerDur); timerDur = null; fn_error(); } var dur = mediaObj.getDuration(); if (dur > 0) { ... clearInterval(timerDur); timerDur = null; } } , 100); } ===== 환경설정 ===== Vibrator 디바이스API 가이드 프로그램에서 제공하는 모바일 디바이스의 알림 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다. ==== Device Application ==== === res/xml/config.xml === === res/values/serverinfo.xml === http://192.168.100.222:8080/DeviceAPIGuideTotal_Web_V1.7.1 서버_URL === AndroidManifest.xml === ==== Server Application ==== === context-properties.xml === * 업로드 된 파일 저장 위치 === resource/egovframework/sqlmap/sql-map-config_[DB명].xml === ===== 관련기능 ===== ==== Media 파일 목록 서버로부터 수신하기 ==== === 비즈니스 규칙 === 서버에 저장된 파일 및 업로드 한 녹음 파일 목록을 조회한다. === 관련코드 === function fn_selectMediaList() { var url = "/mda/mediaInfoList.do"; var acceptType = "xml"; var params = { mdCode : "media" }; $.mobile.showPageLoadingMsg(); egovHyb.post(url, acceptType, params, function(xmldata) { console.log("DeviceAPIGuide fn_selectMediaList request Completed"); fn_displayList(xmldata); }); } === 관련화면 및 수행매뉴얼 === ^Action^URL^Controller method^QueryID^ |목록조회|/mda/mediaInfoList.do|selectMediaInfoList|"mediaAndroidAPIDAO.selectMediaInfoList"| {{:egovframework:hyb:guide:add:egovframework_hyb_guide_add_media_목록조회.png|}} 서버에 저장된 미디어 파일 목록을 조회하고, 디바이스 화면에 표시한다. 기능설명 : **기능설명** 화면으로 이동한다. \\ 라이선스 : **라이선스** 화면으로 이동한다. \\ 미디어파일내용 : **미디어재생** 화면으로 이동한다. \\ ==== Media 플레이어 ==== === 비즈니스 규칙 === 디바이스 API를 통해 Media 생성/해지, Media 재생/정지, 길이를 조회하며, 녹음시작/중지를 통해 저장한 녹음 파일을 서버에 업로드하여 저장한다. === 관련코드 === == 상세 정보 조회 == function fn_selectMediaInfoDetail(sn) { var url = "/mda/mediaInfoDetail.do"; var acceptType = "xml"; var params = { sn : sn }; $.mobile.showPageLoadingMsg(); egovHyb.post(url, acceptType, params, function(xmldata) { console.log("DeviceAPIGuide fn_selectMediaInfoDetail request Completed"); fn_displayDetail(xmldata); }); } == 미디어 재생 == function fn_mediaPlayEvent() { ... fn_mediaPlay(); playTimer = setInterval(function(){ mediaObj.getCurrentPosition(fn_currentPositionSuccess, fn_currentPositionError); }, 1000); } == 미디어 녹음 == function fn_mediaRecordStartEvent() { ... var recordSj = fn_mediaRecordStart(); recTime = 0; ... recordTimer = setInterval(function() { recTime = recTime + 1; ... } , 1000); } == 파일 업로드 == function fn_insertRecordFile() { var file = fileURL.substr(fileURL.lastIndexOf('/') + 1); var options = new FileUploadOptions(); options.fileKey = "file"; options.fileName = file; options.mimeType = "audio/mp3"; var params = { mdSj : file, uuid : encodeURI(device.uuid) }; options.params = params; var ft = new FileTransfer(); ft.upload(fileURL, loadServer + "/mda/mediaRecordUpload.do", fn_insertSuccess, fn_error, options); } } === 관련화면 및 수행매뉴얼 === ^Action^URL^Controller method^QueryID^ |미디어상세정보 조회|/mda/mediaInfoDetail.do|selectMediaInfoDetail|"mediaAndroidAPIDAO.selectMediaInfoDetail"| |미디어재생횟수 수정|/mda/mediaInfoDetail.do|selectMediaInfoDetail|"mediaAndroidAPIDAO.updateMediaInfoRevivCo"| |미디어파일 조회|/mda/mediaInfoDetail.do|getImageInf|"mediaAndroidAPIDAO.selectMediaFileInfo"| {{:egovframework:hyb:guide:add:egovframework_hyb_guide_add_media_재생.png|}} {{:egovframework:hyb:guide:add:egovframework_hyb_guide_add_media_녹음.png|}} == 재생 == 스트리밍 방식을 이용하여 서버에 저장된 미디어 파일을 재생/일시정지/위치이동 하는 플레이어 기능을 한다. 기능설명 : **기능설명** 화면으로 이동한다. \\ 라이선스 : **라이선스** 화면으로 이동한다. \\ 목록 : **미디어 목록 조회** 화면으로 이동한다. \\ 녹음 : ** 녹음 ** 기능을 활성화한다. 재생/정지 : **미디어 파일** 을 재생/정지한다. == 녹음 == 미디어 파일을 생성하고, 정지 버튼을 통해 서버에 해당 파일을 업로드 한다. 기능설명 : **기능설명** 화면으로 이동한다. \\ 라이선스 : **라이선스** 화면으로 이동한다. \\ 목록 : **미디어 목록 조회** 화면으로 이동한다. \\ 재생: ** 이전 미디어 파일 재생 ** 기능을 활성화한다. 녹음/정지 : **미디어 파일** 을 녹음/정지한다. ===== 컴파일 디버깅 배포 ===== ==== 컴파일 ==== === MediaAPI Device Applicaton 컴파일 방법 === * 프로젝트 선택 > 오른쪽 클릭 > Run As > Android Application {{:egovframework:hyb:guide:add:미디어_컴파일1.png?740|}} * 상단의 메뉴 > Run As > Android Application {{:egovframework:hyb:guide:add:미디어_컴파일2.png?740|}} * 실행할 타겟 선택 > 에뮬레이터, 디바이스(디버깅모드) {{:egovframework:hyb:guide:add:디바이스컴파일.png?740|}} * 에뮬레이터를 이용한 실행 화면 {{:egovframework:hyb:guide:add:미디어_컴파일4.png?400|}} {{:egovframework:hyb:guide:add:미디어_컴파일5.png?400|}} * 디바이스를 이용한 실행 화면 {{:egovframework:hyb:guide:add:미디어_컴파일6.png?400|}} {{:egovframework:hyb:guide:add:미디어_컴파일7.png?400|}} === MediaAPI Server Applicaton 컴파일 방법 === * MediaAPI 서버사이드 가이드 프로그램의 실행은 프로젝트를 마우스 오른쪽 버튼을 클릭 한후 Run As>Run On Server 버튼을 통해 실행 할 수 있다. {{:egovframework:hyb:guide:add:서버실행.png?640|}} * 빌드가 성공적으로 수행 되면 이클립스의 콘솔 창에서 'Server Startup in xxx ms' 메시지를 확인 할 수 있다. {{:egovframework:hyb:guide:add:서버실행결과_콘솔.png?840|}} ==== 디버깅 ==== 디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 Phonegap 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스 및 Xcode에서 확인 할 수 있다. console.log의 작성 방법은 다음과 같다. function fn_egov_network_check(doCheck) { console.log('DeviceAPIGuide fn_egov_network_check'); var networkState = navigator.network.connection.type; ... } 디버깅 코드가 실행 되면 아래와 같은 메시지를 개발도구의 콘솔 메시지 창에서 볼 수 있다. {{:egovframework:hyb:guide:add:FileReadWriteconsolelog.png?700|}} Media 디바이스 API 가이드 프로그램 에서는 디버깅을 위하여 다음과 같이 콘솔 정보를 출력한다. ^디버그 코드^디버깅 내용^ |DeviceAPIGuide fn_egov_deviceConfig Success | 디바이스의 서버 정보를 성공적으로 획득 시.| |DeviceAPIGuide Media Config Success | Media 디바이스API를 수행할 경우, 성공적으로 동작 시.| |DeviceAPIGuide fn_egov_currentPositionSuccess Success | 미디어 파일 재생할 경우, 현재 위치를 성공적으로 불러올 시.| |DeviceAPIGuide fn_egov_currentPositionError Error | 미디어 파일 재생할 경우, 현재 위치 불러오기가 실패할 시.| |DeviceAPIGuide fn_egov_insertRecordFile request Completed | 파일을 성공적으로 업로드할 시.| |DeviceAPIGuide fn_egov_selectMediaList request Completed | 미디어 파일 목록 조회를 성공적으로 수행 시.| |DeviceAPIGuide fn_egov_selectMediaInfoDetail request Completed | 미디어 파일 상세 정보 조회를 성공적으로 수행 시.| |DeviceAPIGuide fn_egov_setMediaDuration Success | 미디어 파일 재생 시간을 성공적으로 불러올 시.| |DeviceAPIGuide fn_egov_error Error | 전체적인 에러 시.| ==== 배포 ==== Media 디바이스 API 가이드 다운로드 : [[http://www.egovframe.go.kr/cop/bbs/selectBoardArticle.do?bbsId=BBSMSTR_000000000161&nttId=530&menu=3&submenu=9|Click]] \\ ===== 참고자료 ===== * UX/UI 라이브러리 : [[http://jquerymobile.com/|jQuery Mobile]] \\ * Hybrid : [[http://www.phonegap.com/|PhoneGap]] \\