정보통신단체표준(국문표준) i ttak.ot-10.0323 서 문 1. 표준의 목적 본 표준은...

T T

A S

t a n

d a

r d

정보통신단체표준(국문표준)

TTAK.OT-10.0323 제정일: 2011년 12월 21일

한국 통합 앱 스토어 디바이스 API

Korea Apps Device API


TTAK.OT-10.0323 제정일: 2011년 12월 21일


Korea Apps Device API

본 문서에 대한 저작권은 TTA 에 있으며, TTA 와 사전 협의 없이 이 문서의 전체 또는 일부를

상업적 목적으로 복제 또는 배포해서는 안 됩니다.

Copyrightⓒ Telecommunications Technology Association 2011. All Rights Reserved.


i TTAK.OT-10.0323

서 문

1. 표준의 목적

본 표준은 한국형 통합 앱 스토어 디바이스 API 에서 디바이스(Device) 연동을 위한

API 를 정의한다.

2. 주요 내용 요약

주요 내용으로는 WAC2.0 규격에서 정의한 Device APIs 규격을 준수하는 한국 통합

앱 스토어 디바이스(Device) APIs 정의하고 있으며 국제 표준과의 호환 가능하도록

정의하여 상호 연동성을 보장한다.

3. 표준 적용 산업 분야 및 산업에 미치는 영향

독자적인 표준 제정을 방지함으로써 국내 개발사의 리소스 감소 및 효율성 증대가 기

대되며 이통사별 별도 표준 파생으로 인한 콘텐츠 산업 발전의 저해 요소를 예방하고

모바일 응용 표준 경쟁력 확보를 통한 글로벌 시장에서 국내기업의 모바일 경쟁력 확보

가 가능할 것이다.

4. 참조 표준(권고)

4.1. 국외 표준(권고)

- WAC 2.0 Approved Release Version (ARV), 2011.07.


ii TTAK.OT-10.0323

4.2. 국내 표준

- 해당 사항 없음

5. 참조 표준(권고)과의 비교

5.1. 참조 표준(권고)과의 관련성

본 표준은 WAC 2.0 표준의 기본적인 사항을 만족하면서 한국 통합 앱 스토어(K-

Apps) 서비스에 맞도록 최적화하였다. 서비스 측면에서는 상위 국제 표준을 만족하고

동시에 국내 서비스 환경에 맞도록 항목들을 재구성하였다.

5.2. 참조한 표준(권고)과 본 표준의 비교표

TTAK.OT-10.0323 WAC 2.0 Approved Release Version 비고

1. 개요 1. 개요 동일

2. 표준의 구성 및 범위 2. 표준의 구성 및 범위 동일

3. 용어 정의 3. 용어 정의 동일

4. 디바이스(Device) API 요구 사항 4. 디바이스(Device) API 요구 사항 동일

TTAK.OT-10.0323 WAC 2.0 Approved Release Version 비고

1. 개요 1. 개요 동일

2. 표준의 구성 및 범위 2. 표준의 구성 및 범위 동일

3. 용어 정의 3. 용어 정의 동일

4. 디바이스(Device) API 요구 사항 4. 디바이스(Device) API 요구 사항 동일


iii TTAK.OT-10.0323

6. 지적 재산권 관련 사항

본 표준의 ‘지적 재산권 확약서’ 제출 현황은 TTA 웹 사이트에서 확인할 수 있다.

※ 본 표준을 이용하는 자는 이용함에 있어 지적 재산권이 포함되어 있을 수 있으므로,

확인 후 이용한다.

※ 본 표준과 관련하여 접수된 확약서 이외에도 지적 재산권이 존재할 수 있다

7. 시험 인증 관련 사항

7.1. 시험 인증 대상 여부


7.2. 시험 표준 제정 현황


8. 표준의 이력 정보

8.1. 표준의 이력

판 수 제정·개정일 제정·개정 내역

제 1 판 2011.12.21. 제정

TTAK.OT-10.0323

8.2. 주요 개정 사항



iv TTAK.OT-10.0323

Preface

1. Purpose of Standard

This standard defines the APIs developed by the Korea Apps(K-Apps) for accessing

the device capabilities.

2. Summary of Contents

This standard defines the device APIs of Korea Apps(K-Apps), which observes the

device APIs of WAC. Moreover it assures the interoperability with International

Standards.

3. Applicable Fields of Industry and its Effect

This standard expects to decrease the development resource and increase

development effectiveness as preventing the establishment of independent Standard.

And it is possible to prevent a growing of disturbance factors of the contents industry

because of independent standards of each operator. According to such factors, it is

possible to procure the competitiveness of mobile industry of domestic companies in

a global market through obtaining the competitiveness of mobile application standard.


v TTAK.OT-10.0323

4. Reference Standards(Recommendations)

4.1. International Standards(Recommendations)

- WAC 2.0 Approved Release Version(ARV), 2011.07.

4.2. Domestic Standards

- None

5. Relationship to Reference Standards(Recommendations)

5.1. Relationship of Reference Standards(Recommendations)

This standard has been developed refer to WAC 2.0. Moreover is designed for Korea

Apps. From the point of view service, it is satisfied a global standard and

reconstructed the items which adapt for domestic environment at the same time.

5.2. Differences between Reference Standard(Recommendation) and this Standard

TTAK.OT-10.0323 WAC 2.0 Approved Release Version Remarks

1. Introduction 1. Introduction Same

2. Constitution and Scope 2. Constitution and Scope Same

3. Terms and Definitions 3. Terms and Definitions Same

4. Device API Requirements 4. Device API Requirements Same


vi TTAK.OT-10.0323

6. Statement of Intellectual Property Rights

IPRs related to the present document may have been declared to TTA. The

information pertaining to these IPRs, if any, is available on the TTA Website.

No guarantee can be given as to the existence of other IPRs not referenced on the

TTA website.

And, please make sure to check before applying the standard.

7. Statement of Testing and Certification

7.1. Object of Testing and Certification

- None

7.2. Standards of Testing and Certification

- None

8. History of Standard

8.1. Change History

Edition Issued date Outline

The 1st edition 2011.10.05. Established

TTAK.OT-10.0323

8.2. Revisions

- None


vii TTAK.OT-10.0323

목 차

1. 개요 ............................................................................................................. 1

2. 표준의 구성 및 범위 ....................................................................................... 1

3. 용어 정의 ...................................................................................................... 1

4. Device API 요구 사항 .................................................................................... 15

4.1. Deviceapis 모듈 ..................................................................................... 15

4.2. 가속도계 모듈 ........................................................................................ 33

4.3. 오리엔테이션(orientation) 모듈 ................................................................. 46

4.4. 카메라 모듈........................................................................................... 60

4.5. 디바이스(devicestatus) 모듈 .................................................................... 80

4.6. 파일시스템(filesystem) 모듈 ..................................................................... 98

4.7. 메시징(messaging) 모듈 ....................................................................... 154

4.8. 개인 정보 관리(PIM) 모듈 ..................................................................... 192

4.9. 콘택트(contact) 모듈 ............................................................................ 194

4.10. 캘린더(calendar) 모듈 ......................................................................... 234

4.11. 작업(task) 모듈 .................................................................................. 271

4.12. 장치상호작용(deviceinteraction) 모듈 .................................................... 305

4.13. 장치 상태(Device Status) 용어총람 ....................................................... 320

4.14. WebIDL 설명 ...................................................................................... 340

4.15. 설계 패턴과 표준을 위한 가이드(Design Patterns & Guidelines) ................ 362

4.16. 에러 처리 .......................................................................................... 365


i TTAK.OT-10.0323

Contents

1. Introduction .................................................................................................... 1

2. Constitution and Scope .................................................................................... 1

3. Terms and Definitions ............................... 오류! 책갈피가 정의되어 있지 않습니다.1

4. Device API Requirement ................................................................................. 15

4.1. Deviceapis module .................................................................................. 15

4.2. Accelerometer module ............................................................................. 33

4.3. Orientation module .................................................................................. 46

4.4. Camera module ...................................................................................... 60

4.5. Devicestatus module ............................................................................... 80

4.6. Filesystem module .................................................................................. 98

4.7. Messaging module ................................................................................ 154

4.8. PIM module .......................................................................................... 192

4.9. Contact module .................................................................................... 194

4.10. Calendar module ................................................................................. 234

4.11. Task module ....................................................................................... 271

4.12. Deviceinteraction module ..................................................................... 305

4.13. The Vocabulary for the device status ...................................................... 320

4.14. WebIDL Definition ................................................................................ 340

4.15. Guidelines and Patterns for API Definition ............................................... 362

4.16. Error Handling ..................................................................................... 365


1 TTAK.OT-10.0323


(Korea Apps Device API)

1. 개요

본 표준은 WAC 2.0 Device APIs 규격을 준수하여 장치 기능에 접근할 수 있도록

개발된 Korea Apps(K-Apps) 디바이스 API 를 정의한다. 모듈들은 deviceapis

EcmaScript 오브젝트를 통해 제공된다. 개발자에게 제공된 기능들은 API 각 영역의

기능들과 함께 각 모듈에 연결되어 있어 있다.

2. 표준의 구성 및 범위

본 표준은 K-Apps 디바이스 API 를 구성하는 각 모듈(deviceapis, 가속도계, 방향,

카메라, devicestatus, 파일시스템, 메시징, 위치, PIM, 주소록, 일정, 작업,

deviceinteraction)에 대한 정의와 요구 사항을 기술하고 있다. 각 장치 API 는 호스트

디바이스에 적용된 장치가 제공하는 기능과 운영체제에 영향을 받는다. 모든 API 가

모든 플랫폼에서 유효한 것은 아니며 최대한 많은 장치가 의미있는 수준으로 조작될 수

있도록 표준이 구성되었다.

3. 용어 정의

본 설명에서는 다음과 같은 용어들이 사용되었다.

3.1. 응용 프로그램 인터페이스(API: Application Programming Interface)

인터페이스 제공자로부터 서비스(즉, 데이터)를 받기 위해 프로그램되는

애플리케이션을 실행할 수 있도록 해주는 특정한 인터페이스.


2 TTAK.OT-10.0323

3.2. 앱스토어(AppStore)

위젯 찾기, 선택, 프리뷰(preview), 지불, 인증, 업데이트 등과 같이 애플리케이션과

관련된 사용자의 다양한 기능(capability)을 가능하게 해주는 일련의 클라이언트와

서버 기능.

3.3. 앱스토어 클라이언트(AppStore Client)

클라이언트 입장에서 앱스토어의 기능을 지원하는 디바이스 클라이언트(device

client)

3.4. 앱스토어 서버(AppStore Server)

서버 입장에서 앱스토어의 기능을 지원하는 네트워크 서버

3.5. 서명자 서명(Author Signature)

위젯 디지털 서명 [Widgets-DigSig]에서 규정하는 서명자 서명에 대한 제한

조건을 만족시키는 위젯 서명

3.6. 브라우저(Browser)

웹사이트를 지원하며 웹 런타임을 제공하는 디바이스 애플리케이션.

3.7. 종속형 시트(CSS: Cascading Style Sheets)

종속형 시트(CSS)는 마크업 언어로 작성된 문서의 의미를 설명하기 위해 사용되는

스타일 시트(style sheet)이다. 가장 일반적인 응용방법은 HTML 과 XHTML 로 된

웹페이지를 만드는 것이다. 그러나 이 언어는 모든 종류의 XML 문서에도 사용될

수 있다.


3 TTAK.OT-10.0323

3.8. 종속형 시트 객체 모델(CSSOM: Cascading Style Sheets Object Model)

CSSOM 은 미디어 쿼리(Media Query), 셀렉터(Selector), CSS 등을 위해

API(일반적인 파싱(parsing) 및 일련 번호 나열 규칙 포함)를 정의해 준다

.

3.9. 인증 기관(CA: Certification Authority)

CA 기반구조를 운영하는 기관이 서명한 혹은 이 기관에서 소유한 최상위

인증서(root certificate)로 제한된 인증서를 발급해 주는 기반구조. 일반적으로

CA 를 운영하는 단체는 복수의 최상위 인증서를 가지고 있으며, 특정한 최상위

인증서에 따라 서명된 인증서를 발급하는데 필요한 비즈니스 레벨(level of

business)이나 도메인 확인과 같은 여러 가지 인증 작업을 요구한다.

3.10. 인증서 폐기 리스트(CRL: Certificate Revocation List)

암호체계를 운영할 때 인증서 폐기 리스트인 공개키 기반구조(PKI)가 취소됨에

따라 더 이상 의존해서는 안 되는 인증서 리스트(좀 더 구체적으로 말하면 인증서

일련 번호 리스트).

3.11. ClientHello

클라이언트가 처음으로 서버에 연결할 때에는 첫 번째 메시지로 ClientHello 를

보내야 한다. 또 클라이언트는 HelloRequest 에 대한 답신으로 혹은 기존의 연결

상태에서 보안 파라미터(security parameter)를 협상하기 위해 자발적으로

ClientHello 를 보낸다. 이에 대한 자세한 정보는 http://tools.ietf.org/에서 확인할

수 있다.


4 TTAK.OT-10.0323

3.12. 디바이스 기능(Device Capability)

WAC 애플리케이션이 접근, 조정, 탐색할 수 있는 디바이스의 구체적인 리소스

혹은 기능을 말한다. 디바이스 기능이란 특정한 JavaScript API 나 기본

소프트웨어 플랫폼, 특정한 플랫폼의 API 등에 의존하지 않고 다른 디바이스로

옮겨질 수 있다.

3.13. 디지털 저작권 관리(DRM: Digital Rights Management)

디지털 저작권 관리(DRM)는 디지털 콘텐츠와 디바이스의 사용을 제한하기 위해

하드웨어 제조업자, 출판업자, 저작권 소유자, 개인 등이 사용할 수 있는 접근

제어 기술을 의미한다.

3.14. 배포자 서명(Distributor Signature)

[Widgets-DigSig]에서 규정한 배포자 서명을 위한 제약 조건을 충족시키는 위젯

서명.

3.15. 배포자가 서명한(Distributor Signed)

유효한 배포자 서명(Verified Distributor Signature)을 받은 것을 의미한다. 어떤

위젯이 WAC 서명을 받았다면(WAC-signed), 이는 배포자가 서명했다는 것을

의미한다. 그러나 반대의 경우는 성립되지 않는다.

3.16. 문서객체모델(DOM: Document Object Model)

문서객체모델은 HTML, XHTML, XML 로 된 객체로, 이와 상호작용하는 크로스

플랫폼(cross-platform)이고 언어이다. DOM 은 사용 중인 프로그램 언어 체계

내에서 처리되고 관리된다.


5 TTAK.OT-10.0323

3.17. DPI(Dots per Inch)

DPI 는 공간에 인쇄된 혹은 화면에 나타나는 점의 밀도를 측정한 것으로,

1 인치(2.54cm) 내의 선에 있는 점의 개수를 의미한다. DPI 수치는 이미지

해상도와 관련이 있으나, 간접적으로만 관련이 있다.

3.18. 다운로드 매니저(Download Manager)

WAC 위젯을 안전하게 다운로드 할 수 있도록 만들어 주는 클라이언트의 기능을

지원해 주는 디바이스 클라이언트.

3.19. 확장 검증(EV: Extended Validation)

확장 검증 인증이란 TLS/SSL 프로토콜을 통해 웹 기반의 데이터 이동 통로를

구축하기 위해 또 실행 가능한 코드의 인증을 확인하기 위해 만들어졌다.

3.20. 피쳐(Feature)

특정한 디바이스 기능에 접근할 수 있도록 해주는 일련의 JavaScript APIs 나

디바이스 행동을 의미한다. 피쳐은 IRI 에 의해서만 확인되며, WAC 애플리케이션에

의존하는 정도를 나타낸다.

3.21. HTML 의 알려지지 않은 요소(HTML Unknown Elements)

WRT 에 의해 지원되지 않는 HTML 요소.

3.22. HTML(Hypertext Markup Language)

웹 페이지를 만들 때 사용하는 언어.


6 TTAK.OT-10.0323

3.23. HTTP(Hypertext Transfer Protocol)

HTTP 는 분산형 데이터 처리방식의 하이퍼미디어(hypermedia) 정보 시스템을

말한다. HTTP 는 월드 와이드 웹(www, World Wide Web)에서의 데이터 통신

기초가 된다.

3.24. HTTPS(Hypertext Transfer Protocol Secure)

HTTPS 는 암호화된 통신과 네트워크 웹 서버의 안전한 확인을 위해 HTTP 와

SSL/TLS 프로토콜을 결합한 것이다.

3.25. 아이프레임(Inline Frames, iframe)

HTML 문서에서 서명자가 텍스트에 프레임을 삽입할 수 있도록 만들어 주는

인라인 프레임.

3.26. 국제휴대장치식별번호(IMEI: International Mobile Equipment Identity)

IMEI 는 휴대 장치(전화)와 위성 전화를 확인해 주는 유일한 숫자를 의미한다.

3.27. 국제화된 자원 식별자(IRI: Internationalised Resource Identifier)

유니코드의 사용을 허용해 주는 월드 와이드 웹 자원인 URI(Uniform Resource

Identifieer)를 말한다.

3.28. 유효하지 않은 서명(Invalid Signature)

유효한 서명(Valid Signature)이 아닌 위젯 서명(Widget Signature)


7 TTAK.OT-10.0323

3.29. 자바스크립트(JavaScript )

자바스크립트는 ECMAScript 언어로서, 클라인언트 입장에서 자바스크립트 형태로

사용된다. 이는 개선된 사용자 인터페이스와 다이나믹한 웹사이트를 제공하기

위하여 웹 브라우저의 일부분으로써 실행되며, 호스트 환경에서 컴퓨터

객체(computational object)에 대한 계획적인 접근을 가능하게 해준다.

3.30. 자바스크립트 API(JavaScript API)

인터페이스 정의언어(IDL, Interface Definition Language)를 사용하여 정의된 웹

애플리케이션(Web Applications)을 위한 프로그램 인터페이스. 일반적으로

자바스크립트 API 는 디바이스 기능(Device Capabilities)에 대한 접근을 목적으로

WAC 애플리케이션을 실행하기 위한 수단으로써 제공된다. 그러나 API 그 자체의

정의는 AIP 를 구성하는 인터페이스, 방법, 성질 및 기타 속성 등과 관련되어 있다.

그리고 API 의 정의를 특정한 디바이스 기능과 연관시킬 필요는 없으며, API 에

대한 접근이 기본적인 디바이스 기능에 대한 접근이라는 것을 의미하지는 않는다.

3.31. 휴대장치 확인자(MEID: Mobile Equipment Identifier)

MEID 는 이동국 장치(mobile station equipment)를 확인해 주는 전 세계적으로

하나밖에 없는 숫자이다.

3.32. 다목적 인터넷 전자우편(MIME: Multipurpose Internet Mail Extensions)

MIME 는 그 값이 MIME 형태인 여러 가지 프로토콜에 있는 헤더의 이름으로,

인터넷에서의 파일 포맷에 대한 2 부 확인자(two-part identifier)이다.

3.33. 온라인 인증서 상태 프로토콜(OCSP: Online Certificate Status Protocol)

OCSP 는 [RFC 2560]에서 규정한 X.509 디지털 인증서의 취소 지위를 얻기 위해

사용되는 인터넷 프로토콜이다.


8 TTAK.OT-10.0323

3.34. OCSP 지위(OCSP Status)

인증서의 취소 상태를 결정하기 위한 규정(rules for determining the revocation

status of a certificate)에 따른 OCSP 확인 결과에 기초한 인증서 상태.

3.35. 주문자 상표 부착 생산(OEM: Original equipment manufacturer)

주문자 상표 부착 생산 혹은 OEM 은 어떤 회사가 구매회사의 상표로 구매

회사가 구매하는 제품이나 컴포넌트를 제조하는 것을 의미한다. OEM 은 제품을

원래 제조하는 회사와 관련이 있는 말이다.

3.36. 웹 자원 기술 프로토콜(POWDER: Protocol for Web Description Resources)

웹 자원 기술 프로토콜(POWDER)은 W3C 에서 권장하는 웹 자원(resource)을

기술(description)하는 방법이다. 이는 웹 리소스에 대한 메타 데이터를 알리는

프로토콜을 규정해 준다.

3.37. 공중 육상 이동 네트워크(PLMN: Public Land Mobile Networks)

PLMN 은 관리자나 대중에게 육상 이동통신 서비스를 제공하려는 구체적인 목적을

가진 것으로 인정되는 운영 기관이 구축하고 관리하는 네트워크를 의미한다.

3.38. 승인되는(Recognised )

위젯 서명의 상태를 결정하기 위한 규정(rules for determining the status of a

widget signature)에 기초하여 확인된(verifired) 것을 의미한다.

3.39. 승인된 출처(Recognised Origin)

인정된 위젯(recognised widget)의 ID 속성으로부터 유래된 출처.


9 TTAK.OT-10.0323

3.40. 취소된 서명(Revoked Signature)

위젯 서명의 취소 상태를 결정하기 위한 규정(rules for determining the

revocation status of a widget signature)에 기초하여 취소되기로 결정된 위젯

서명(Widget Signature).

3.41. 가변 벡터 도형(SVG: Scalable Vector Graphics)

가변 벡터 도형 처리는 정적 및 동적인(즉, 인터액티브(interactive) 혹은

애니메이티드(animated)한) 2 차원의 벡터 그래픽을 설명하기 위한 XML 기반의

파일 포맷을 의미한다.

3.42. 보안 소켓 계층(SSL: Secure Sockets Layer)

SSL 은 인터넷상에서의 통신 보안을 제공하는 암호 프로토콜이다. SSL 은

개인정보 보호를 위해 대칭 암호화 방식(symmetric cryptography)을 그리고

메시지의 신뢰성을 위해서는 키(key) 메시지 인증코드를 사용하여 전송 계층 위로

네트워크 연결의 세그먼트(segment)를 암호화 해준다.

3.43. 보안 매니저(Security Manager)

다양한 보안정책의 관리 및 실행을 지원하는 디바이스 소프트웨어

3.44. SMS(Short Message Service)

SMS(문자서비스)는 전화 및 휴대전화에서 사용하는 텍스트 문자 통신 형태를

의미한다.


10 TTAK.OT-10.0323

3.45. 사이드 로드(Side-Load)

웹 런타임(Web Runtime)이나 웹 런타임(Web Runtime)과 안전하게 통합된

앱스토어 클라이언트(AppStore Client)와 같은 WAC 인증 클라이언트를 통해

다운로드된 위젯(Widget) 패키지를 받는 것(importation)을 의미한다.

3.46. 가입자 식별 모듈(SIM: Subscriber Identity Module)

분리성 카드(SIM 카드)에 있는 가입자 식별 모듈 혹은 가입자 확인 모듈은 휴대

전화 장치(휴대 전화나 컴퓨터 등)의 가입자를 확인하는 데 사용되는 서비스

가입자 키를 안전하게 저장해 준다.

3.47. 테스트 서명(Test Signature)

목표로 하는 제한조건을 포함하고 있는 배포자의 서명.

3.48. 전송 계층 보안(TLS: Transport Layer Security)

TLS 는 SSL 를 대신하는 것으로, 인터넷 상에서의 통신 보안을 제공해 주는 암호

프로토콜이다.

3.49. 신뢰할 수 있는 애플리케이션(Trusted Application)

보안 정책에 따른 다양한 애플리케이션 속성과 설치 속성에 기초하여 특정 신뢰

수준에서 할당된 애플리케이션.

3.50. URI(Uniform Resource Identifier)

URI 는 인터넷 상에서의 이름이나 리소스를 확인하기 위해 사용되는 일련의

글자들이다. 이러한 확인을 통해 네트워크 상에서 리소스 간 상호작용이 가능하다.


11 TTAK.OT-10.0323

3.51. URL(Uniform Resource Locator)

URL 은 확인된 리소스가 어디에 있는지 또 이를 탐색하는 메커니즘이 어디에

있는지에 대해 규정하는 URI 를 의미한다.

3.52. 승인되지 않는( Unrecognised)

승인되지(Recognised) 않는다는 것을 의미한다.

3.53. 사용자 에이전트(User Agent)

사용자 에이전트는 클라이언트-서버 컴퓨터 시스템에서의 통신에 사용되는

네트워크 프로토콜을 실행하는 클라이언트 애플리케이션을 의미한다.

3.54. 신뢰할 수 없는 애플리케이션(Untrusted Application)

특정 수준의 신뢰를 받지 못한 애플리케이션으로, 디폴트 수준의 신뢰수준을 갖고

있다.

3.55. 유효한 서명(Valid Signature)


widget signature)에 기초하여 유효한 것으로 결정되는 위젯 서명(Widget

Signature)을 의미한다.

3.56. 검증된 서명(Verified Signature)


widget signature)에 기초하여 확인된 것으로 결정되는 위젯 서명(Widget

Signature)을 의미한다.


12 TTAK.OT-10.0323

3.57. WAC 홀세일 애플리케이션 커뮤니티

Wholesale Applications Community 로 슈퍼앱 스토어를 의미한다.

3.58. WAC 인증 기관(CA: WAC Certification Authority)

WAC 에서 운영하는 CA

3.59. WAC 에서 인증한(WAC-certified)

관련된 모든 WAC 요건을 충족하는 것으로 WAC 에서 확인 받았다는 것을

의미한다.

3.60. WAC 에서 승인한 인증 기관(WAC-recognised Certification Authority (CA))

WAC 에서 승인한 신원 인증서(WAC-recognised Identity Certificates) 발급

요건을 충족하면서 WAC 에서 인정한 인증 권한을 가진 인증 기관(CA)

3.61. WAC 에서 승인한 식별(WAC-recognised Identity)

세 등급의 승인 받은 서명자(classes of recognised author identity) 중의 하나에

포함되는 서명자에게 할당되고 이 서명자가 소유한 도메인.

3.62. WAC 에서 승인한 식별 인증서(WAC-recognised Identity Certificate)

WAC 에서 승인한 신원(WAC-recognised Identity)을 대신하여 WAC 에서 인증받은

CA(WAC-recognised CA) 에서 발급해주는 인증서.

3.63. WAC 의 최상위 인증서(WAC root certificate)

WAC CA 에서 발급한 최상위 인증서.


13 TTAK.OT-10.0323

3.64. WAC 에서 서명한(WAC-signed)

테스트 서명(Test Signature)이 아닌 또 WAC 의 최상위 인증서(WAC root

certificate)를 제한하는 최소 하나 이상의 확인된 배포자 서명(Verified Distributor

Signature)을 포함하고 있는 위젯 패키지.

3.65. WAC 테스트 위젯(WAC test widget)

하나 이상의 테스트 서명(Test Signatures)이 있는 위젯.

3.66. 웹 애플리케이션(Web Application)

HTML, 자바스크립트, CSS, 여러 미디어 포맷 등과 같이 웹 포맷에서 개발된

애플리케이션.

3.67. 웹 런타임(WRT: Web Runtime)

웹 애플리케이션의 실행을 지원하는 디바이스 소프트웨어. WAC 에서

인증한(WAC-certified) WRT 는 WAC 에서 규정한 웹의 주요 특성, API, API 보안

등을 지원한다.

3.68. 웹사이트(Website)

원격으로 호스트되는 리소스의 집합으로, 웹 포맷(HTML, 자바스크립트, CSS,

여러 미디어 포맷 포함)에서 개발되고, 웹 서버가 서비스를 제공하며, 브라우저를

통해 볼 수 있다.

3.69. 위젯(Widget)

로컬 데이터 혹은 웹 상의 데이터를 보여주기 위하여 상호 작용하는

애플리케이션으로, 한 번의 다운로드로 실행할 수 있고 사용자의 장치나 휴대용

디바이스에 설치할 수 있다.


14 TTAK.OT-10.0323

3.70. 위젯 접근 요청 정책(WARP, Widget Access Request Policy)

위젯 내에서 네트워크 접근을 제어하고, 특정 네트워크 리소스에 대한 사용자

에이전트의 접근을 허용해주는 위젯 서명자의 방법을 의미한다.

3.71. 위젯 엔진(Widget Engine)

위젯(Widgets)을 지원하는 웹 런타임 환경(Web Runtime Environment)을

제공하는 디바이스 소프트웨어.

3.72. 위젯 매니저(Widget Manager)

위젯 설치, 업데이트, 선택 관리 등과 같은 위젯의 여러 생명주기 단계를

지원해주는 디바이스 소프트웨어를 의미한다. 또 위젯 매니저는 앱스토어

클라이언트(AppStore Client) 기능도 지원한다.

3.73. 위젯 서명(Widget Signature)

위젯 디지털 서명 [Widgets-DigSig]에서 규정한 서명 파일에 있는 XML 디지털

서명.

3.74. 확장성 HTML(XHTML: eXtensible HyperText Markup Language)

XHTML 은 웹페이지에서 사용되는 HTML 언어로, 널리 사용되고 있는 HTML 의

확장 버전인 XML 마크업 언어이다.

3.75. 확장성 마크업 언어(XML: Extensible Markup Language)

XML 은 기계에서 읽을 수 있는 형태로 되어 있는 암호화된 문서 규정이다.


15 TTAK.OT-10.0323

3.76. XMLHttpRequest (XHR)

XMLHttpRequest(XHR)은 자바스크립트와 같은 웹 브라우저 스크립팅

언어(scripting language)에서 사용할 수 있는 API 이다. 이는 HTTTP 나 HTTPS

요청을 웹 서버에 직접 보내고 스크립트로 서버가 보내는 데이터를 직접 받는데

사용된다.

4. Device API 요구 사항

4.1. Deviceapis 모듈

4.1.1. 요약

이 API 는 공통적인 WAC 기능을 제공한다.

4.1.2. 인터페이스 및 방법 요약

인터페이스 방법

DeviceapisObject

Deviceapis FeatureArray listAvailableFeatures()

FeatureArray listActivatedFeatures()

DeviceAPIError

PendingOperation boolean cancel()

Feature

Param

Synchronisable PendingOperation sync(SuccessCallback success, ErrorCallback error)

SuccessCallback void onsuccess()

ErrorCallback void onerror(DeviceAPIError error)


16 TTAK.OT-10.0323

4.1.3. 서론

이 API 는 모든 기타 WAC 모듈에서 사용되는 기본 정의를 제공한다. 여기에는 성공

및 에러에 대한 일반적인 콜백(callback)인 GenericError 인터페이스와

PendingOperation 이 포함된다. 한, 이 API 는 지원 및 활성화되는 특징 리스트를

가져오기 위한 메커니즘뿐만 아니라 WAC API 를 예시하는 (window.deviceapis)

ECMAScript 체계의 위치도 지정한다.

4.1.4. 인터페이스

가. Deviceapis객체

윈도우 전역 객체(window global object)의 일부로서 deviceapis 인터페이스를

정의한다.

[NoInterfaceObject] interface DeviceapisObject {

readonly attribute Deviceapis deviceapis;

};

Window implements DeviceapisObject;

Deviceapis 인터페이스는 ECMAScript 계층의 윈도우 객체(Window object) 내에서

항상 이용할 수 있다.

나. Deviceapis

WAC 루트(root) API.

[NoInterfaceObject] interface Deviceapis {

FeatureArray listAvailableFeatures();

FeatureArray listActivatedFeatures();

};

이는 Deviceapis 객체 인터페이스에 의해 지정되는 속성으로서 ECMAScript 전역

객체의 일부인 WAC 루트 인터페이스이다.


17 TTAK.OT-10.0323

방법

listAvailableFeatures

웹 런타임(WRT)에서 이용할 수 있는 모든 특징을 가지는 리스트를 반환한다.

서명


WRT 에서 이용 가능한 모든 특징을 가지는 리스트를 제공한다. 위젯(widget)

구성 문서(config.xml)에서 요청되지 않는 특징에 대하여, 요구되는 속성 및 특징

인스턴스의 파라미터는 반드시 널(null)이어야 한다. 위젯(widget) 구성 문성에서

요청된 특징에 대해서는 요구되는 속성 및 파라미터가 반드시 위젯 구성

문서에서 제공되는 값이어야 한다.

반환 값(Return value)

이용 가능한 모든 특징을 가지는 열 또는 에러 발생 시 널(null).

코드 예

listActivatedFeatures

웹 런타임(WRT)에서 활성화 되는 모든 특징을 가지는 리스트를 반환한다.

서명


이 방법은 반드시 WRT 의 위젯에 대하여 활성화된 모든 특징을 가지는 리스트를

제공해야 한다. 모든 특징에 대하여, 요구되는 params 속성은 반드시 위젯

구성문서에서 제공되는 값을 포함해야 한다.


활성화된 모든 특징을 가지는 열 또는 에러 발생 시 null.

var features = deviceapis.listAvailableFeatures();

for (var i=0; i<features.length; i++) {

alert("The Feature " + features[i].uri + " is supported");

}


18 TTAK.OT-10.0323

코드 예

다. DeviceAPIError

일반적 에러 인터페이스

[NoInterfaceObject] interface DeviceAPIError {

readonly attribute short code;

readonly attribute DOMString message;

const short UNKNOWN_ERR = 0;

const short INDEX_SIZE_ERR = 1;

const short DOMSTRING_SIZE_ERR = 2;

const short HIERARCHY_REQUEST_ERR = 3;

const short WRONG_DOCUMENT_ERR = 4;

const short INVALID_CHARACTER_ERR = 5;

const short NO_DATA_ALLOWED_ERR = 6;

const short NO_MODIFICATION_ALLOWED_ERR = 7;

const short NOT_FOUND_ERR = 8;

const short NOT_SUPPORTED_ERR = 9;

const short INUSE_ATTRIBUTE_ERR = 10;

const short INVALID_STATE_ERR = 11;

const short SYNTAX_ERR = 12;

const short INVALID_MODIFICATION_ERR = 13;

const short NAMESPACE_ERR = 14;

const short INVALID_ACCESS_ERR = 15;

const short VALIDATION_ERR = 16;

const short TYPE_MISMATCH_ERR = 17;

const short SECURITY_ERR = 18;

const short NETWORK_ERR = 19;

const short ABORT_ERR = 20;

const short TIMEOUT_ERR = 21;

const short INVALID_VALUES_ERR = 22;

};

var features = deviceapis.listActivatedFeatures();

for (var i=0; i<features.length; i++) {

alert("The Feature " + features[i].uri + " has been

activated");

}


19 TTAK.OT-10.0323

본 인터페이스는 에러를 동시에 띄우거나 비동기 방법의 에러 콜백(error

callbacks)에서 이를 반환하기 위한 API 에 의해 사용될 것이다.

본 인터페이스에서 정의되는 에러 코드는 몇 가지 추가된 DOM level3 명세서에

의해 정의되는 것이다.

API 는 [Supplemental] WebIDL 키워드 사용 전체에서 모듈 특이성을 가지는 에러

코드 리스트를 확대할 수 있다. API 특이적 에러 숫자는 미래의 DOM 에러

코드와의 충돌을 피하기 위해 100 부터 시작한다.

코드 예

상수

short UNKNOWN_ERR

일반적인 에러 코드.

short INDEX_SIZE_ERR

short DOMSTRING_SIZE_ERR

short HIERARCHY_REQUEST_ERR

short WRONG_DOCUMENT_ERR

short INVALID_CHARACTER_ERR

short NO_DATA_ALLOWED_ERR

short NO_MODIFICATION_ALLOWED_ERR

short NOT_FOUND_ERR

short NOT_SUPPORTED_ERR

실행이 요청되는 객체 타입 또는 동작(operation)을 지원하지 않는 경우.

deviceapis.filesystem.resolve(

function(dir) { // do something },

function(e) {

// handling error defined in deviceapis

if (e.code == e.NOT_SUPPORTED_ERR) alert("not supported");

// handling error defined in appropriate module (e.g. filesystem)

if (e.code == e.IO_ERR) alert("i/o error");

}, 'images', 'r'

);


20 TTAK.OT-10.0323

short INUSE_ATTRIBUTE_ERR

short INVALID_STATE_ERR

short SYNTAX_ERR

short INVALID_MODIFICATION_ERR

short NAMESPACE_ERR

short INVALID_ACCESS_ERR

short VALIDATION_ERR

short TYPE_MISMATCH_ERR

객체 타입이 객체와 관련하여 기대되는 파라미터의 타입과 호환되지 않는 경우.

short SECURITY_ERR

보안 위험 또는 사용자 대리인 보안 정책 위반을 제시하는 방법으로 동작이나

데이터 접근을 수행하려는 시도가 이루어지는 경우.

short NETWORK_ERR

동시 요청에서 네트워크 에러가 발생한 경우.

short ABORT_ERR

short TIMEOUT_ERR

동작이 시간 초과되고 완료되지 못 한 경우.

short INVALID_VALUES_ERR

어떤 객체의 내용이 유효한 값을 포함하지 않는 경우.


21 TTAK.OT-10.0323

속성

읽기 전용 짧은 코드

16 비트 에러 코드.

이 속성은 읽기 전용이다.

읽기 전용 DOMString 메시지

에러 메시지

마주치게 되는 에러의 상세사항을 설명한다.

주) 이 속성은 주로 최종 사용자 보다는 개발자에게 유용하게 의도되었기 때문에 사용자 인터페이스에서 직접 사용하고자 의도된 것이 아니다.


라. PendingOperation

비동기 콜의 대기 동작(pending operation)을 대표하는 객체

[NoInterfaceObject] interface PendingOperation {

boolean cancel();

};

동작 취소를 제공하기 위하여 비동기 동작에 의해 반환되는 인터페이스


22 TTAK.OT-10.0323

코드 예

var pendingOp = null;

// SMS sending example

var msg = deviceapis.messaging.createMessage(Messaging.TYPE_SMS);

msg.body = "I will arrive in 10 minutes";

msg.to = ["+34666666666"];

// Define the success callback

function messageSent() {

alert("The SMS has been sent");

pendingOp = null;

}

// Define the error callback

function messageFailed(error) {

alert("The SMS could not be sent " + error.message);

pendingOp = null;

}

// To be executed if, for instance, the user presses a cancel button in the user

interface

function cancel() {

if (pendingOp != null) {

if (pendingOp.cancel()) {

alert("The message sending has been canceled");

} else {

alert("The operation cannot be canceled");

}

} else {

alert("The operation cannot be canceled");

}

}

pendingOp = deviceapis.messaging.send(msg, messageSent, messageFailed);


23 TTAK.OT-10.0323

방법

cancel

근원적인 비동기 동작을 취소하기 위한 호출.

서명

boolean cancel();

이 호출은 항상 성공적이며, 예를 들어 대기 동작이 취소되거나 콜백(callbacks)

중 하나가 호출된다.

취소가 성공적인 경우 true 취소된 대기 작업에 의해 어떤 콜백도 호출되지 않을

것이다.


대기 작업이 이미 끝났거나 근원적인 실행의 기술적인 한계 때문에 취소가

성공할 수 없기 때문에 취소가 성공하지 않은 경우 false. 결과적으로, 대기

작업은 완료되고, 성공이냐 실패냐에 따라 이 방법이 반환된 후 적절한 콜백이

호출될 것이다.

마. 특징

어떤 특징에 대한 모든 정보를 제공한다.

[NoInterfaceObject] interface Feature {

attribute DOMString uri;

attribute boolean required;

attribute ParamArray params;

};

본 인터페이스는 어떤 특징에 대한 상세 사항을 제공하는 데 사용된다.

속성

DOMString uri

URI 를 특징으로 함. 이것은 그 속성의 고유한 식별자이다.


24 TTAK.OT-10.0323

boolean required

필수 플래그(flag)

이 속성은 그 특징이 위젯 구성 문서(config.xml)에서 필수로 태그된 경우 진실로

설정된다.

ParamArray params

Params 를 특징으로 함.

이 속성은 그 특징이 위젯 구성 문서(config.xml)에 포함된 모든 파라미터를

가지는 열을 포함한다.

Param

한 가지 특징으로 연결되는 파라미터를 나타냄.

[NoInterfaceObject] interface Param {

attribute DOMString name;

attribute DOMString value;

};

속성

DOMString name

파라미터 이름

DOMString value

파라미터 값

바. 동기화 가능(Synchronisable)

본 인터페이스는 데이터 동기화가 필요한 다른 인터페이스에 의해 실행될 것이다.

interface Synchronisable {

readonly attribute boolean isInSync;

PendingOperation sync(in SuccessCallback success,

in optional ErrorCallback error)


25 TTAK.OT-10.0323

raises(DeviceAPIError);

};

본 인터페이스는 그 인터페이스의 동기화 상태를 되돌리는 속성과 인터페이스

데이터를 동기화하도록 요청하는 방법을 제공한다.

속성

읽기전용 boolean isInSync

인터페이스 동기화 상태.

이 속성은 그 인터페이스가 동기화되었는지 여부를 기술한다. 객체가 동기화된

경우 true 이고 객체가 동기화되지 않은 경우 false 이다.

디폴트 값은 false 이다.


방법

sync

인터페이스 데이터 동기화를 요청함.

서명

PendingOperation sync(in SuccessCallback success, in optional ErrorCallback

error);

이 방법을 호출하는 경우, 그 실행은 반드시 모든 인터페이스 속성을 갱신하여

이들 모두를 최신 상태로 만들어야 한다.

입력 속성 중 어떤 것이 잘못된 경우, 그 방법은 반드시 동시에

TYPE_MISMATCH_ERR 를 띄워야 한다.

실행이 요청된 동작을 지원하지 않는 경우, NOT_SUPPORTED_ERR 코드를

가지는 DeviceAPIError 와 함께 errorCallback 을 호출해야 한다.

successCallback 이 예를 들어 널(null)이나 미정 등 유효한 값을 포함하지 않는

경우, INVALID_VALUES_ERR 코드를 가지는 DeviceAPIError 를 errorCallback 에

복구해야 한다.


26 TTAK.OT-10.0323

객체가 이미 현재화된 경우(예, 동기화) 그 실행은 반드시 isInSync 속성을

true 로 설정하고 더 이상의 조치 없이 successCallback 을 호출해야 한다.

인터페이스가 현재화되지 않은 경우 (예를 들어 동기화되지 않은 경우), 그

실행은 반드시 데이터 가져오기를 시도해야 한다. 데이터를 성공적으로 가져온

경우, isInSync 속성이 true 로 설정되고 successCallback 이 호출된다.

인터페이스 속성 갱신 도중 에러가 발생한 경우, 다음 에러 코드와 함께

errorCallback 이 호출된다:

• TIMEOUT_ERR: 시간 초과 때문에 동작이 완료될 수 없었던 경우.

• NETWORK_ERR: 데이터가 네트워크 에러 때문에 동기화될 수 없는 경우.

위에서 지정한 것처럼 errorCallback 이 호출되어야 하는 모든 경우에, 개발자가

유효한 ErrorCallback(e.g. 널(null) 또는 미정) 지나치지 않은 경우, 조치가

필요하지 않다 (i.e. 그 에러는 개발자에게 통지되지 않음).

파라미터

• 성공

o 선택가능: 아니오.

o 타입: SuccessCallback.

o 설명:

• error

o 선택가능: 예.

o 타입: ErrorCallback.

o 설명:

예외

• DeviceAPIError:

사. SuccessCallback

일반적인 성공 콜백 인터페이스.

[Callback=FunctionOnly, NoInterfaceObject] interface SuccessCallback {

void onsuccess();

};

이 콜백은 성공 콜백 시 어떤 반환 값도 요구하지 않는 기능에 의해 사용될 수

있다.


27 TTAK.OT-10.0323

방법

onsuccess

비동기 콜을 성공적으로 완료할 때 불러오는 방법

서명

void onsuccess();

코드 예

아. ErrorCallback

Generic error callback interface.

[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {

void onerror(in DeviceAPIError error);

};


var msg =

deviceapis.messaging.createMessage(deviceapis.messaging.TYPE_SMS);


msg.to = ["+34666666666"];




}




}

// Send request

deviceapis.messaging.sendMessage(msg, messageSent, messageFailed);


28 TTAK.OT-10.0323

이 콜백은 에러 콜백 시 에러를 입력 파라미터로 요구하는 기능에 의해 사용될 수

있다.

방법

onerror

에러 발생 시 호출되는 방법.

서명


파라미터

• 에러


o 타입: DeviceAPIError.

o 설명: 상승되는 에러

코드 예


var msg = deviceapis.messaging.createMessage(Messaging.TYPE_SMS); msg.body = "I will arrive in 10 minutes";

msg.to = ["+34666666666"];



alert("The SMS has been sent"); }

// Define the error callback function messageFailed(error) {


}

// Send request

deviceapis.messaging.sendMessage(msg, messageSent, messageFailed);


29 TTAK.OT-10.0323

4.1.5. 타입 정의

StringArray

DOMstings 열.

typedef sequence<DOMString> StringArray;

UnsignedShortArray

짧은 값 열

typedef sequence<short> UnsignedShortArray;

ShortArray

짧은 값 열

typedef sequence<short> ShortArray;

FeatureArray

IRIs 특징 열.

typedef sequence<Feature> FeatureArray;

ParamArray

특징 파라미터 열.

typedef sequence<Param> ParamArray;

일자

날짜 데이터 타입.

typedef unsigned long long Date;


30 TTAK.OT-10.0323

4.1.6. 특징

다음 특징:

• http://wacapps.net/api/deviceapis

또는 그 특징아래 속성 중 어떤 것이 성공적으로 요청되면, Deviceapis

인터페이스가 예시되고, 그 결과로 나타나는 객체는 전세계 namespace 에

window.deviceapis 로 나타난다.

이것은 widget config.xml 에서 사용하기 위하여 API 속성을 선언하는 데 사용된다.

각 URL 에 대하여 포함된 기능 리스트가 제공된다.

http://wacapps.net/api/deviceapis

장치 API 기초 모듈에 대한 접근.

4.1.7. Full WebIDL

module deviceapis {









};





};





31 TTAK.OT-10.0323
























};


boolean cancel();

};





};




};


32 TTAK.OT-10.0323






};


void onsuccess();

};



};

};


33 TTAK.OT-10.0323

4.2. 가속도계 모듈

4.2.1. 요약

본 표준은 Accelerometer API 를 기술한다. 본 API 는 장치 가속도계 정보에 대한

접근방법을 제공한다. 가속도계는 장치의 속도 크기와 방향을 변경하는 속도를 측정하는

센서이다. 장치 가속도계는 3 개의 장치 축에 따라 기저 상태 대비 가속도를 측정한다.

본 API 는 개발자가 현재 가속도 값을 검색하고, 가속도의 변화가 가속도계에 의해

측정될 때 통지할 수 있도록 한다.

4.2.2. 인터페이스 및 방법 요약

인터페이스 방법

DeviceapisAccelerometer

Accelerometer PendingOperation

getCurrentAcceleration(AccelerationSuccessCallback

successCallback, ErrorCallback errorCallback)

long watchAcceleration(AccelerationSuccessCallback

successCallback, ErrorCallback errorCallback,

AccelerationOptions options)

void clearWatch(long watchId)

AccelerationOptions

Acceleration

AccelerationSuccessCallback void onsuccess(Acceleration acceleration)

4.2.3. 서론

다음 축은 장치 가속도를 감지하는 데 사용된다:

� x 축은 화면 평면상에 있으며 화면 오른쪽으로 갈수록 증가한다.

� y 축은 화면 평면상에 있으며 화면 위쪽으로 갈수록 증가한다.

� z 축은 화면 평면에 직각이며 화면 평면에서 멀어질수록 증가한다.

이 축은 화면의 기준/디폴트 방향성과 관련하여 정해진다.


34 TTAK.OT-10.0323

따라서 각 축에 대한 가속도 값은 그 축의 가속도 비율에 의해 정해지며 m/s2 로

측정된다 (국제 단위 시스템). 정상 기저 상태에서, 가속도계는 모든 축에서 0 m/s2 로

읽는다. 장치를 자유낙하 시키고 장치가 다른 움직임 없이 뒷면이 땅에 닿게 자유낙하

한다고 가정하면 중력으로 인한 가속도를 측정할 수 있는데, 이 때 x,y 축은 0

m/s2 이고 z 축은 -9.8 m/s2 로 측정한다.


가. DeviceapisAccelerometer

Deviceapis 대상에서 예시되는 것을 정의한다.

[NoInterfaceObject] interface DeviceapisAccelerometer {

readonly attribute Accelerometer accelerometer;

};

Deviceapis implements DeviceapisAccelerometer;

가속도계 모듈의 기능 접근을 허용하는 deviceapis.accelerometer 대상이 있을 것이다.

나. 가속도계(Accelerometer)

가속도계 센서 값에 대한 접근.

[NoInterfaceObject] interface Accelerometer {

const float EARTH_GRAVITY = -9.8;

PendingOperation getCurrentAcceleration(in AccelerationSuccessCallback

successCallback, in optional ErrorCallback errorCallback)

raises (DeviceAPIError);

long watchAcceleration(in AccelerationSuccessCallback successCallback,

in optional ErrorCallback errorCallback,

in optional AccelerationOptions options)


void clearWatch(in long watchId)


};

deviceapis.accelerometer 인터페이스를 통하여 모듈 기능에 대한 접근을 제공.


35 TTAK.OT-10.0323

코드 예

상수

지구_중력값

지구 중력

방법

getCurrentAcceleration

장치 가속도를 요청

서명


successCallback, 선택적으로 ErrorCallback errorCallback);

입력 파라미터 중 어떤 것이 그 파라미터에 대하여 예상되는 타입과 맞지 않는

경우 TYPE_MISMATCH_ERR 코드가 있는 DeviceAPIError 를 반드시 동시에

띄워야 한다.

successCallback 이 기능을 가지지 않는 경우 (예를 들어 null 함유)

DeviceAPIError 및 코드 INVALID_VALUES_ER 와 함께 errorCallback 이 반드시

시작되어야 한다.

이 특징이 지원되지 않는 경우, 코드 NOT_SUPPORTED_ERR 와 함께

DeviceAPIError 는 반드시 errorCallback 을 반환해야 한다.

이 기능이 허용되지 않는 경우, 반드시 SECURITY_ERR 코드를 가지는

DeviceAPIError 와 함께 errorCallback 을 불러와야 한다.

다른 오류 사례에서, UNKNOWN_ERR 코드를 가지는 DeviceAPIError 는 반드시

errorCallback 으로 돌아와야 한다.

// One-shot request deviceapis.accelerometer.getCurrentAcceleration(function(acceleration) {

if (acceleration.xAxis == 0)

alert("The device has no acceleration in the xAxis"); else

alert("The device has acceleration in the xAxis " + acceleration.xAxis);

});


36 TTAK.OT-10.0323

errorCallback 이 유효한 기능 (예, 무효(null))을 함유하지 않는다면,

errorCallback 으로 돌아와야 하는 모든 오류의 경우 (위 참조) 실행이 반드시

조용히 실패하고 더 이상의 조치가 필요하지 않다 (예, 그 오류는 개발자에게

통지되지 않음).

동작이 성공적으로 완료되고 세 축의 가속도 값이 얻어진 경우, 반드시

successCallback 을 불러와야 하며 현재 장치 가속도에 대한 데이터를 포함하는

Acceleration 대상을 받게 된다. 가속도 값을 성공적으로 구할 수 없는 경우,

위에서 설명한 것처럼 그 이유를 반영하는 새로운 DeviceAPIError 대상과 함께

반드시 (있다면) errorCallback 을 불러와야 한다.

파라미터

• successCallback


o 타입: AccelerationSuccessCallback.

o 설명: 가속도값 구하기에 성공한 경우 불러옴.

• errorCallback



o 설명: 가속도값을 구할 수 없는 경우 불러옴


동작 취소를 위한 PendingOperation

예외

• DeviceAPIError:

입력 파라미터가 그 파라미터에 대하여 기대되는 타입과 맞지 않는 경우

TYPE_MISMATCH_ERR 라는 오류 코드를 가짐.

코드 예

deviceapis.accelerometer.getCurrentAcceleration(function(acceleration) {

if (acceleration.xAxis == 0)

alert("The device is not moving in the xAxis");

else

alert("The device is moving in the xAxis");

});


37 TTAK.OT-10.0323

다. watchAcceleration

장치 가속도 변화에 대한 통지를 받기로 약속.

서명

long watchAcceleration(in AccelerationSuccessCallback successCallback, in

optional ErrorCallback errorCallback, in optional AccelerationOptions options);



띄워야 한다.

successCallbac 에 기능이 없는 경우 (예를 들어 null 함유) DeviceAPIError 및

코드 INVALID_VALUES_ER 와 함께 errorCallback 이 반드시 시작되어야 한다.

이 특징이 지원되지 않는 경우, 코드 NOT_SUPPORTED_ERR 와 함께

DeviceAPIError 는 반드시 errorCallback 을 반환해야 한다.

이 기능이 허용되지 않는 경우, 반드시 코드 SECURITY_ERR 를 가지는

DeviceAPIError 와 함께 errorCallback 을 불러와야 한다.


errorCallback 으로 돌아와야 한다.


errorCallback 으로 돌아와야 하는 모든 오류의 경우 (위 참조) 실행이 반드시



실행되면, 그 실행은 반드시 즉시 시계 동작을 확인하는 가입

식별자(subscription identifier)를 반환해야 한다. 식별자를 반환한 후, 시계

동작이 비동기로 시작된다. 현재 장치 가속도 측정을 얻기 위하여 반드시 실행을

시도해야 한다. 그 시도가 성공하면 현재 가속도 값과 함께 successCallback 을

반드시 불러와야 하고, 시도가 실패한 경우 위에서 설명한 것과 같이 해당 오류

코드와 함께 (만약 있다면) errorCallback 을 불러와야 한다.

가속도 값 구하기에 최초로 성공한 후, 시계 동작이 지속되어 장치 가속도 값을

모니터링하고, 가속도가 바뀔 때마다 적절한 콜백을 불러오게 된다. 시계

동작은 해당 서명 식별자와 함께 clearWatch() 방법을 불러올 때까지 반드시

지속되어야 한다.


38 TTAK.OT-10.0323

선택 파라미터를 건너뛰고 minNotificationInterval 속성에 유효값을 가지는 경우,

적어도 minNotificationInterval 파라미터와 동일한 시간이 발생할 때까지

successCallback 을 불러와서는 안된다. 선택 파라미터가 유효 값은 가지지

않거나 미지정 또는 널(null)인 경우, 실행은 반드시 그 내용을 무시하고

minNotificationInterval 없이 진행해야 한다.

파라미터

• successCallback


o 타입: AccelerationSuccessCallback.

o 설명: 가속도 구하기에 성공한 경우 불러옴.

• errorCallback



o 설명: 가속도 값을 구할 수 없는 경우 불러옴.

• 옵션


o 타입: AccelerationOptions.

o 설명: 애플리케이션을 통지하기 위하여 적용되는 조건.


시계 등록을 제거하기 위해 사용되는 긴 식별자.

예외

• DeviceAPIError:


TYPE_MISMATCH_ERR 라는 오류 코드를 가짐.


39 TTAK.OT-10.0323

코드 예

// Last acceleration value retrieved

var x = 0;

// Receives acceleration changes

function watcher(acceleration){

alert("The acceleration in x Axis changed in " +

acceleration.xAxis - x + " m/s2");

x = acceleration.xAxis;

}

// registers to be notified when acceleration changes

// (minimum time between notifications is 10 secs)

deviceapis.accelerometer.watchAcceleration(watcher,

function(error){alert("An error occurred");},

{minNotificationInterval:10000} ) ;


40 TTAK.OT-10.0323

라. clearWatch

가속도 시계 동작 등록을 취소함

서명

void clearWatch(in long watchId);

watchId argument 가 유효하고 이미 존재하는 등록에 해당되는 경우, 반드시 그

시계 프로세스를 즉시 중단하고 더 이상의 callbacks 을 불러오지 않아야 한다.

watchId argument 가 유효하지 않고 유효 등록에 해당되지 않는 경우, 이

방법은 더 이상의 조치 없이 반환되어야 한다.

파라미터

• watchId

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: long. o 설명: 서명 식별자(Subscription Identifier)

예외

• DeviceAPIError:


TYPE_MISMATCH_ERR 라는 오류 코드가 있음

코드 예

// Last acceleration value retrieved var x = 0; var id = 0; // watcher identifier // Receives acceleration changes function watcher(acceleration){ alert("The acceleration in x Axis changed in " + acceleration.xAxis - x + " m/s2"); x = acceleration.xAxis; } // Cancel the watch operation function cancelWatch() { deviceapis.accelerometer.clearWatch(id); } // registers to be notified when acceleration changes // (minimum time between notifications is 10 secs) id = deviceapis.accelerometer.watchAcceleration(watcher, function(error){alert("An error occurred");}, {minNotificationInterval:10000} );


41 TTAK.OT-10.0323

마. AccelerationOptions

가속도 등록에 대한 옵션을 지정함.

[Callback, NoInterfaceObject] interface AccelerationOptions {

attribute long minNotificationInterval;

};

본 인터페이스는 successCallback 을 불러오는 조건을 결정하기 위한

watchAcceleration() 방법 불러오기에 사용된다.

코드 예

속성

long minNotificationInterval

통지간 시간이 최소

watchAcceleration 방법 요청에 반응하여 2 개의 successCallback 불러오기

사이에 발생해야 하는 최단 시간 (1000 분의 1 초로 표현)을 지정한다.

바. 가속도

장치 가속도

[NoInterfaceObject] interface Acceleration {

readonly attribute float xAxis;

readonly attribute float yAxis;

readonly attribute float zAxis;

};

// Receives acceleration changes

function watcher(acceleration){

alert("The acceleration has changed");

}

// registers to be notified when acceleration changes

// (minimum time between notifications is 10 secs)

deviceapis.accelerometer.watchAcceleration(watcher,

function(error){alert("An error occurred");},

{minNotificationInterval:10000} );


42 TTAK.OT-10.0323

본 인터페이스는 3 가지 축의 장치 가속도 값을 반환하는 데 사용된다. 이는

watchAcceleration()와 getCurrentAcceleration() 방법의 successCallbacks 에

사용된다.

코드 예

속성

readonly float xAxis

m/s2 로 측정되는 x-축 가속도.

x-축을 따라 측정되는 가속도. 가속도 값이 양수이면 장치가 x-축이 증가하는

방향을 따라 가속되고 있음을 나타내며 (예를 들어 장치가 평면 위에 있고

사용자가 화면의 “바닥”에 서있는 경우 (y 축의 최저점)) 장치의 가속도는

사용자의 위치에 대비하여 오른쪽 방향이다. 음수의 가속도 값은 x-축의

감소하는 방향을 따라갈 때 발생한다 (예를 들어 장치가 왼쪽으로 가속).


readonly float yAxis

m/s2 로 측정되는 y-축 가속도.

y-축을 따라 측정되는 가속도. 가속도 값이 양수이면 장치가 y-축이 증가하는

방향을 따라 가속되고 있음을 나타내며 (예를 들어 장치가 평면 위에 있고

사용자가 화면의 “바닥”에 서있는 경우 (y 축의 최저점)) 장치의 가속도는

사용자로부터 멀어지는 방향이다 (예를 들어 장치의 바닥에서 위로 가는 방향).

음수의 가속도 값은 y-축이 감소하는 방향으로 이동할 때 발생한다 (예를 들어

장치의 윗면으로부터 아래쪽 방향으로 사용자를 향하는 장치의 가속도).

이 특성은 읽기 전용이다.

deviceapis.accelerometer(function(acceleration) {

alert("Acceleration in x,y,z axis is: " +

acceleration.xAxis + "," +

acceleration.yAxis + "," +

acceleration.zAxis);

});


43 TTAK.OT-10.0323

readonly float zAxis

m/s2 로 측정되는 z-축 가속도.

z-축을 따라 측정되는 가속도. 가속도가 양수인 경우 장치가 z-축이 증가하는

방향을 따라 가속되고 있음을 나타낸다 (예를 들어 장치가 평면에 있고, 화면이

위를 향해 서있는 경우, 장치는 표면 위로 움직이며 가속된다). 음수의 가속도

값은 z-축의 감소하는 방향을 따라갈 때 발생한다 (예를 들어 장치가 표면을

뚫고 아래로 가속).

이 특성은 읽기 전용이다.

사. AccelerationSuccessCallback

가속도 특이적 성공 콜백(success callback)

[Callback=FunctionOnly, NoInterfaceObject] interface

AccelerationSuccessCallback

{

void onsuccess(in Acceleration acceleration);

};

이 콜백 인터페이스는 입력 인수로서 가속도 대상을 취하는 기능을 가지는 success

callback 을 지정한다. 이는 getCurrentAcceleration() 또는 watchAcceleration()

등의 비동기 동작에 사용된다.

방법

onsuccess

비동기 콜을 성공적으로 완료할 때 불러오는 방법

서명


파라미터

• 가속도


o 타입: 가속도

o 설명: 장치 가속도


44 TTAK.OT-10.0323

4.2.5. 특징

다음 특징:

• http://wacapps.net/api/accelerometer

또는 그 특징 아래 속성 중 어떤 것이 성공적으로 요청되면,

Accelerometer 인터페이스는 예를 들어 설명되고 그 결과로 대상은 전세계 네임

스페이스(name space)에 deviceapis.accelerometer 로 나타난다.



http://wacapps.net/api/accelerometer

가속도계 센서 정보에 접근. 본 특징은 본 모듈에서 기술된 인터페이스, 방법 및

속성 중 어떤 것과 연관된다.

4.2.6. Full WebIDL

module accelerometer

{



};





successCallback,

in optional ErrorCallback

errorCallback)







45 TTAK.OT-10.0323



};



};





};

[Callback=FunctionOnly, NoInterfaceObject] interface AccelerationSuccessCallback {


};

};


46 TTAK.OT-10.0323

4.3. 오리엔테이션(orientation) 모듈

4.3.1. 요약

오리엔테이션(orientation) API

4.3.2. 인터페이스 및 메소드 요약

인터페이스 메소드

DeviceapisOrientation

Orientation PendingOperation

getCurrentOrientation(OrientationSuccessCallback


long watchOrientation(OrientationSuccessCallback


OrientationOptions options)

void clearWatch(long watchId)

OrientationOptions

Rotation

OrientationSuccessCallback void onsuccess(Rotation rotation)

4.3.3. 서론

본 API 는 디바이스 오리엔테이션 정보에 대한 접근을 제공한다. 오리엔테이션

센서는 3 개의 축을 따라 기준 틀과 비교하여 디바이스의 회전에 대한 정보를

제공하는 센서이다디바이스 축은 x, y, z 로 표지되며 보통 가속도계 모듈에서와

같다:

� x 축은 화면 평면상에 있으며 화면 오른쪽으로 갈수록 증가한다.

� y 축은 화면 평면상에 있으며 화면 위쪽으로 갈수록 증가한다.

� z 축은 화면 평면에 직각이며 화면 평면에서 멀어질수록 증가한다.

회전 정보는 3 개의 서로 다른 각도로 기술된다:

알파 (azimuth)는 z-축(위-아래 축) 주변의 디바이스 회전 각도이다디바이스가 자침

북쪽을 가리키는 경우 ‘0’으로 읽히는 일이 발생한다.양의 회전 각도는 자침이

가리키는 북쪽으로부터 시계반대방향으로 편향된 정도로 측정하며 0 에서 360 도

사이의 값을 취할 수 있다.

베타 (pitch)는 x-축 주변(좌우 방향 축)의 디바이스 회전 각도이다디바이스가 위를

향한 채 평면 위에 있는 경우 ‘0’으로 읽힌다양의 회전 각도는 시계반대방향


47 TTAK.OT-10.0323

편향으로 측정되고, 음의 회전 각도는 시계방향 편향으로 측정된다 각도는

도(degree)로 측정되며 -180 에서 180 도 사이의 값을 취할 수 있다.

감마 (roll)은 y-축 주변(상면-바닥 축)의 회전 각도이다. 디바이스가 위를 향한 채

평면 위에 있는 경우 0 으로 읽힌다. 양의 회전 각도는 시계 반대 방향 편향으로

측정되고, 음의 회전 각도는 시계방향 편향으로 측정된 다각도는 도(degree)로

측정되며 -90 에서 90 도 사이의 값을 취할 수 있다.

각도는 항상 회전축의 양수 측에서 보았을 때 시계 반대 방향으로 측정된다. 또한

회전이 서로 호환되지 않는 경우, 알파, 베타, 감마가 항상 같은 순서로 적용된다.

예를 들어, 화면이 위로 향하고, 화면 윗부분이 북쪽을 가리키며 평면상에 있는

디바이스는 알팦, 베타 감마가 ‘0’으로 같다그 디바이스가 z 축을 따라 회전하여

화면의 위쪽이 서쪽을 가리키면 베타와 감마는 그대로 남아 있지만 알파 값은

90 도로 변한다.

디바이스를 사용자가 손으로 잡고 수직 위치에, 뒷부분이 남쪽을 가리키고, 화면

윗부분이 오른쪽을 가리키는 경우, 오리엔테이션 값은 다음과 같다. 알파(alpha)=90,

베타(beta)=0, 감마(gamma)=90. 화면 위부분이 오른쪽 대신에 위쪽을 가리키는

경우, 그 값은 다음과 같다알파=180, 베타=90, 감마=0.

본 API 는 개발자가 현재 오리엔테이션 값을 구하고, 센서가 오리엔테이션의 변화를

측정했을 때 통지할 수 있도록 등록한다.


가. DeviceapisOrientation

deviceapis 객체에서 예시되는 것을 정의한다.

[NoInterfaceObject] interface DeviceapisOrientation {

readonly attribute Orientation orientation;

};

Deviceapis implements DeviceapisOrientation;

오리엔테이션 모듈의 기능 접근을 허용하는 deviceapis.orientation 객체가 있을

것이다.


48 TTAK.OT-10.0323

나. 오리엔테이션

수화자(listener) 기능뿐 아니라 오리엔테이션 센서 값에 대한 접근을 제공한다.

[NoInterfaceObject] interface Orientation {

PendingOperation getCurrentOrientation(in OrientationSuccessCallback



long watchOrientation(in OrientationSuccessCallback successCallback,


in optional OrientationOptions options)




};

각 축에 대한 값은 그 주변으로 측정되는 회전으로 결정되며, 도(degree)로

표시한다(International System of Units).

오리엔테이션 정보는 비동기 호출(asynchronous call)을 통해 구한다.

코드 예

Methods

getCurrentOrientation

var neworientation = 'flat'; var oldorientation = 'flat'; function orientationChange(rotation) { azimuth = rotation.alpha; pitch = rotation.beta; roll = rotation.gamma; if (pitch < -45) if(pitch > -135) neworientation = 'bottom'; else if (pitch > 45) if (pitch < 135) neworientation = 'top'; else if (roll > 45) neworientation = 'right'; else if (roll -45) neworientation = 'left'; else neworientation = 'flat'; if (neworientation != oldorientation) { alert('Your orientation has changed'); oldorientation = neworientation; } function genericError(e) { alert("Error: "+e.message); } var myOptions = {minNotificationInterval:10000}; //10 seconds deviceapis.orientation.watchOrientation(orientationChange, genericError,

myOptions);


49 TTAK.OT-10.0323

디바이스 오리엔테이션을 요청.

서명


successCallback, in optional ErrorCallback errorCallback);


경우 TYPE_MISMATCH_ERR 코드가 있는 DeviceAPIError 예외를 발생시킨다.

이 기능을 가지지 않는 경우 (예를 들어 null 함유) 반드시 DeviceAPIError 및

코드 INVALID_VALUES_ER 와 함께 errorCallback 이 시작되어야 한다.

이 feature 가 지원되지 않는 경우, 코드 NOT_SUPPORTED_ERR 와 함께

DeviceAPIError 는 반드시 errorCallback 을 리턴해야 한다.


DeviceAPIError 와 함께 errorCallback 을 호출해야 한다.


errorCallback 으로 리턴해야 한다.

errorCallback 이 유효한 기능 (예, null))을 함유하지 않는다면, errorCallback 으로

리턴해야 하는 모든 오류의 경우 (위 참조) 구현(implementation)은 반드시



동작이 성공적으로 완료되고 3 개의 축 주변 회전 값을 구한 경우, 현재

디바이스 오리엔테이션을 포함하는 새로운 Rotation 객체와 함께

successCallback 을 호출해야 한다. 회전 값을 성공적으로 구할 수 없는 경우,

위에서 설명한 것처럼 그 이유를 반영하는 새로운 DeviceAPIError 객체 대상과

함께 (만약 있다면) 반드시 errorCallback 을 호출해야 한다.


50 TTAK.OT-10.0323

파라미터

successCallback


o 타입: OrientationSuccessCallback.

o 설명: To be invoked in case of successful retrieval of the

orientation.

• errorCallback



o 설명: 오리엔테이션 값을 구할 수 없는 경우 호출됨.

리턴 값(Return value)

동작 취소를 위한 PendingOperation

예외

• DeviceAPIError:

입력 파라미터 가 그 파라미터에 대하여 기대되는 타입과 맞지 않는 경우

TYPE_MISMATCH_ERR 라는 오류 코드가 있음.

코드 예

watchOrientation

디바이스 오리엔테이션 변화에 대한 통지를 받기 위해 등록.

서명

long watchOrientation(in OrientationSuccessCallback successCallback, in

optional ErrorCallback errorCallback, in optional OrientationOptions options);

// One-shot request

function showOrientationInfo(rotation)

{

alert("Device orientation " + rotation.alpha + "," +

rotation.beta + "," + rotation.gamma);

}

var pOp = deviceapis.orientation.getCurrentOrientation(showOrientationInfo);


51 TTAK.OT-10.0323



이 기능을 가지지 않는 경우 (예를 들어 null 함유) 반드시 DeviceAPIError 및

코드 INVALID_VALUES_ER 와 함께 errorCallback 이 시작되어야 한다.

이 feature 가 지원되지 않는 경우, 코드 NOT_SUPPORTED_ERR 와 함께

DeviceAPIError 는 반드시 errorCallback 을 리턴해야 한다.


DeviceAPIError 와 함께 errorCallback 을 호출해야 한다.


errorCallback 으로 리턴해야 한다.


리턴해야 하는 모든 오류의 경우 (위 참조) 구현은 반드시 조용히 실패하고 더

이상의 조치가 필요하지 않다 (예, 그 오류는 개발자에게 통지되지 않음).

실행되면, 이 메소드는 반드시 즉시 watch operation 을 확인하는 등록

식별자(subscription identifier)를 리턴해야 한다. 식별자를 리턴한 후, watch

operation 이 비동기로 시작된다현재 디바이스 오리엔테이션 측정값을 얻기

위하여 반드시 implementation 을 시도해야 한다. 그 시도가 성공하면 현재

가속도 값과 함께 successCallback 을 반드시 불러와야 하고, 시도가 실패한

경우 위에서 설명한 것과 같이 해당 오류 코드와 함께 (만약 있다면)

errorCallback 을 불러와야 한다.

오리엔테이션 값 구하기에 최초로 성공한 후, watch operation 이 지속되어

디바이스 오리엔테이션 값을 모니터링하고, 오리엔테이션이 바뀔 때마다 적절한

callback 을 호출하게 된다 watch operation 해당 등록 식별자와 함께

clearWatch() method 를 호출할 때까지 반드시 지속되어야 한다.

선택 파라미터를 건너뛰고 minNotificationInterval 특성에 유효값을 가지는 경우,

적어도 minNotificationInterval 파라미터와 동일한 시간이 발생할 때까지

successCallback 을 호출해서는 안 된다선택 파라미터가 유효 값을 가지지

않거나 미지정 또는 null 인 경우, implementation 은 반드시 그 내용을 무시하고

minNotificationInterval 없이 진행해야 한다.


52 TTAK.OT-10.0323

파라미터

• successCallback


o 타입: OrientationSuccessCallback.

o 설명오리엔테이션 구하기에 성공한 경우 호출됨.

• errorCallback



o 설명: 회전 값을 구할 수 없는 경우 호출됨.

• options


o 타입: OrientationOptions.

o 설명: 애플리케이션을 통지하기 위하여 적용되는 조건.


시계 등록을 제거하기 위해 사용되는 긴 식별자(long identifier).

예외

• DeviceAPIError:



코드 예

var alpha=0; // Watch orientation changes function showOrientation(rotation) { delta = orientation.alpha - alpha; alert("Azimuth has changed in " + delta + " degrees"); alpha=orientation.alpha; } function genericError(e) { alert("Error: "+e.message); } var myOptions = {}; myOptions.minNotificationInterval = 10000; // 10 seconds freq. var subId = deviceapis.orientation.watchOrientation(showOrientation, genericError, myOptions);


53 TTAK.OT-10.0323

clearWatch

오리엔테이션 시계 동작 등록을 취소함.

서명


watchId 인수가 유효하고 이미 존재하는 등록에 해당되는 경우, 반드시 그

watch process 를 즉시 중단하고 더 이상의 callback 을 호출하지 않아야 한다.

watchId 인수가 유효하지 않고 유효 등록에 해당되지 않는 경우, 이 메소드는 더

이상의 조치 없이 리턴해야 한다.

• watchId


o Nullable: 아니오.

o 타입: long.

o 설명: 등록 식별자(Subscription Identifier)

예외

• DeviceAPIError:



코드 예

function showOrientation(rotation)

{

alert("New orientation value available");

}

function genericError(e)

{

alert("Error: cancelling watch procedure");

deviceapis.orientation.clearWatch(subId);

}

// Watch orientation changes

var subId = deviceapis.orientation.watchOrientation(showOrientation,

genericError);


54 TTAK.OT-10.0323

다. OrientationOptions

오리엔테이션 등록에 대한 옵션을 지정함.

[Callback, NoInterfaceObject] interface OrientationOptions {


};

본 인터페이스는 successCallback 호출 조건을 결정하기 위한 watchOrientation()

method 호출에 사용된다.

코드 예

속성


통지 간 최소 시간

watchOrientation() 메소드 요청에 반응하여 2 개의 successCallback 호출

사이에 발생해야 하는 최단 시간 (1000 분의 1 초로 표현)을 지정한다.


{

alert("New orientation info available");

}


{

alert("Error: "+e.message);

}

var myOptions = {};

myOptions.minNotificationInterval = 10000; // 10 seconds

var subId = deviceapis.orientation.watchOrientation(showOrientationInfo,

genericError,

myOptions);


55 TTAK.OT-10.0323

코드 예

라. 회전

디바이스 회전

[NoInterfaceObject] interface Rotation {

readonly attribute long alpha;

readonly attribute long beta;

readonly attribute long gamma;

};

본 인터페이스는 3 개의 서로 다른 축 주변 디바이스 회전 값을 리턴하는 데

사용된다.이는 watchOrientation()과 getCurrentOrientation() 메소드의 success

Callbacks 에 사용된다.

코드 예


{ alert("The orientation on the three axis is: "+

rotation.alpha + " (alpha), " +

rotation.beta + " (beta), " + rotation.gamma + " (gamma)");

}

var pOp = deviceapis.orientation.getCurrentOrientation(showOrientationInfo);


{

alert("New orientation info available");

}


{

alert("Error: "+e.message);

}

var myOptions = {};

myOptions.minNotificationInterval = 10000; // 10 seconds

var subId = deviceapis.orientation.watchOrientation(showOrientationInfo,

genericError,

myOptions);


56 TTAK.OT-10.0323

속성

readonly long alpha

x-축을 중심으로 한 회전.

x-축을 중심을 시계-반대방향 회전 시 양수인 알파 값이 값은 도(degree)로

측정된다.


코드 예

readonly long beta

y-축을 중심으로 한 회전.

y-축을 중심을 시계-반대방향 회전 시 양수인 베타 값이 값은 도(degree)로

측정된다.


코드 예


{

alert("The orientation on the x axis is "+rotation.alpha);

}

var pOp =

deviceapis.orientation.getCurrentOrientation(showOrientationInfo);


{

alert("The orientation on the y axis is "+rotation.beta);

}

var pOp =



57 TTAK.OT-10.0323

readonly long gamma

z-축을 중심으로 한 회전.

z-축을 중심을 시계-반대방향 회전 시 양수인 감마 값.이 값은 도(degree)로

측정된다.


코드 예

마. OrientationSuccessCallback

오리엔테이션 특이적 success callback

[Callback=FunctionOnly, NoInterfaceObject] interface OrientationSuccessCallback

{

void onsuccess(in Rotation rotation);

};

이 callback 인터페이스는 회전(Rotation) 객체를 입력 인수(input argument)로

취하는 기능을 가지는 success callback 을 지정한다. 이는 getCurrentOrientation()

또는 watchOrientation() 등의 비동기 동작에 사용된다.

Methods

onsuccess

비동기 콜을 성공적으로 완료할 때 호출하는 메소드

서명



{

alert("The orientation on the z axis is "+rotation.gamma);

}

var pOp =



58 TTAK.OT-10.0323

rotation


o 타입: Rotation.

o 설명: 디바이스 오리엔테이션

4.3.5. Features

다음 feature:

• http://wacapps.net/api/orientation

또는 그 feature 아래의 속성 중 어떤 것이 효과적으로 요청되면, 오리엔테이션

인터페이스가 예시되고, 그 결과로 나타나는 대상은 글로벌 namespace 에

deviceapis.orientation 으로 나타난다.



http://wacapps.net/api/orientation

오리엔테이션 센서 정보에 접근. 본 feature 는 본 모듈에서 기술된 인터페이스,

메소드 및 속성(attributes) 중 어느 것과 연관된다.

4.3.6. Full WebIDL

module orientation

{



};







59 TTAK.OT-10.0323







};



};





};


OrientationSuccessCallback {


};

};


60 TTAK.OT-10.0323

4.4. 카메라 모듈

4.4.1. 요약

Camera API.



CameraManagerObject

CameraManager PendingOperation

getCameras(CameraArraySuccessCallback


CameraOptions

Camera PendingOperation

captureImage(CameraCaptureSuccessCallback


CameraOptions options)

PendingOperation

startVideoCapture(CameraCaptureSuccessCallback


CameraOptions options)

void stopVideoCapture()

PendingOperation

createPreviewNode(CameraPreviewSuccessCallback


CameraArraySuccessCallback void onsuccess(CameraArray obj)

CameraCaptureSuccessCallback void onsuccess(DOMString filename)

CameraPreviewSuccessCallback void onsuccess(HTMLElement domObj)

4.4.3. 서론

본 API 는 카메라 디바이스에 대한 인터페이스를 제공한다. 이 API 는 사진을 찍고,

동영상을 캡쳐하거나 카메라 뷰파인더를 보여주는데 사용될 수 있다.

카메라의 수와 종류는 디바이스에 따라 다르지만 주 카메라 디바이스에 대한

접근은 반드시 이 API 를 통해 제공되어야 한다.

getCameras() 메소드는 이 API 가 접근할 수 있는 디바이스의 이용할 수 있는

카메라 행렬을 리턴한다 (예를 들어 어떤 디바이스가 이 API 를 통해 조작할 수


61 TTAK.OT-10.0323

없는 카메라를 가지는 경우, 그것은 이 리스트에 기록되어서는 안 된다). 주 카메라

디바이스(보통 뒤쪽 것)는 반드시 행렬의 첫 번째 위치에 기록되어야 한다.

미디어 캡쳐 시, 그 위젯(widget)은 미디어가 저장되어야 하는 선호 위치와 이름을

나타낼 수도 있다.

캡쳐는 비동기식으로 이루어진다.


가. CameraManagerObject

Deviceapis object 에서 예시되는 것을 정의한다.

[NoInterfaceObject] interface CameraManagerObject {

readonly attribute CameraManager camera;

};

Deviceapis implements CameraManagerObject;

카메라 모듈의 기능 접근을 허용하는 deviceapis.camera 객체가 있을 것이다.

나. CameraManager

카메라 관리 인터페이스를 마스터.

[NoInterfaceObject] interface CameraManager {

PendingOperation getCameras(in CameraArraySuccessCallback

successCallback,

in optional ErrorCallback errorCallback)


};

CameraManager 인터페이스는 카메라 디바이스에 접근하기 위한 메소드를

제공한다. getCameras() 메소드는 그 디바이스에서 이용할 수 있는 다양한

카메라에 대한 기준을 리턴한다. 이 기준은 이미지나 동영상 캡쳐에 사용할 수 있다.


62 TTAK.OT-10.0323

Methods

getCameras

디바이스에 지원되는 카메라를 가진다.

서명



동작이 성공적으로 완료되면, 지원되는 모든 카메라를 포함하는 행렬과 함께

successCallback 을 불러온다 (예를 들어 어떤 디바이스가 이 API 를 통해

조작할 수 없는 카메라는 가지는 경우, 그것은 이 행렬에 기재되어서는 안 된다).

주 카메라 디바이스(보통 뒤쪽 것)는 반드시 행렬의 첫 번째 위치에 기록되어야

한다.

디바이스에 지원되는 카메라가 없는 경우, 빈 행렬과 함께 successCallback 을

불러온다.



에러가 발생하는 경우, 에러 원인을 나타내는 에러 코드를 포함하여 불러오기 시

전달되는 기능을 요청한다.

• NOT_SUPPORTED_ERR: 이 feature 가 지원되지 않음. • SECURITY_ERR: 동작이 허용되지 않음. • INVALID_VALUES_ERR: SuccessCallback 이 기능을 포함하지 않는 경우

(예를 들어 null). • UNKNOWN_ERR: 다른 에러 사례.

errorCallback 이 유효한 기능 (예, 무효(null))을 포함하지 않는다면,

errorCallback 을 리턴해야 하는 모든 에러의 경우 (위 참조) implement 가 반드시

조용히 실패하고 더 이상의 조치가 필요하지 않다 (예, 그 에러는 개발자에게


파라미터

• successCallback


o 타입: CameraArraySuccessCallback.

o 설명: 불러오기가 성공적으로 끝났을 때 요청되는 기능


63 TTAK.OT-10.0323

• errorCallback



o 설명: 에러가 발생할 때 호출하는 기능


비동기 콜(call)을 취소하기 위한 PendingOperation

예외

• DeviceAPIError:



코드 예

//variable to hold main camera

var mainCamera;

//success callback

function onCamerasObtained(cams) {

if(cams.length > 0) {

alert("found " + cams.length + " cameras");

//store main camera

mainCamera = cams[0];

} else {

alert("no cameras found");

}

}

//error callback

function onGetCamerasError(error) {

alert(error.message);

}

//call async function to retrieve all cameras on device

try {

var pendop = deviceapis.camera.getCameras(

onCamerasObtained, onGetCamerasError);

} catch (exp) {

alert("getCameras Exception :[" + exp.code + "] " + exp.message);

}


64 TTAK.OT-10.0323

다. CameraOptions

카메라 동작에 대한 옵션을 지정함.

[Callback, NoInterfaceObject] interface CameraOptions {

attribute DOMString destinationFilename;

attribute boolean highRes;

};

본 인터페이스는 successCallback 호출 조건을 결정하기 위한 captureImage()와

startVideoCapture() 메소드 탐색에 사용된다.

속성

DOMString destinationFilename

애플리케이션이 지정하는 파일이름을 포함한 캡쳐한 이미지 또는 동영상이

저장될 목적지.

애플리케이션이 저장된 이미지/동영향을 지정하는 WAC 파일 시스템 모듈에서

정의되는 바와 같이 실체 경로를 지정함. 이는 Filesystem.resolve()을 불러와서

입증할 수 있는 형식의 경로 문자열(path string)이어야 한다.

이 파라미터는 다음 조건에서 WRT 에 의해 무시될 수 있다.

• 패스한 값이 null 임.

• 경로가 유효하지 않은 위치로 분해되는 경우.

• WRT 가 OS 제한 때문에 이 위치에서 이미지/동영상을 저장할 수 없는 경우.

이 파라미터가 무시되는 경우, 플랫폼은 목표 이미지/동영향 형식을 선택할

것이다.

CameraCaptureSuccessCallback 는 심지어 그것이 이 파라미터에서 지정한 경로

및 파일이름과 동일한 경우에도 반드시 캡쳐한 이미지의 실제 경로를 제공해야

한다.

상기 이유로 이 파라미터가 무시되는 경우, WRT 가 타겟 이미지/동영상을 파일

확장자에 의해 지정된 형식으로 저장할 수 없는 경우가 여전히 가능하다. 이런

경우, CameraCaptureSuccessCallback 를 통해 반드시 올바른 확장자를 제공해야

한다.


65 TTAK.OT-10.0323

boolean highRes

애플리케이션이 고해상도로 캡쳐한 이미지나 캡쳐할 동영상을 지정하는 경우

지정하는 플래그.

이 플래그가 true 한 경우 캡쳐한 이미지/동영상은 가능한 높은 품질에 있어야

한다.

플래그가 false 인 경우, 애플리케이션은 고해상도를 요구하지 않으므로

implement 이 저해상도 형식을 사용할 수도 있음을 나타낸다.

이 파라미터에 대한 지원은 플랫폼에 따라 다르다. 플랫폼이 고해상도 및

저해상도 이미지/동영상 캡쳐 옵션을 제공하지 않는다면 WRT 는 이 플레그를

무시하도록 선택할 수도 있다.

라. 카메라

디바이스 카메라에 대한 접근을 제공한다.

[NoInterfaceObject] interface Camera {

readonly attribute DOMString id;

PendingOperation captureImage(in CameraCaptureSuccessCallback

successCallback, in optional ErrorCallback errorCallback,

in optional CameraOptions options)


PendingOperation startVideoCapture(in CameraCaptureSuccessCallback




void stopVideoCapture();

PendingOperation createPreviewNode(in CameraPreviewSuccessCallback



};

본 인터페이스는 디바이스 카메라로부터 이미지나 동영상을 캡쳐하는 웹

애플리케이션을 허용한다. 이 기능을 지원하는 디바이스에서, 이 인터페이스는

카메라 뷰파인더를 미리 보는 웹 애플리케이션도 허용한다.


66 TTAK.OT-10.0323

속성

readonly DOMString id

카메라 식별자

카메라를 식별하는 이름 문자열. “전면”과 “후면”라는 이름은 전면과 후면의 주

카메라 각각을 위해 남겨둔다. 다른 카메라에 대해서는, 추가 후면 카메라에

대하여 implement 시 다른 이름 (예를 들어 “후면 2” 또는 “후면_2 차” 등)을

선택할 수 있다.


Methods

captureImage

비동기적으로 정지 이미지를 캡쳐하고 이를 파일로 저장.

서명


successCallback, in optional ErrorCallback errorCallback, in optional

CameraOptions options);

옵션 입력 인수에 기술된 옵션에 따라 이미지가 캡쳐된다. 옵션 인수가 유효하지

않은 값을 보유하거나 미정 또는 null 인 경우, implement 은 반드시 그 인수를

무시해야 한다.

이미지 캡쳐에 성공한 경우, successCallback 을 부르고 미디어가 저장된 파일을

입력 인수로 통과해야 한다.



그림을 캡쳐할 수 없는 경우, errorCallback 을 부른다. 다음 에러 코드는 에러

조건에 따라 error callback 시 리턴될 수 있다.

• NOT_SUPPORTED_ERR: 이 feature 가 지원되지 않는 경우.

• SECURITY_ERR: 동작이 허용되지 않는 경우.

• INVALID_VALUES_ERR: SuccessCallback 이 어떤 기능을 포함하지 않는

경우 (예를 들어 null).

• UNKNOWN_ERR: 다른 에러 사례 시.


67 TTAK.OT-10.0323

errorCallback 이 유효한 기능(예, 무효(null))을 포함하지 않는다면,

errorCallback 으로 돌아와야 하는 모든 에러의 경우 (위 참조) implement 가

반드시 조용히 실패하고 더 이상의 조치가 필요하지 않다 (예, 그 에러는

개발자에게 통지되지 않음).

파라미터

• successCallback


o 타입: CameraCaptureSuccessCallback.

o 설명: 이미지를 성공적으로 캡쳐했을 때 호출.

• errorCallback



o 설명: 이미지 캡쳐에 실패했을 때 호출.

• options


o 타입: CameraOptions.

o 설명: 이미치 캡쳐를 위하여 적용되는 조건.



예외

• DeviceAPIError:



코드 예

//variable to hold pending operation for captureImage

var op = null;

//success callback

function onCaptureImageSuccess(filename) {

alert("Captured image path:" + filename);

op = null;

}


68 TTAK.OT-10.0323

startVideoCapture

동영상 캡쳐 시작

서명



CameraOptions options);

동영상 캡쳐가 성공적으로 시작되고 stopVideoCapture()를 명백하게 부를 때까지

지속되거나 캡쳐가 플랫폼 제한 때문에 자동적으로 중지된 경우 이 메소드는

동영상 캡쳐를 요청한다 (예. 최대 동영상 크기 또는 동영상 캡쳐 지속시간에

도달).

일단 캡쳐가 중지되면 파일 시스템의 특정 위치에서 미디어를 사용할 수 있고,

successCallback 을 호출한다.

옵션 입력 인수에 기술된 옵션에 따라 동영상이 캡쳐된다. 옵션 논의가 유효하지

않은 값을 보유하거나 미정 또는 null 인 경우, implement 는 반드시 그 논의를

무시해야 한다.

//error callback

function onCaptureImageError(e) {

alert("Capture image failed with error:" + e.message);

op = null;

}

//call async function to capture an image

// it is assumed that mainCamera is obtained previously

// using deviceapis.camera.getCameras

try {

op = mainCamera.captureImage(

onCaptureImageSuccess,

onCaptureImageError,

{destinationFilename:"images/a.jpg", highRes:true}

);

} catch(exp) {

alert("captureImage Exception :[" + exp.code + "] " + exp.message);

}


69 TTAK.OT-10.0323



동영상 캡쳐를 시작할 수 없는 경우나 캡쳐 도중 다른 에러가 발생한 경우, 이는

동영상 저장을 불가능하게 하며, errorCallback 을 반드시 호출해야 한다. 다음

에러 코드는 에러 조건에 따라 errorCallback 시 리턴될 수 있다.

• NOT_SUPPORTED_ERR: 그 feature 가 지원되지 않는 경우.






errorCallback 으로 돌아와야 하는 모든 에러의 경우 (위 참조) implement 가



이 동작은 리턴된 PendingOperation 을 이용하여 어느 시점에서든 취소할 수

있다. 이 PendingOperation 동영상 캡쳐가 중지하면 끝난다.

파라미터

• successCallback


o 타입: CameraCaptureSuccessCallback.

o 설명: 동영상을 성공적으로 캡쳐했을 때 호출.

• errorCallback



o 설명: 캡쳐 시작에 실패했을 때 호출.

• options


o 타입: CameraOptions.

o 설명: 이미치 캡쳐를 위하여 적용되는 조건.




70 TTAK.OT-10.0323

예외

• DeviceAPIError:



코드 예

//variable to hold pending operation for startVideoCapture

var op = null;

//success callback

function onCaptureVideoSuccess(filename) {

alert("Captured video path:" + filename);

op = null;

}

//error callback

function onCaptureVideoError(e) {

alert("Capture video failed with error:" + e.message);

op = null;

}

//call async function to start a video capture

//it is assumed that mainCamera is obtained previous using

deviceapis.camera.getCameras

try {

op = mainCamera.startVideoCapture(

onCaptureVideoSuccess,

onCaptureVideoError,

{destinationFilename:"videos/a.3gp", highRes:true}

);

} catch(exp) {


}


71 TTAK.OT-10.0323

stopVideoCapture

진행 중 동영상 캡쳐 중지를 요청한다.

서명


이것은 startVideoCapture()를 불러온 후 동영상 캡쳐가 진행 중일 때만 부를 수

있다. 이 API 를 불렀을 때 동영상 캡쳐가 활성화 상태가 아니라면, 이는

무시된다. 이 API 를 부르면, 캡쳐가 중지되고, 동영상이 생성 및 저장되며

startVideoCapture()를 위해 등록한 successCallback 을 부른다. 이 과정 중

에러가 발생하는 경우, successCallback 대신에

errorCallback 이 startVideoCapture() 메소드에 전달된다.

코드 예

//variable to hold pending operation for startVideoCapture

var op = null;

//success callback

function onCaptureVideoSuccess(filename) {

alert("Captured video path:" + filename);

op = null;

}

//error callback

function onCaptureVideoError(e) {

alert("Capture video failed with error:" + e.message);

op = null;

}

//call async function to start a video capture



try {

op = mainCamera.startVideoCapture(

onCaptureVideoSuccess,

onCaptureVideoError,

{destinationFilename:"videos/a.3gp", highRes:true}

);


72 TTAK.OT-10.0323

createPreviewNode

카메라 미리보기 창을 표시하기 위한 새로운 DOM object 을 생성 및 리턴한다.

서명



이 메소드는 카메라 미리보기 창을 표시하는 데 사용될 수 있는 WRT 특이적

DOM object 을 생성하기 위해 사용된다. 새롭게 생성된 DOM object 은 그 후

제자리에서 DOM 트리에 부착될 수 있는 문서의 기존 컨테이너 요소(e.g.

<div>)에 첨부할 수 있다. 이는 미리보기를 위한 위치와 치수를 공급한다.

미리보기는 새롭게 생성된 DOM object 이 DOM 내에서 “볼 수 있게”되면 즉시

시작되며, 새롭게 생성된 DOM object 이 “볼 수 없게”되고, DOM 트리에서

떨어지거나 부분적으로 또는 완전히 디스플레이 뷰포트(viewport) 밖으로 스크롤

} catch(exp) {


}

//to be invoked when the user decides to stop the video recording

function stopVideo() {

// if the op is different to null we request to stop the video recording

if (op != null)

mainCamera.stopVideoCapture();

else

alert("Video recording cannot be stopped as it already finished");

}

//to be invoked when the user decides to cancel the video recording

//no video will be captured

function cancelVideo() {

//if the op is null, the operation is already over

if (op != null) {

op.cancel();

op = null;

} else

alert("Video recording cannot be cancelled as it already finished");

}


73 TTAK.OT-10.0323

아웃되면 중지된다. 새롭게 생성된 DOM object 에 해당하는 요소는 반드시 CSS

'z-index' 속성을 반영하여 증가된-현실성이 사례를 이용할 수 있어야 한다

(e.g.동영상 상단에 동영상의 설명을 보여주는 원문 오버레이). Widget 개발자는

미리보기가 더 이상 프리 리소스(free resource)에 요구되지 않고 디스플레이를

복구할 때 DOM 트리로부터 그 요소를 떼어내야 한다.



띄워야 한다.

다음 에러 코드는 에러 조건에 따라 errorCallback 시 리턴될 수 있다:

• NOT_SUPPORTED_ERR: 그 feature 가 지원되지 않는 경우.






errorCallback 으로 돌아와야 하는 모든 에러의 경우 (위 참조) implement 이



파라미터

• successCallback


o 타입: CameraPreviewSuccessCallback.

o 설명: 미리보기 창을 위한 DOM object 생성이 성공적인 경우

불러온다.

• errorCallback



o 설명: 생성에 실패했을 때 호출.




74 TTAK.OT-10.0323

예외

• DeviceAPIError:



코드 예

//variable that holds pending operation

var op = null;

//variable that holds id of preview element

var myPreviewId = null;

//retrieve a 'container' node which can house the preview window object

var myParent = document.getElementById("myDiv");

//success callback

function onCreatePreviewNodeSuccess(previewObject) {

myPreviewId = previewObject.id;

myParent.appendChild(previewObject);

previewObject.style.visibility = "visible"; //start preview

op = null;

}

//error callback

function onCreatePreviewNodeError(e) {

alert("Create preview node failed with error:" + e.message);

op = null;

}

//call async function to create camera preview DOM object



try {

op = mainCamera.createPreviewNode(

onCreatePreviewNodeSuccess, onCreatePreviewNodeError);

} catch(exp) {


}


75 TTAK.OT-10.0323

마. CameraArraySuccessCallback

카메라 리스트 검색을 위한 Success callback.


CameraArraySuccessCallback {

void onsuccess(in CameraArray obj);

};

카메라 리스트를 가져오기 위한 비동기 동작에 사용되는 Success callback.

Methods

onsuccess

카메라 리스트를 성공적으로 가져왔을 때 호출하는 메소드.

서명


파라미터

• obj


o 타입: CameraArray.

o 설명: 카메라 리스트

//to be invoked when the user decides to stop the camera preview

function stopPreview() {

if(myPreviewId != null) {

var preview = document.getElementById(myPreviewId);

previewObject.style.visibility = "hidden"; //stop preview

myParent.removeChild(preview);

myPreviewId = null;

} else {

alert("preview already stopped");

}

}


76 TTAK.OT-10.0323

바. CameraCaptureSuccessCallback

미디어 (이미지/동영상) 캡쳐를 위한 특정 success callback


CameraCaptureSuccessCallback {

void onsuccess(in DOMString filename);

};

이 콜백 인터페이스는 캡쳐된 이미지/동영상 파일이름을 입력 인수로 하는 기능을

가지는 success callback 을 지정한다. 이는 이미지/동영상 캡쳐를 위한 비동기

동작에 사용된다.

Methods

onsuccess


서명


파라미터

• filename


o 무효화가능(Nullable): 아니오.

o 타입: DOMString.

o 설명: 파일시스템 모듈에 의해 분해되는 데 사용할 수 있는 저장된

파일의 실제 경로

사. CameraPreviewSuccessCallback

카메라 미리보기 창 노드(node)를 생성하기 위한 특정 success callback.


CameraPreviewSuccessCallback {

void onsuccess(in HTMLElement domObj);

};


77 TTAK.OT-10.0323

이 콜백 인터페이스는 카메라 미리보기를 표시하기 위하여 사용될 수 있는 새롭게

생성된 DOM object 을 취하는 기능을 가지는 success callback 을 지정한다. 이는

카메라 미리보기 표시를 위한 비동기 동작에 사용된다.

Methods

onsuccess


서명


파라미터

• domObj


o 타입: HTMLElement.

o 설명: 카메라 미리보기 표시에 사용할 수 있는 새롭게 생성된 DOM

object

4.4.5. 타입 정의

가. CameraArray

카메라 어레이.

typedef sequence<Camera> CameraArray;

4.4.6. Feature

다음 feature:

• http://wacapps.net/api/camera

또는 그 feature 아래의 속성 중 어떤 것이 효과적으로 요청되면, CameraManager

인터페이스가 예시되고, 그 결과로 나타나는 객체(object)는 글러벌 네임

스페이스(global namespace)에 deviceapis.camera 로 나타난다.




78 TTAK.OT-10.0323

http://wacapps.net/api/camera.show

Viewfinder 게시를 허용하는 feature 는 captureImage()와 startVideoCapture()

메소드를 제외한 전체 모듈에 대한 접근을 제공한다.

http://wacapps.net/api/camera.capture

카메라를 이용하여 사진 캡쳐나 동영상 기록을 허용하는 feature.

createPreviewNode() 메소드를 제외한 전체 모듈에 대한 접근을 제공한다.

http://wacapps.net/api/camera

모든 카메라 feature (예, camera.show 및 camera.capture 등)에 대한 접근을

제공한다.

4.4.7. Full WebIDL

module camera {




};




successCallback,



};




};




79 TTAK.OT-10.0323


successCallback,





successCallback,






successCallback,



};




};




};




};

};


80 TTAK.OT-10.0323

4.5. 디바이스(devicestatus) 모듈

4.5.1. 요약

웹 환경으로부터 디바이스 상태에 대한 접근을 제공한다.



DeviceapisDeviceStatusManager

DeviceStatusManager StringArray getComponents(DOMString aspect)

boolean isSupported(DOMString aspect, DOMString?

property)

PendingOperation

getPropertyValue(PropertyValueSuccessCallback


PropertyRef prop)

long

watchPropertyChange(PropertyValueSuccessCallback


PropertyRef prop, WatchOptions options)

void clearPropertyChange(long watchHandler)

PropertyRef

WatchOptions

DeviceAPIError

PropertyValueSuccessCallback void onpropertyvalue(Object value, PropertyRef property)

4.5.3. 서론

본 상태 정보는 WAC 에 의해 명세서에 기입된 vocabulary 를 활용한 트리 구조로

구성된다. 정보의 첫 번째 층은 “aspect”, 두 번째 층은 “컴포넌트(components)”,

세 번째 층은 “프로퍼티(property)”로 명명된다.

본 API 는 트리(tree)를 탐색하고, 선택된 프로퍼티(property)의 값을 취하며, 선택된

값의 변경에 대한 비동기 통지를 설정하는 메소드를 제공한다. 다음은 트리 데이터

구조의 개요를 제공한다:

• "Aspects": 디바이스의 고유한 측면과 관련된 정보를 모으는 다양한 측면으로

구성되는 단어 (e.g. 'WebRuntime', 'Battery', 'MemoryUnit').


81 TTAK.OT-10.0323

• "Component": 동일한 aspect 의 다양한 예를 기술하고자 하는 다양한

컴포넌트로 구성될 수 있는 aspect. (e.g. 'MemoryUnit' aspect 는 'physical',

'virtual', 'storage') 등의 다양한 컴포넌트를 가질 수 있다. 2 개의 특별 컴포넌트

식별자가 있음: - _active(active): 현재 widget 이 사용하고 있는 aspect 의 예를

말한다. 예를 들어, widget 이 implementation 되는 웹 런타임(Web Runtime),

위젯(widget)이 표시되는 디스플레이_디폴트(default): 현재 디바이스가 디폴트로

사용하고 있는 컴포넌트의 예를 말한다. 예를 들어, 위젯(widget)이 디폴트로

implementation 되는 웹 런 타임(Web Runtime)이나 디바이스의 주 디스플레이.

• "Property": aspect 는 컴포넌트의 특정 프로퍼티에 대한 정보를 제공하는

프로퍼티로 이루어지며, 예를 들어 모든 'MemoryUnit' 컴포넌트에 대하여 'size',

'availableSize'. 'removable' 등의 프로퍼티가 지원된다. 모든 프로퍼티에 대하여

값이 표현되는 WebIDL Type 이 지정된다.

vocabulary tree 에서 프로퍼티를 분해하고자 할 때, 최소한 aspect 와 프로퍼티

명은 반드시 개발자가 제공해야 한다. 컴포넌트가 지정되지 않고 선택된 aspect 에

대하여 active 컴포넌트가 있는 경우, 이 active 컴포넌트는 반드시

구현시(implementation)에 의해 사용되어야 한다. 선택된 aspect 에 대하여 이용

가능한 active 컴포넌트가 없는 경우, 구현은 반드시 디폴트 컴포넌트를 사용해야

한다.

본 API 는 오직 DeviceStatus 프로퍼티에 대한 액세스만을 정의하며 aspect 나

프로퍼티의 이용가능성에 대해서는 정의하지 않는다. 종합적인 프로퍼티 리스트를

탐색하려면, WAC Vocabulary 를 참조할 것. WAC Vocabulary 의 지원은 필수이므로,

따라서 전체 vocabulary 는 반드시 implementation 에 의해 인식되어야 한다 (예를

들어, 이 프로퍼티 중 어떤 것에 대해서도 NOT_FOUND_ERR 가 리턴 되어서는

안됨).

하드웨어 제한 때문에 액세스할 수 없는 프로퍼티를 제외하고, 구현은 반드시 WAC

vocabulary 내의 모든 프로퍼티에 대하여 값을 리턴할 수 있어야 한다. 예를 들어,

이 디바이스는 WiFi 하드웨어가 없으므로 WiFiHardware aspect 프로퍼티는 결코

검색할 수 없으며 isSupported 는 false 로 돌아온다.


82 TTAK.OT-10.0323


가. DeviceapisDeviceStatusManager


[NoInterfaceObject] interface DeviceapisDeviceStatusManager {

readonly attribute DeviceStatusManager devicestatus;

};

Deviceapis implements DeviceapisDeviceStatusManager;

deviceapis.devicestatus 객체는 device status module 에 접근을 허용한다.

나. DeviceStatusManager

디바이스의 상태를 묻기 위한 엔트리 포인트(entry point).

[NoInterfaceObject] interface DeviceStatusManager {

StringArray getComponents(in DOMString aspect)


boolean isSupported(in DOMString aspect,

[TreatUndefinedAs=Null] in optional DOMString property)


PendingOperation getPropertyValue(in PropertyValueSuccessCallback

successCallback, in ErrorCallback errorCallback,

in PropertyRef prop)


long watchPropertyChange(in PropertyValueSuccessCallback successCallback,

in ErrorCallback errorCallback,

in PropertyRef prop,

in optional WatchOptions options)


void clearPropertyChange(in long watchHandler)


};

이 모듈은 디바이스상태에 관한 정보를 얻기위한 방법을 제공하고 디바이스 상태

변경에 대한 noti 를 수신한다.


83 TTAK.OT-10.0323

코드 예

Methods

getComponents

지정된 aspect 의 사례인 모든 컴포넌트의 이름을 리턴한다.

서명

StringArray getComponents(in DOMString aspect);

이 메소드는 지정된 aspect 의 사례인 다양한 컴포넌트에 대한 정보를 제공한다.

aspect 가 유효한 값을 가지지 않는 경우 (e.g. WAC Vocabulary 의 부분이 아님),

이 메소드는 null 을 리턴한다.

aspect 가 유효한 경우에는, 메소드가 그 aspect 의 모든 다양한 컴포넌트 부분을

리턴하게 된다.

파라미터

• aspect


o 무효화가능: 아니오.


o 설명: 컴포넌트가 구해지는 aspect


컴포넌트 이름 리스트

function onValueRetrieved(value) {

alert("The battery level is " + value);

}

deviceapis.devicestatus.getPropertyValue(

onValueRetrieved,

function(e){alert("An error occurred " + e.message);},

{property:"batteryLevel", aspect:"Battery"});


84 TTAK.OT-10.0323

예외

• DeviceAPIError:



코드 예

isSupported

프로퍼티나 aspect 가 디바이스에 의해 지원되는지 확인.

서명

boolean isSupported(in DOMString aspect, in optional DOMString? property);

aspect 는 반드시 이 메소드에 전달되어야 하며, 프로퍼티는 선택적으로 전달될

수 있다. 파라미터 프로퍼티가 전달되지 않거나 null 인 경우, 메소드는 그

aspect 가 적어도 하나 이상의 프로퍼티에 의해 지원되는지 확인한다. 메소드는

디바이스가 적어도 그 값을 구할 수 있는 aspect 에 속하는 하나 이상의

프로퍼티를 가지는 경우 true 를 리턴하고, 그렇지 않으면 false 를 리턴한다.

어떤 파라미터 프로퍼티가 null 이외의 값과 함께 전달되고 aspect/property 쌍이

지원되는 경우 (예를 들어 aspect/property 쌍은 WAC Vocabulary 의 일부이며,

디바이스가 그 프로퍼티의 값을 수할 수 있고 필요한 하드웨어가 있음), 그

implementation 은 반드시 true 를 리턴하고 그렇지 않으면 false 를 리턴해야

한다.

플랫폼은 반드시 WAC Vocabulary 에 지정되지 않은 모든 프로퍼티와 WAC

Vocabulary 의 일부이지만 하드웨어 제한 때문에 액세스할 수 없는 프로퍼티에

대하여 false 를 리턴해야 한다.

파라미터

• aspect


o 무효화가능:

var displays = devicestatus.getComponents('Display');


85 TTAK.OT-10.0323


o 설명: 확인해야 하는 aspect 이름.

• property


o 무효화가능: 아니오.


o 설명: 확인해야 하는 aspect 이름.

리턴 값

implementation 에 의해 프로퍼티/aspect 이 지원되는 경우 true.

예외

• DeviceAPIError:



코드 예

getPropertyValue

특정 프로퍼티의 값을 리턴한다.

서명


successCallback, in ErrorCallback errorCallback, in PropertyRef prop);

function onValueRetrieved(value) {


}

if (deviceapis.devicestatus.isSupported('Battery','batteryLevel')) {


onValueRetrieved,

function(error){alert("An error occurred " + error.message),


);

}


86 TTAK.OT-10.0323

이 메소드는 디바이스 상태 프로퍼티의 현재 값을 리턴한다.

prop argument 는 의무적으로 프로퍼티와 aspect 를 포함해야 한다 (컴포넌트는

선택가능). 컴포넌트가 지정되지 않은 경우, implementation 은 반드시 주어진

aspect(_active)의 active 컴포넌트 사용을 시도해야 한다. active 컴포넌트가

존재하지 않는 경우, implementation 은 반드시 주어진 aspect 에 대한 디폴트

컴포넌트(_default)를 사용해야 한다.

호출되었을 때, 반드시 기능이 즉시 리턴하고 비동기적으로 요청된 프로퍼티의

현재 값을 구해야 한다. 성공적인 경우, successCallback 는 (vocabulary 에서

지정되는 바와 같이) 반드시 적절한 데이터 타입을 가지는 프로퍼티를 포함하는

객체(object) 및 해당 PropertyRef 와 함께 호출되어야 한다.



에러가 발생하는 경우, 호출 시 전달되는 errorCallback 기능은 다음 에러 코드로

에러 원인을 나타내며, DeviceAPIError 객체와 함께 호출된다:

• NOT_SUPPORTED_ERR: 이 feature 가 지원되지 않는 경우

implementation 은 반드시 이 에러 코드를 리턴해야 함.

• SECURITY_ERR: 동작이 불가한 경우 implementation 은 반드시 이

에러를 리턴해야 한다.

• NOT_FOUND_ERR: propertyRef 를 유효한 것으로 인식하지 못하는 경우

이 에러를 리턴해야 한다 (예를 들어, 프로퍼티는 WAC Vocabulary 에서

정의되며, 유효하지 않은 aspect 또는 컴포넌트의 일부가 아니다).

• NOT_AVAILABLE_ERR: 이 프로퍼티가 유효한 것으로 인식되는 경우

implementation 은 반드시 이 에러 코드를 리턴해야 하지만, 현재 값은

구할 수 없다. 이는 필요한 하드웨어가 디바이스에 포함되어 있지 않거나

그 프로퍼티 값을 일시적으로 사용할 수 없게 만드는 일시적인 문제가

있기 때문일 수도 있다 (그러나 어떤 시점에서는 그 값을 이용할 수도

있디). 이 두 가지 상황을 구분하기 위하여, isSupported 메소드를 사용할

수 있다. isSupported 는 첫 번째 상황의 프로퍼티에 대하여 반드시

false 를 리턴해야 하고 두 번재 상황의 프로퍼티에 대해서는 true 를

리턴해야 한다.

• INVALID_VALUES_ERR: 모든 입력 파라미터가 유효하지 않은 값을

포함하는 경우, 예들 들어 successCallback 나 prop 등은 null 이다.

개발자가 에러를 무시할 수 있도록, errorCallback 은 null 을 유효한

값으로 수용한다.

• UNKNOWN_ERR: Implementation 은 반드시 다른 에러 사례 시 이 에러

코드를 리턴해야 한다.


87 TTAK.OT-10.0323


리턴해야 하는 모든 에러의 경우 (위 참조) implementation 은 반드시 조용히

실패하고 더 이상의 조치가 필요하지 않는다 (예, 그 에러는 개발자에게


파라미터

• successCallback


o 타입: PropertyValueSuccessCallback.

o 설명: 메소드가 성공적으로 완료된 경우 호출됨.

• errorCallback



o 설명: 에러 시 호출 됨.

• prop


o 타입: PropertyRef.

o 설명: 값이 요청되는 프로퍼티에 대한 reference

리턴 값

비동기 콜(asynchronous call) 취소를 요청하기 위한 PendingOperation

예외

• DeviceAPIError:



코드 예

function onValueRetrieved(value){


}


onValueRetrieved,

function(e){alert("An error occurred " + e.message);},



88 TTAK.OT-10.0323

watchPropertyChange

프로퍼티변화에 대한 통지를 받기 위해 가입.

서명

long watchPropertyChange(in PropertyValueSuccessCallback successCallback,

in ErrorCallback errorCallback, in PropertyRef prop, in optional WatchOptions

options);

prop 인수(argument)는 의무적으로 프로퍼티와 aspect 를 포함해야 한다

(컴포넌트는 선택가능). 컴포넌트가 지정되지 않은 경우, 구현은 반드시 주어진

aspect(_active)의 active 컴포넌트 사용을 시도해야 한다. Active 컴포넌트가

존재하지 않는 경우, 구현은 반드시 주어진 aspect 에 대한 디폴트

컴포넌트(_default)를 사용해야 한다.

이 메소드가 호출되면, 즉시 가입 식별자를 리턴하고 watch operation 을

비동기적으로 시작해야 한다. 식별자를 리턴한 후, 구현은 반드시 그 프로퍼티에

대한 현재 값을 가지려고 시도해야 한다. 그 시도가 성공한 경우,

successCallback 은 반드시 현재 프로퍼티 값과 함께 호출되어야 한다. 그

시도가 실패하고 메소드가 non-null errorCallback argument 와 함께 호출된 경우,

구현은 반드시 적절한 에러 코드와 함께 DeviceAPIError 를 가지는

errorCallback 을 호출해야 한다.

• NOT_SUPPORTED_ERR: 이 feature 가 지원되지 않는 경우 구현은 반드시

이 에러 코드를 리턴해야 함.

• SECURITY_ERR: 동작이 불가한 경우 구현은 반드시 이 에러를 리턴해야

한다.

• NOT_FOUND_ERR: propertyRef 를 유효한 것으로 인식하지 못하는 경우

이 에러를 리턴해야 한다 (예를 들어, 프로퍼티는 WAC Vocabulary 에서

정의되며, 유효하지 않은 aspect 또는 컴포넌트 일부가 아니다).

• NOT_AVAILABLE_ERR: 이 프로퍼티가 유효한 것으로 인식되는 경우

구현은 반드시 이 에러 코드를 리턴해야 하지만, 헌재 값은 구할 수 없다.

이는 필요한 하드웨어가 디바이스에 포함되어 있지 않거나 그 프로퍼티

값을 일시적으로 사용할 수 없게 만드는 일시적인 문제가 있기 때문일

수도 있다 (그러나 어떤 시점에서는 그 값을 이용할 수도 있디). 이 두

가지 상황을 구분하기 위하여, isSupported 메소드를 사용할 수 있다.

isSupported 는 첫 번째 상황의 프로퍼티에 대하여 반드시 false 를

리턴해야 하고 두 번재 상황의 프로퍼티에 대해서는 true 를 리턴해야

한다.


89 TTAK.OT-10.0323

• INVALID_VALUES_ERR: 모든 필수 입력 파라미터가 유효하지 않은 값을

포함하는 경우, 예들 들어 successCallback 나 prop 등은 null 이다.

개발자가 오류를 무시할 수 있도록, errorCallback 은 null 을 유효한


• UNKNOWN_ERR: 구현은 반드시 다른 에러 사례 시 이 에러 코드를

리턴해야 한다.

최초 실행 후, watch 동작이 지속되어 프로퍼티 값을 모니터한다. 구현은

프로퍼티 값이 변할 때마다 successCallback 을 호출하며 옵션 파라미터에 의해

지정된 조건은 등록 식별자(subscription identifier)와 함께 호출되는

clearWatch() 메소드를 통하여 등록이 취소될 때까지 충족된다.

options argument 는 필수적이 아니며 통지의 입도(granularity)를 지정하는 데

사용된다. 어떤 옵션이 유효하지 않거나 options argument 가 미정 또는 null 인

경우, 이를 무시한다.

파라미터

• successCallback


o 타입: PropertyValueSuccessCallback.

o 설명: 프로퍼티 변경 시마다 호출되는 success callback.

• errorCallback



o 설명: 에러 발생시 호출되는 error callback

• prop



o 설명: 통지 또는 변경되는 프로퍼티에 대한 레퍼런스(reference)

• options


o 타입: WatchOptions.

o 설명: 통지의 입도(granulity)를 지정하는 옵션 세트.

리턴 값

clearPropertyChange() 메소드를 사용하여 통지 등록을 취소하는 데 사용되는

핸들러(handler)


90 TTAK.OT-10.0323

예외

• DeviceAPIError:



코드 예

clearPropertyChange

watchPropertyChange 에 의한 프로퍼티 변경 설정에 대한 통지를 해지.

서명

void clearPropertyChange(in long watchHandler);

watchHandler argument 가 유효한 형태이고 이미 존재하는 등록에 해당되는

경우, 반드시 그 watch 프로세스를 즉시 중단하고 더 이상의 callbacks 을

불러오지 않아야 한다. watchId argument 가 유효 등록에 해당되지 않는 경우,

이 메소드는 더 이상의 조치 없이 반환되어야 한다.

파라미터

• watchHandler

o 선택가능: 아니오. o 무효화가능: 아니오. o 타입: long. o 설명: identifier of the subscription returned by the

watchPropertyChange() method.

예외

• DeviceAPIError:



function propertyChange(ref, value) {

alert("New value for " + ref.property + " is " + value);

}

deviceapis.devicestatus.watchPropertyChange(propertyChange, null



91 TTAK.OT-10.0323

코드 예

다. PropertyRef

프로퍼티에 대한 전체 레퍼런스(reference)

[Callback, NoInterfaceObject] interface PropertyRef {

attribute DOMString component;

attribute DOMString aspect;

attribute DOMString property;

};

이는 다음 세 가지 수준으로 지정된다; aspect, 컴포넌트 및 프로퍼티 이것은

Vocabulary 내의 단일 프로퍼티를 참조할 수 있다. "aspect"와 "프로퍼티" 는

필수적이며, "component" 는 선택적이다.

속성

DOMString component

Component Identifier (optional).

DOMString aspect

Local Aspect Name (mandatory).

DOMString property

Local Property Name (mandatory).

var id = null;



if (id != null) // After receiving the first notification, we clear it

devicestatus.clearPropertyChange(id);

}

id = deviceapis.devicestatus.watchPropertyChange(propertyChange,

null,{property:"batteryLevel", aspect:"Battery"});


92 TTAK.OT-10.0323

라. WatchOptions

watchPropertyChange 동작에 사용되는 옵션 세트를 설명한다.

[Callback, NoInterfaceObject] interface WatchOptions {


attribute long maxNotificationInterval;

attribute long minChangePercent;

};

코드 예

속성


통지(Notification) 간의 최소 시간, 밀리세컨드(millisecond)로 표현됨.

통지는 이전 통지로부터 이 값 이상의 시간이 경과될 때까지 통지되지 않아야

한다. maxNotificationInterval 이 0 이상인 경우, minNotificationInterval 는 반드시

maxNotificationInterval 보다 작아야 하며, 그렇지 않은 경우 WatchOptions

객체는 유효하지 않은 것으로 간주한다.

그 값이 null 또는 0 인 경우 (디폴트 값), 결코 이 파라미터를 무시해서는 안

된다.



}

// Subscribe for being notified when battery level changes,

invocations to the listener will be at least separated by 60 secs

deviceapis.devicestatus.watchPropertyChange(propertyChange,null,

{property:"batteryLevel", aspect:"Battery"},

{minNotificationInterval:60000});


93 TTAK.OT-10.0323

long maxNotificationInterval

통지 간의 최대 시간, 밀리세컨드(millisecond)로 표현됨.

속성이 해당 시간 동안 변경되지 않은 경우에도 지정된 시간 후에는 반드시

통지가 이루어져야 한다. minNotificationInterval 가 0 이상인 경우 반드시

이것보다 커야 하며, 그렇지 않은 경우 WatchOptions 객체는 유효하지 않은

것으로 간주한다. 이 파라미터를 사용하여, 디바이스 상태가 변경되지 않은

경우에도 통지가 이루어질 수 있다.

그 값이 null 또는 0 인 경우 (디폴트 값), 결코 이 파라미터를 무시해서는 안

된다.

long minChangePercent

그 값의 최소 변경 백분율

숫자로 된 속성 값에 대해서만 유효함. 이는 통지가 이루어지기 전 속성 값에서

발생할 수 있는 최소 백분율 변경을 지정한다. 예를 들어, 이전 값이 100 이고

지정된 minChangePercent 가 20%라면 그 값이 80 이하로 떨어지거나

120 이상으로 증가할 때만 통지가 발생하게 된다.

minChangePercent 과 minNotificationInterval 또는 maxNotificationInterval 이

0 이 아닌 값을 가지는 경우, frequency filter 가 우세하다.

디폴트 값은 0 이고, 이는 최소 변경에는 제한이 필요하지 않다는 것을 나타낸다.

1) DeviceAPIError

이 모듈에 대한 특정 에러 코드를 정의한다.

[NoInterfaceObject, Supplemental] interface DeviceAPIError {

const short NOT_AVAILABLE_ERR = 101;

};

상수

short NOT_AVAILABLE_ERR

그 속성은 현재 구할 수 없다.


94 TTAK.OT-10.0323

마. PropertyValueSuccessCallback

Device status success callback.


PropertyValueSuccessCallback {

void onpropertyvalue(in Object value, in PropertyRef property);

};

속성의 값을 통지하기 위한 success callback. Callback 이 호출되면 입력

파라미터는 새 속성 값이자 관련 속성의 식별자이다.

Methods

onpropertyvalue

속성 변경에 대한 통지를 호출하는 메소드.

서명


파라미터

• value


o 타입: 객체.

o 설명: 속성을 포함하는 값.

• property



o 설명: 관련 속성


95 TTAK.OT-10.0323

4.5.5. Features

다음 feature:

• http://wacapps.net/api/devicestatus

또는 그 feature 아래의 속성 중 어떤 것이 효과적으로 요청되면,

DeviceStatusManager 가 예시되고, 그 결과로 나타나는 대상은 전역

namespace 에 deviceapis.devicestatus 로 나타난다.



http://wacapps.net/api/devicestatus.deviceinfo

모든 모듈에 대한 Access getPropertyValue() 및 watchPropertyValue() method 는

deviceinfo aspect 에만 사용될 수 있다.

• 배터리(Battery)

• 디바이스(Device)

• 디스플레이(Display)

• 메모리유닛(MemoryUnit)

• OperatingSystem

• WebRuntime.

http://wacapps.net/api/devicestatus.networkinfo

모든 모듈에 대한 Access. getPropertyValue() 및 watchPropertyValue() method 는

networkinfo aspect 에만 사용될 수 있다.

• CellularHardware

• CellularNetwork

• WiFiHardware

• WiFiNetwork.

http://wacapps.net/api/devicestatus

모든 모듈 feature 에 대한 Access 를 제공한다.


96 TTAK.OT-10.0323

4.5.6. Full WebIDL

module devicestatus {



};





boolean isSupported(in DOMString aspect, [TreatUndefinedAs=Null] in

optional DOMString? property)



successCallback,




long watchPropertyChange(in PropertyValueSuccessCallback

successCallback,







};





97 TTAK.OT-10.0323


};





};



};




};

};


98 TTAK.OT-10.0323

4.6. 파일시스템(filesystem) 모듈

4.6.1. 요약

파일시스템(Filesystem) API.



DeviceapisFileSystemManager

FileSystemManager PendingOperation resolve(FileSystemSuccessCallback


DOMString location, DOMString? mode)

File DOMString toURI()

PendingOperation

listFiles(FileSystemListSuccessCallback

successCallback, ErrorCallback errorCallback, FileFilter

filter)

PendingOperation

openStream(FileOpenSuccessCallback


DOMString mode, DOMString? encoding)

PendingOperation

readAsText(ReadFileAsStringSuccessCallback


DOMString? encoding)

PendingOperation copyTo(SuccessCallback


DOMString originFilePath, DOMString

destinationFilePath, boolean overwrite)

PendingOperation moveTo(SuccessCallback


DOMString originFilePath, DOMString

destinationFilePath, boolean overwrite)

File createDirectory(DOMString dirPath)

File createFile(DOMString filePath)

File resolve(DOMString filePath)

PendingOperation deleteDirectory(SuccessCallback


DOMString directory, boolean recursive)


99 TTAK.OT-10.0323


PendingOperation deleteFile(SuccessCallback


DOMString file)

FileFilter

FileStream void close()

DOMString read(long charCount)

ByteArray readBytes(long byteCount)

DOMString readBase64(long byteCount)

void write(DOMString stringData)

void writeBytes(ByteArray byteData)

void writeBase64(DOMString base64Data)

FileSystemSuccessCallback void onsuccess(File file)

ReadFileAsStringSuccessCallback void onsuccess(DOMString fileStr)

FileOpenSuccessCallback void onsuccess(FileStream filestream)

FileSystemListSuccessCallback void onsuccess(FileArray files)

DeviceAPIError

4.6.3. 서론

본 API 는 디바이스 파일시스템 정보에 대한 접근을 제공한다. 파일시스템은

각각이 디바이스 파일시스템의 특정 위치에 해당하며 해체된 filesystem virtual root

location 의 이론적인 수집을 의미한다. filesystem API 는 single virtual

filesystem 으로서 이들의 root locations 아래로 hierarchy 를 드러낸다.

각각의 virtual root 는 string 이름을 가진다. virtual filesystem 내의 각 파일 또는

디렉토리는 완전히 자격을 갖춘 형식 경로를 이용하여 어드레스를 지정한다.

<rootname>이며 virtual root 의 이름이며 <path>가 파일에 대한 경로이거나 root 에

대한 디렉토리인 <root name>/<path>.

다음 virtual root 는 반드시 지원해야 한다:

• images: 이미지 위치

• videos: 동영상 위치

• music: 사운드 위치

• documents: 문서 위치

• downloads: 다운로드 항목 위치

• wgt-package: Widget 패키지 위치 (읽기전용 위치)

• wgt-private: Widget 개인 저장

• wgt-private-tmp: Widget 개인 휘발성 저장 구역

• removable: 삭제가능 저장 구역 위치


100 TTAK.OT-10.0323

위에서 지정된 곳으로부터 특정 위치에 접근하기 위하여, 반드시 filesystem.resolve

call 을 이용하여 File handle 을 구해야 한다.

File handle 은 파일이나 디렉토리를 나타낸다. 어떤 파일에 대하여, isFile 속성은

true 이다. 어떤 디렉토리에 대하여, isFile 속성은 true 이다. FileStream handle 을

이용하여 파일을 열고 읽거나 쓸 수 있다. 파일 및 서브-디렉토리 리스트는

디렉토리로부터 얻을 수 있으며 디렉토리 리스트를 프로세싱하는 것보다 보다

편리하게 파일이나 서브디렉토리를 분해하기 위한 resolve 메소드가 있다.

구현은 반드시 파일명 내의 다음 문자를 이용할 수 있도록 지원해야 한다.

• 문자 (azAZ)

• 숫자 (0-9)

• 공백

• 밑줄 ("_")

• 하이픈 ("-")

• 점 (".").

구현은 플랫폼 지원에 따라 파일명 내에 추가적인 문자를 지원할 수 있다.

구현은 플랫폼에 따라 파일명 내에 추가적인 문자 사용을 금지할 수도 있다. 파일명

내에 경로 분리기호(separator)인 "/"는 사용할 수 없다. "/" 문자는 (경로)

컴포넌트 분리기호로 사용된다.

예를 들어 최대 경로길이, 파일명 길이, 대소문자 구분, 추가 문자 지원 등 일부

파일명과 경로의 기타 feature 는 플랫폼에 따라 다르다. 따라서 많은 플랫폼에서

공통으로 지원될 수 없는 aspect 에 대한 의존성은 피하는 것이 좋다.

어떤 경로가 근원적인 filesystem 과 상호작용하는 데 사용되면, 그 파일 경로에

사용된 encoding 은 플랫폼 디폴트(platform default)이어야 한다.


101 TTAK.OT-10.0323


가. DeviceapisFileSystemManager


[NoInterfaceObject] interface DeviceapisFileSystemManager{

readonly attribute FileSystemManager filesystem;

};

Deviceapis implements DeviceapisFileSystemManager;

파일시스템 모듈의 기능 접근을 허용하는 deviceapis.filesystem 객체가 있을

것이다.

나. FileSystemManager

filesystem API 에 대한 접근을 제공하는 파일 시스템 관리자 클래스(file system

manager class).

[NoInterfaceObject] interface FileSystemManager {

readonly attribute long maxPathLength;

PendingOperation resolve(in FileSystemSuccessCallback successCallback,


in DOMString location,

[TreatUndefinedAs=Null] in optional DOMString?

mode)


};

이 관리자 클래스는 파일시스템 기반 API 를 노출하고 루트 및 디폴트 위치 결정,

주어진 위치를 File Handle 로 분해, 파일시스템 이벤트에 대한 파일시스템 listener

등록 등의 기능을 제공한다.


102 TTAK.OT-10.0323

코드 예

function successCB(files) {

for(var i = 0; files.length; i++) {

alert("File Name is " + files[i].name); // displays file name

}

var testFile = documentsDir.createFile("test.txt");

if (testFile != null) {

testFile.openStream(

function(fs){

fs.write("HelloWorld");

fs.close();

}, function(e){

alert("Error " + e.message);

}, "w", "UTF-8"

);

}

}

function errorCB(error) {

alert("The error " + error.message + " occurred when listing the files in the

selected folder");

}

var documentsDir;


function(dir){

documentsDir = dir;

dir.listFiles(successCB,errorCB);

}, function(e){

alert("Error" + e.message);

}, 'documents', "rw"

);


103 TTAK.OT-10.0323

속성

readonly long maxPathLength

플랫폼 의존성 최대 경로 길이를 포함한다.


코드 예

Methods

resolve

위치를 File handle 로 분해.

서명

PendingOperation resolve(in FileSystemSuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString location, in optional DOMString?

mode);

주어진 위치를 입증 및 File handle 로 분해. operation 이 성공적으로 완료된

경우, 그 handle 은 succesCallback 으로 리턴된다. 유효한 위치는 유효한 루트

또는 디폴트로 미리 고정되며 기존의 접근 가능한 파일이나 디렉토리로 주소를

지정한다.

compliant implementation 이 반드시 지원해야 하는 루트 위치 리스트는 다음과

같다:

• documents: 디바이스 내에 텍스트 문서 (e.g. pdf, doc...)가 디폴트로

저장되는 디폴트 폴더를 말한다. 예를 들어, 일부 플랫폼에서 이는 “내

문서” 폴더에 해당한다.

• images: 디바이스 내에 사진 (e.g. jpg, gif, png, etc.) 등의 정지 이미지가

디폴트로 저장되는 디폴트 폴더를 말한다. 예를 들어, 일부 플랫폼에서

이는 “내 이미지” 폴더에 해당한다.

• music: 디바이스 내에 사운드 클립 (e.g. mp3 , aac, etc.)가 디폴트로


음악” 폴더에 해당한다.

alert("The maximum path length is " + deviceapis.filesystem.maxPathLength);


104 TTAK.OT-10.0323

• videos: 디바이스 내에 비디오 클립 (e.g. avi, mp4, etc.) 가 디폴트로


비디오” 폴더에 해당한다.

• downloads: 디바이스 내에 다운로드 된 파일 (e.g. 브라우저에 따라, e-

mail client, etc.)가 디폴트로 저장되는 디폴트 폴더를 말한다. 예를 들어,

일부 플랫폼에서 이는 “다운로드” 폴더에 해당한다.

• wgt-package: Widget 파일 내용을 추출한 읽기전용 폴더를 말한다.

• wgt-private: Widget 이 정보를 저장할 수 있는 개인 폴더를 말한다. 이

폴더는 반드시 그 widget 에만 접근 가능해야 하며, 다른 위젯이나

애플리케이션은 그곳에 저장된 정보에 접근할 수 없어야 한다.

• wgt-private-tmp: Widget 이 위젯 실행 주기 동안 이용할 수 있는

데이터를 저장할 수 있는 임시 개인폴더를 말한다. 이 폴더의 내용은

widget 이 닫히거나 Web Runtime 이 재 시작되면 이 디렉토리에서 삭제될

수 있다. 이 폴더는 반드시 그 widget 에만 접근 가능해야 하며, 다른

위젯이나 애플리케이션은 그곳에 접근할 수 없어야 한다.

• removable: SD 카드 등의 탈착 가능한 미디어에 저장된 내용에 대한

경로를 묘사한 폴더를 말한다.

모드 파라미터(mode parameter)는 결과적인 파일 객체가 directory tree 를

포함하는 루트 위치(root location)에 대한 읽기전용 접근 (“r” 액세스) 또는 읽고

쓰기 접근 (“rw” 액세스) 여부를 지정한다. 요청된 액세스에 대한 허가는 보안

프레임워크(security framework)로부터 획득할 수 있다. 결과로 얻은 File 객체가

액세스를 가지면, 액세스는 File 의 일정 메소드 설명에 기재된 바와 같이 보안

프레임워크를 더 이상 참조하지 않고 이 인스턴스(instance)로부터 유래된 다른

File 객체에 계승된다.


경우 TYPE_MISMATCH_ERR 코드가 있는 DeviceAPIError 예외를 발생시켜야

한다.

그 파일이 다른 에러 때문에 분해될 수 없는 경우, 적절한 에러 코드와 함께

errorCallback 이 실시된다:

• INVALID_VALUES_ERR: successCallback 이 유효한 기능을 포함하지

않거나 (예를 들어 null 또는 미정) 모드(mode)가 유효하지 않은 경우

(예를 들어 “r”이나 "rw”가 아님).

• NOT_FOUND_ERR: 위치 입력 인수(input argument)가 유효한 위치에

해당하지 않음.


• SECURITY_ERR: 그 동작이 허용되지 않는 경우.

• UNKNOWN_ERR: 다른 오류 사례 시.


105 TTAK.OT-10.0323

파라미터

• successCallback


o 타입: FileSystemSuccessCallback.

o 설명: 새로 생성된 File 객체가 유효한 형태이고, 위치가

성공적으로 분해되었을 때 호출됨.

• errorCallback



o 설명: 에러 발생 시 호출됨.

• location


o 무효화가능(nullable): 아니오.


o 설명: 분해 대상 위치. 반드시 유효한 루트(root)에 의해 미리

고정된 실제 경로(virtual path)이어야 함.

• mode




o 설명: File 객체로부터 도달할 수 있는 모든 파일과 디렉토리에

대하여 읽기전용 액세스 획득을 위한 “r” 값 또는 읽기 및 쓰기

액세스를 획득하기 위한 “rw”의 선택가능 문자열(optional string)은

successCallback 으로 간주된다. 없거나 null 인 경우 "rw"를

디폴트로 함.


이 요청을 취소할 수 있는 PendingOperation.

예외

• DeviceAPIError:




106 TTAK.OT-10.0323

코드 예

다. File

파일 클래스.

[NoInterfaceObject] interface File {

readonly attribute File parent;

readonly attribute boolean readOnly;

readonly attribute boolean isFile;

readonly attribute boolean isDirectory;

readonly attribute Date created;

readonly attribute Date modified;

readonly attribute DOMString path;

readonly attribute DOMString name;

readonly attribute DOMString fullPath;

readonly attribute long fileSize;

readonly attribute long length;

DOMString toURI()


PendingOperation listFiles(in FileSystemListSuccessCallback successCallback,


in optional FileFilter filter)


PendingOperation openStream(in FileOpenSuccessCallback successCallback,


in DOMString mode,

[TreatUndefinedAs=Null] in optional DOMString? encoding)



function(dir) {

alert("Mount point Name is " + dir.name);

}, function(e) {

alert(e.message);

}, 'images', 'r'

);


107 TTAK.OT-10.0323

PendingOperation readAsText(in ReadFileAsStringSuccessCallback


[TreatUndefinedAs=Null] in optional DOMString? encoding)


PendingOperation copyTo(in SuccessCallback successCallback,


in DOMString originFilePath,

in DOMString destinationFilePath,

in boolean overwrite)


PendingOperation moveTo(in SuccessCallback successCallback,






File createDirectory(in DOMString dirPath)


File createFile(in DOMString filePath)


File resolve(in DOMString filePath)


PendingOperation deleteDirectory(in SuccessCallback successCallback,


in DOMString directory,

in boolean recursive)


PendingOperation deleteFile(in SuccessCallback successCallback,


in DOMString file)


};


108 TTAK.OT-10.0323

본 인터페이스는 사용 중인 파일 추상화(abstraction)를 나타낸다. file handle 은

파일 및 디렉토리 주소를 지정할 수 있다. file handle 은 isFile 속성이 true 인 경우

파일을 나타내고, isFile 속성이 false 인 경우에는 디렉토리를 나타낸다.

파일 객체 위치 및 그 위치에 기반한 트리(tree)에 대한 파일 객체 읽기 및 쓰기

허가는 resolve method 에 정의되는 모드에 따라 달라진다 (읽기전용: "r" 또는 읽기

및 쓰기: “rw"). 어떤 File 객체가 하위 File 객체를 생성하면, 새로운 File 객체는

File 의 일정 메소드에 기재된 바와 같이 보안 프레임워크를 참조하지 않고 부모

객체로부터 액세스 권한을 물려받는다.

파일을 나타내는 file handle 은 읽기 및 쓰기 등 I/O operation 에 대하여 개방될 수

있다.

디렉토리를 나타내는 file handle 은 그 file handle 위치와 같은 곳에 뿌리를 둔 모든

파일과 디렉토리 리스트작성에 이용할 수 있다.

코드 예

속성

readonly File parent

상위 디렉토리 핸들(Parent directory handle).

상위 디렉토리(parent directory)가 없는 경우 null.

상위 디렉토리(parent directory)가 없는 경우 이는 루트(root) 위치를 나타낸다.



for(var i = 0; i < files.length; i++) {

// alerts each name of dir's contents

alert(files[i].name);

}

}


alert("The error " + error.message + "

occurred when listing the files in the selected folder");

}

// list directory contents

dir.listFiles(successCB, errorCB);


109 TTAK.OT-10.0323

코드 예

readonly boolean readOnly

Filesystem 내의 파일/디렉토리 액세스 상태.

객체가 그 위치에서 읽기전용 액세스인 경우 true

객체가 그 위치에서 쓰기 액세스를 가지는 경우 false

이 속성은 filesystem 내에서 어떤 파일이나 디렉토리의 실제 상태를 나타낸다.

그 값은 이 File 객체가 획득된 File 객체를 생성하는 데 사용된

FileSystemManager.resolve 에 사용된 모드(mode)에 영향을 받지 않는다.






// alerts the file parent, should contain the

// same value for all the files in the loop

alert("All the files should have the same parent " +

files[i].parent);

}

}

function errorCB(error){

alert("The error " + error.message +

" occurred when listing the files in the selected folder");

}


110 TTAK.OT-10.0323

코드 예

readonly boolean isFile

파일 타입

이 handle 이 파일인 경우 true , 이 handle 이 디렉토리인 경우 false.


readonly boolean isDirectory

파일 타입

이 handle 이 디렉토리인 경우 true,

이 handle 이 파일인 경우 false,


readonly Date created

이 파일의 생성 타임스탬프(creation timestamp).





if(files[i].readOnly)

alert("Cannot write to file " + files[i].name);

else

alert("Can write to file " + files[i].name);

}

}


alert("The error " + error.message + " occurred when listing the files in

the selected folder");

}


111 TTAK.OT-10.0323

이것은 이 파일이 filesystem 내에서 생성될 때의 타임스탬프(timestamp)이다.

createFile()에 대한 호출이 성공했을 때의 타임스탬프와 동일함.

플랫폼이 이 속성을 지원하지 않는 경우 반드시 “미정의(undefined)”이어야 한다.

파일을 이동할 때 생성 타임스탬프가 변경되는 경우 이는 지정되지 않으며

플랫폼에 따라 달라진다.


readonly Date modified

수정 타임스탬프(Modification timestamp).

이 파일의 수정 타임스탬프(modification timestamp). 이것은 보통 마지막 쓰기

작업(operation)이 성공했을 때 가장 최근 수정한 타임스탬프이다. 읽기를 위해

파일을 열 때는 이 수정 타임스탬프가 변경되지 않는다.

플랫폼이 이 속성을 지원하지 않는 경우 반드시 미정의(undefined)이어야 한다.

파일을 이동할 때 수정 타임스탬프가 변경되는 경우 이는 지정되지 않으며

플랫폼에 따라 달라진다.


코드 예

readonly DOMString path

파일명을 제외한 이 파일의 경로.

이것은 그 파일을 포함하는 루트(root)의 이름에서 시작하여 그 파일명은

제외하고, 그 파일을 포함하는 디렉토리까지 포함한다,

루트(root) 자체를 나타내는 파일 등 특별한 경우를 제외하고, 마지막 문자는

항상 문자 '/'이다.

예를 들어, 어떤 파일이 music/ramones/volume1/RockawayBeach.mp3 에

위치하는 경우, 그 경로는 music/ramones/volume1/이다.

alert(file.modified); // displays the modification timestamp


112 TTAK.OT-10.0323

예를 들어, 어떤 디렉토리가 music/ramones/volume1 에 위치하는 경우, 그

경로는 music/ramones/이다.

루트가 music 인 경우 이 루트와 같은 특별한 경우는 경로가 music 이다.


코드 예

readonly DOMString name

모든 경로 컴포넌트를 제외한 파일명(File name).

이것은 루트 명과 다른 경로 컴포넌트를 제외한 이 파일의 이름이다.

예를 들어, 어떤 파일이 music/ramones/volume1/RockawayBeach.mp3 에

위치하는 경우, 그 이름은 RockawayBeach.mp3 이다.

예를 들어, 어떤 디렉토리가 music/ramones/volume1 에 위치하는 경우, 그

이름은 volume1 이다.

루트 자체인 특별한 경우에 대해서는, 그 이름이 빈 문자열(empty string)이다.


코드 예

readonly DOMString fullPath

파일의 전체 경로.

그 파일을 포함하는 루트명에서 시작하여 그 파일이나 디렉토리 자체의 이름을

포함하는 파일의 전체 경로(full path).

예를 들어, 어떤 파일이 music/ramones/volume1/RockawayBeach.mp3,에

위치하는 경우, 그 경로는 music/ramones/volume1/RockawayBeach.mp3 이다.

alert(file.path); // should be 'music/' if the file is music/foo.mp3

alert(file.name); // should be foo.mp3 if the file path is music/foo.mp3


113 TTAK.OT-10.0323

디렉토리에 대하여, 그 디렉토리가 music/ramones/volume1 에 위치하는 경우,

fullPath 는 music/ramones/volume1 이다.

그 루트가 music 인 경우 이 루트와 같은 특별한 경우에는 fullPath 가

music 이다.

fullPath 는 항상 경로 + 이름과 동일하다.


코드 예

readonly long fileSize

이 파일의 바이트 단위 크기(size).

어떤 디렉토리에서 이 속성을 읽으려고 하는 경우, undefined 가 리턴된다. 그

디렉토리에 포함된 파일과 디렉토리의 수를 구하기 위해서는, 대신에 길이

속성(length attribute)을 이용한다.


코드 예

readonly long length

이 File Handle 에 포함된 파일과 디렉토리의 수.

어떤 파일에서 이 속성을 읽으려고 하는 경우, undefined 가 리턴된다. 어떤

파일의 크기를 구하기 위해서는 대신에 fileSize 속성을 이용한다.


코드 예

alert(file.fullPath); // should be music/track1.mp3 if the file is

music/track1.mp3

alert(file.fileSize); // displays the file size

alert(file.length); // '3' if the directory contains two files and one sub-

directory


114 TTAK.OT-10.0323

Methods

toURI

파일에 대하여 URI 를 리턴한다.

서명

DOMString toURI();

이 엔트리(entry)를 식별하는 데 사용될 수 있는 URI 를 리턴한다 (e.g. 이것을

HTML img element 상의 src attribute 로 사용). 그 URI 는 특정

만기(expiration)가 없으며, 적어도 그 파일이 존재하는 한 유효해야 한다.

이 메소드가 호출되면, 구현은 반드시 URI 를 생성해야 한다.

그 URI 가 public virtual roots (i.e. images, videos, music, documents,

downloads and removable) 중 하나에 해당되는 경우, URI 는 반드시 전역에서

고유하고 모든 widget 에서 사용할 수 있어야 한다.

그 URI 가 widget 개별 구역(e.g. wgt-package, wgt-private, wgt-private-

tmp)에 위치하는 파일에 해당되는 경우, 생성된 URI 는 반드시 그 파일 및 그

요청을 한 widget 에 대하여 고유해야 한다 (e.g. 그 URI 의 widget id 로부터

유래된 몇 가지를 포함). URI 은 반드시 오퍼스케이트(obfuscate)되어 그

파일위치에 대한 어떤 정보도 제공하지 않아야 한다. 이들 URI 는 결코 이

메소드를 호출한 것과 다른 위젯(widget)에 접근 가능해서는 안 된다.


에러가 발생한 경우 그 파일이나 null 을 식별하는 URI.

예외

• DeviceAPIError:

이 기능이 지원되지 않는 경우 NOT_SUPPORTED_ERR 에러코드를 가짐.

다른 에러 상황에서는 UNKNOWN_ERR 에러코드를 가짐.

코드 예

// 'file://A123456ABCD/RockawayBeach.mp3' if the file is

// music/ramones/RockawayBeach.mp3

alert(file.toURI());


115 TTAK.OT-10.0323

listFiles

이 디렉토리의 모든 파일 리스트를 리턴한다.

서명

PendingOperation listFiles(in FileSystemListSuccessCallback successCallback,

in optional ErrorCallback errorCallback, in optional FileFilter filter);

파일 리스트는 successCallback 에서 FileArray 로서 유용한 형태이고 디렉토리와

파일을 포함한다. 그러나 "."와 ".." 디렉토리는 리턴되어서는 안 된다. 그

어레이의 각 파일 객체 부분은 반드시 이 메소드가 호출된 File 객체로부터 모든

액세스 권한 ("r" 또는 "rw" 모드)를 물려받아야 한다.

필터는 유효한 형태이고 유효한 값을 포함하는 경우, FileFilter 인터페이스에

지정된 필터 기준에 맞는 디렉토리에 있는 디렉토리와 파일만이 반드시

successCallback 에 리턴되어야 한다. 필터가 유효하지 않고, null 이거나 미정,

또는 유효하지 않은(invalid) 값을 포함하는 경우 구현은 반드시 디렉토리의 전체

파일 리스트를 리턴해야 한다.

그 디렉토리가 모든 파일 또는 디렉토리를 포함하지 않거나 그 필터 기준이 어떤

파일 또는 디렉토리와 맞지 않는 경우, successCallback 이 빈 어레이와 함께

호출될 것이다.



다른 에러 때문에 그 파일 리스트를 구할 수 없는 경우, 적절한 에러 코드와

함께 errorCallback 이 실시된다:

• IO_ERR: 작업이 파일에서 시작됨 (디렉토리가 아니라).


• SECURITY_ERR: 그 operation 이 허용되지 않는 경우.




errorCallback 이 유효한 기능을 포함하지 않거나 (예, null)), errorCallback 으로

리턴해야 하는 모든 오류의 경우 (위 참조) 구현은 반드시 조용히 실패하고 더

이상의 조치가 필요하지 않다 (예, 그 오류는 개발자에게 통지되지 않음).


116 TTAK.OT-10.0323

파라미터

• successCallback


o 타입: FileSystemListSuccessCallback.

o 설명: 리스트 작업(operation)이 성공적으로 완료되었을 때 호출됨.

• errorCallback




• filter


o 타입: FileFilter.

o 설명: 리스트에 기재된 필터를 제한하는 데 사용됨.


이 요청을 취소하기 위한 requester 를 가능하게 하는 PendingOperation

예외

• DeviceAPIError:



코드 예


alert("There are " + files.length + " in the selected folder");

}



selected folder");

}


function(dir){

dir.listFiles(successCB, errorCB)

}, function(e){


}, "documents", "r"

);


117 TTAK.OT-10.0323

openStream

주어진 encoding 을 지원하는 주어진 모드(model) 내의 파일을 연다.

서명


in ErrorCallback errorCallback, in DOMString mode, in optional DOMString?

encoding);

이 작업은 비동기로 실행된다. 파일이 성공적으로 열린 경우, mode 에 따라 그

파일의 읽기와 쓰기에 사용될 수 있는 FileStream 과 함께 successCallback 이

호출된다. return FileStream 인스턴스에는 그 파일의 현재 위치를 나타내는 file

pointer 가 포함된다. Filepointer 는 filepointer 가 파일의 끝을 가리키는 append

("a") mode 로 열리는 경우를 제외하고 디폴트로 파일의 시작 부분에 있게 된다.



다른 에러 때문에 그 파일을 열 수 없는 경우, 적절한 에러 코드와 함께

errorCallback 이 실시된다:

• INVALID_VALUES_ERR: 입력 파라미터 중 어떤 것이 유효하지 않은 값을

포함하는 경우 (예를 들어, 모드가 "a", "r" 또는 "w"과 다른 문자열인

경우), 그 encoding 은 유효하지 않거나 successCallback 이 null 이다.

개발자가 에러를 무시할 수 있도록, errorCallback 은 null 을 유효한


• IO_ERR: 작업이 (파일이 아닌) 디렉토리에서 시작되며, 파일이 유효하지

않거나 존재하지 않음.





리턴해야 하는 모든 오류의 경우 (위 참조) implementation 은 반드시 조용히

실패하고 더 이상의 조치가 필요하지 않다 (예, 그 오류는 개발자에게 통지되지

않음).


118 TTAK.OT-10.0323

파라미터

• successCallback


o 타입: FileOpenSuccessCallback.

o 설명: 파일이 열려있는 경우 호출됨.

• errorCallback




• mode




o 설명: 파일 열기에 대한 mode: 읽기는 "r", 붙여넣기(appending)는

"a", 쓰기는 "w"

• encoding




o 설명: 파일 상의 읽기/쓰기 operation 에 대한 encoding, 적어도

다음 인코딩은 반드시 지원되어야 함: "UTF-8" 디폴트 인코딩,

"ISO-8859-1" latin1 인코딩. 개발자에 의해 인코딩이 유효한

형태가 아닌 경우, 반드시 그 디폴트 플랫폼 인코딩을 사용해야

한다.



예외

• DeviceAPIError:




119 TTAK.OT-10.0323

코드 예




}

var testFile = documentsDir.createFile("test.txt");

if (testFile != null) {

testFile.openStream(

function(fs){

fs.write("HelloWorld");

fs.close();

}, function(e){


}, "w", "UTF-8"

);

}

}



selected folder");

}

var documentsDir;


function(dir){

documentsDir = dir; dir.listFiles(successCB,errorCB);

}, function(e) {



);


120 TTAK.OT-10.0323

readAsText

파일 내용을 DOMString 으로 읽는다.

서명



DOMString? encoding);

그 operation 이 성공적으로 실행된 경우 successCallback 이 호출되고

DOMString 은 인코딩 파라미터에 의해 결정되는 포맷(format)에서 파일 내용을

나타내는 입력 파라미터로서 유효한 형태를 가진다.



그 operation 이 실패한 경우 다음과 같은 적절한 에러 코드와 함께

errorCallback 이 호출된다:

• INVALID_VALUES_ERR: SuccessCallback 이 어떤 기능을 포함하지 않거나 (예를 들어 null) encoding 이 유효하지 않은 경우.

• IO_ERR: 작업이 (파일이 아닌) 디렉토리에서 시작되며, 그 파일이 유효하지 않거나 존재하지 않음.

• NOT_SUPPORTED_ERR: 이 feature 가 지원되지 않는 경우. • SECURITY_ERR: 그 operation 이 허용되지 않는 경우. • UNKNOWN_ERR: 다른 오류 사례 시.



실패하고 더 이상의 조치가 필요하지 않다 (예, 그 오류는 개발자에게 통지되지 않음).

파라미터

• successCallback

o 선택가능: 아니오. o 타입: ReadFileAsStringSuccessCallback. o 설명: 파일 읽기에 성공한 경우 호출됨.

• errorCallback

o 선택가능: 예. o 타입: ErrorCallback. o 설명: 파일 읽기 도중 에러가 발생한 경우.

• encoding

o 선택가능: 예. o 무효화가능(nullable): 아니오. o 타입: DOMString. o 설명: 파일 상의 읽기/쓰기 operation 에 대한 encoding, 적어도

다음 encoding 은 반드시 지원되어야 함: "UTF-8" default encoding, "ISO-8859-1" latin1 encoding. 개발자에 의해


121 TTAK.OT-10.0323

encoding 이 유효한 형태가 아닌 경우, 반드시 그 디폴트 플랫폼 encoding 을 사용해야 한다.


++이 요청을 취소하기 위한 requester 를 가능하게 하는 PendingOperation

예외

• DeviceAPIError:



코드 예




if (files[i].isDirectory == false)

files[i].readAsText(

function(str){

alert("The file content " + str);

}, function(e){


}, "UTF-8"

);

}

}



elected folder");

}

var documentsDir;


function(dir){

documentsDir = dir;

dir.listFiles(successCB,errorCB);

}, function(e) {



);


122 TTAK.OT-10.0323

copyTo

지정된 위치로부터 파일이나 디렉토리를 다른 지정된 위치로 복사 (및 지정 및

가능한 경우 덮어쓰기)한다.

서명

PendingOperation copyTo(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString originFilePath, in DOMString

destinationFilePath, in boolean overwrite);

originFilePath 파라미터에 의해 식별되는 파일이나 디렉토리 복사하기(copy)는

반드시 destinationFilePath 파라미터에서 유효한 형태를 가지는 경로에서

생성되어야 한다.

복사되는 파일이나 디렉토리는 반드시 메소드가 호출되는 디렉토리 아래에

있어야 하고, 그렇지 않은 경우 그 operation 은 결코 실행되어서는 안 된다.

복사하기가 성공적으로 실행된 경우, successCallback 이 호출된다.



이 기능이 다른 이유로 실패한 경우 다음과 같은 적절한 에러코드와 함께 error

callback 이 호출된다:

• INVALID_VALUES_ERR: 입력 파라미터 중 어떤 것이 유효하지 않은 값을

포함하는 경우. 예를 들어 successCallback 이 null 인 경우. 개발자가

에러를 무시할 수 있도록, errorCallback 은 null 을 유효한 값으로

수용한다.

• NOT_FOUND_ERR: originFilePath 는 유효한 파일에 해당하지 않거나

destinationPath 가 유효한 경로가 아님.

• IO_ERR: copyTo 메소드가 호출된 파일이 (디렉토리가 아닌) 파일이고,

originFilePath 가 다른 프로세스에 의해 사용 중인 파일이나 디렉토리에

해당하며, overwrite 파라미터는 false 이고 destinationFilePath 는 기존

파일이나 디렉토리에 해당함.







123 TTAK.OT-10.0323


않음).

파라미터

• successCallback



o 설명: 파일이 복사된 경우 호출됨.

• errorCallback




• originFilePath




o 설명: origin full virtual 파일 또는 디렉토리 경로, 반드시 현재

디렉토리 아래에 있어야 함.

• destinationFilePath




o 설명: 새로운 full virtual 파일 경로.

• overwrite



o 타입: boolean.

o 설명: True 는 강제로 기존 파일에 덮어쓰기 함.

Return value


예외

• DeviceAPIError:




124 TTAK.OT-10.0323

코드 예

moveTo

지정된 위치로부터 다른 위치로 파일이나 디렉토리를 이동시킨다.

서명

PendingOperation moveTo(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString originFilePath, in DOMString

destinationFilePath, in boolean overwrite);

파일이나 디렉토리가 주어진 경로로 자동 이동(및 덮어쓰기가 가능하고 그렇게

지정된 경우에는 덮어쓰기)된다. 이 작업은 플랫폼에서 여분의 디스크 공간이




documentsDir.copyTo(function(){alert("file copied");},

null,

files[i].fullPath,

"images/backup/"+files[i].name,

false);

}

}




}

var documentsDir;


function(dir){

documentsDir = dir;


}, function(e) {



);


125 TTAK.OT-10.0323

필요하지 않기 때문에 copyTo 를 실행한 후 원래 파일을 삭제하는 것과는

다르다.

originFilePath 파라미터에 의해 식별되는 파일 또는 디렉토리가 반드시

destinationFilePath 파라미터에서 유효한 형태를 가지는 경로로 이동되어야 한다.

이동되는 파일은 반드시 메소드가 호출되는 디렉토리 아래에 있어야 하고,

그렇지 않은 경우 그 operation 은 결코 실행되어서는 안 된다.

파일이나 디렉토리가 성공적으로 이동된 경우, successCallback 이 호출된다.



이 기능이 다른 이유로 실패한 경우 다음과 같은 적절한 에러코드와 함께 error

callback 이 호출된다:

• INVALID_VALUES_ERR: 입력 파라미터 어떤 것이 유효하지 않은 값을



수용한다.

• NOT_FOUND_ERR: originFilePath 는 유효한 파일에 해당하지 않거나

destinationPath 가 유효한 경로가 아닌 경우.

• IO_ERR: moveTo 메소드가 호출된 파일이 (디렉토리가 아닌) 파일이고,

originFilePath 가 다른 프로세스에 의해 사용 중인 파일이나 디렉토리에

해당하며, overwrite 파라미터는 false 이고 destinationFilePath 는 기존

파일이나 디렉토리에 해당함.







않음).


126 TTAK.OT-10.0323

파라미터

• successCallback



o 설명: 파일이 이동된 경우 호출됨.

• errorCallback




• originFilePath




o 설명: origin full virtual 파일 또는 디렉토리 경로, 반드시 현재

디렉토리 아래에 있어야 함.

• destinationFilePath




o 설명: 새로운 full virtual 파일 경로.

• overwrite



o 타입: boolean.

o 설명: True 는 강제로 기존 파일에 덮어쓰기 함.



예외

• DeviceAPIError:




127 TTAK.OT-10.0323

코드 예

createDirectory

새로운 디렉토리를 만든다.

서명

File createDirectory(in DOMString dirPath);

이 operation 이 실행되는 현재 디렉토리에 새로운 디렉토리가 생성된다.

Implementation 은 dirPath 에서 지정된 모든 필수 하위-디렉토리 생성을

시도한다. 경로 컴포넌트(path component)에서 "." 또는 ".." 사용은 지원되지

않는다.




documentsDir.moveTo(function(){alert("file moved");},

null,

files[i].fullPath,

"images/newFolder/"+files[i].name,

false);

}

}




}

var documentsDir;


function(dir){

documentsDir = dir;


}, function(e) {



);


128 TTAK.OT-10.0323

이 operation 은 디렉토리를 나타내는 File handlers 에서만 실행될 수 있다 (i.e.

isDirectory == true).

디렉토리가 성공적으로 생성되면, 이것이 리턴될 것이다.

디렉토리를 만들 수 없는 경우, 적절한 에러 코드와 함께 에러가 발생해야 한다.

파라미터

• dirPath




o 설명: 관련 디렉토리 경로, 근원적인 filesystem 에 의해 지원되는

문자만을 포함해야 한다.


새로운 디렉토리의 file handle. createDirectory() 메소드가 호출된 File

객체로부터 액세스 권리를 물려받기 때문에, 새로운 File 객체는 "rw" 액세스를

가지게 된다.

예외

• DeviceAPIError:

입력 파라미터가 기대되는 타입과 맞지 않는 경우


dirPath 가 유효한 경로를 가지지 않는 경우 INVALID_VALUES_ERR 에러

코드를 가짐.

dirPath 가 이미 존재하는 경우 IO_ERR 에러 코드를 가짐.


코드 예

var newDir = dir.createDirectory("newDir");

var anotherNewDir = dir.createDirectory("newDir1/subNewDir1");


129 TTAK.OT-10.0323

createFile

지정된 위치에서 새로운 빈 파일을 생성한다.

서명

File createFile(in DOMString filePath);

Operation 이 실행된 현재 디렉토리와 관련한 주어진 경로에서 새로운 빈 파일이

생성된다. 경로 컴포넌트(path component)에서 "." 또는 ".." 사용은 지원되지

않는다.

이 operation 은 디렉토리를 나타내는 File handlers 에서만 실행될 수 있다 (i.e.

isDirectory == true).

파일이 성공적으로 생성된 경우, File handler 는 반드시 이 메소드로 리턴되어야

한다.

파일을 만들 수 없는 경우, 적절한 에러 코드와 함께 에러가 발생해야 한다.

파라미터

• filePath

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: DOMString. o 설명: 새로운 파일 경로, 근원적인 filesystem 에 의해 지원되는

문자만을 포함해야 한다.


새로운 빈 파일의 file handle. createFile() 메소드가 호출된 File 객체로부터

액세스 권리를 물려받기 때문에, 새로운 File 객체는 "rw" 액세스를 가지게 된다.

예외

• DeviceAPIError:

입력 파라미터가 기대되는 타입과 맞지 않는 경우


filePath 가 유효하지 않은 값을 포함하는 경우 INVALID_VALUES_ERR

에러 코드를 가짐.

filePath 가 이미 존재하는 경우 IO_ERR 에러 코드를 가짐.


130 TTAK.OT-10.0323


코드 예

resolve

이 operation 이 실행되는 현재 디렉토리와 관련하여 기존 파일이나 디렉토리를

분해함; 그에 대한 file handle 을 리턴함.

서명

File resolve(in DOMString filePath);

The filePath is not allowed to contain the "." or ".." directories.

The encoding of file paths is UTF-8.

파라미터

• filePath




o 설명: 분해대상 관련 파일/디렉토리


그 파일의 file handle. 새로운 File 객체는 resolve() 메소드가 호출된 File

객체로부터 액세스 권리를 물려받게 된다.

예외

• DeviceAPIError:

파일이 유효한 파일 경로에 존재하지 않는 경우 NOT_FOUND_ERR

코드를 가짐.

메소드가 디렉토리를 나타내지 않는 File 객체에서 실행되지 않는 경우

error code IO_ERR 를 가짐 (i.e. isDirectory 속성은 false 이다).

var newFile = dir.createFile("newFilePath");


131 TTAK.OT-10.0323

File Path 가 유효하지 않은 값을 포함하는 경우 INVALID_VALUES_ERR

에러 코드를 가짐.




코드 예

deleteDirectory

지정된 경우, 지정된 디렉토리와 디렉토리 트리를 제거한다.

서명

PendingOperation deleteDirectory(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString directory, in boolean recursive);

이 기능은 현재 디렉토리 아래의 디렉토리 또는 디렉토리 트리를 비동기적으로

삭제한다.

recursive 파라미터가 true 로 기술되면, 지정된 디렉토리 아래의 모든 디렉토리와

파일은 반드시 삭제되어야 한다. recursive 파라미터가 false 로 기술되면,

디렉토리는 빈 경우에만 삭제되고, 그렇지 않은 경우 IO_ERR 에러 코드가

errorCallback 에서 유효한 형태를 가지게 된다.

삭제되는 디렉토리는 반드시 메소드가 호출되는 디렉토리 아래에 있어야 하고,

그렇지 않은 경우 그 operation 은 결코 실행되어서는 안 된다. 삭제하기가

성공적으로 실행된 경우, successCallback 이 호출된다.



var file;

// Resolves helloWorld.doc file that is located in the

// documents root location


function(dir){ file = dir.resolve("helloWorld.doc");},

function(e){ alert("Error" + e.message);},

'documents',

"rw");


132 TTAK.OT-10.0323

다른 이유로, operation 을 완료할 수 없는 경우, 적절한 에러 코드와 함께

errorCallback 이 반드시 호출되어야 한다.

• INVALID_VALUES_ERR 입력 파라미터 어떤 것이 유효하지 않은 값을



수용한다.

• NOT_FOUND_ERR: 유효한 형태를 가지는 디렉토리가 유효한 디렉토리에

해당하지 않음.

• IO_ERR: delete 메소드가 호출된 파일이 (디렉토리가 아닌) 파일이고, 그

디렉토리는 다른 프로세스가 사용 중이거나 디렉토리가 empty 상태가

아니고, recursive argument 는 false 임. recursive 삭제가 부분적으로

실패하고 그때까지 삭제된 데이터는 복구할 수 없는 경우 이 코드가

사용된다. 이는 filesystem 허가가 없거나 어떤 디렉토리 또는 파일이

다른 프로세스에 의해 열린 경우 발생할 수 있다.







않음).

파라미터

• successCallback

o 선택가능: 아니오. o 타입: SuccessCallback. o 설명: 디렉토리가 성공적으로 삭제된 경우 호출됨.

• errorCallback

o 선택가능: 아니오. o 타입: ErrorCallback. o 설명: 에러 발생 시 호출됨.

• directory

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: DOMString. o 설명: 삭제대상 디렉토리에 대한 full virtual 경로 (반드시 현재

디렉토리 아래에 있어야 함).

• recursive

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: boolean. o 설명: True 는 recursive 삭제를 의미하며, 이는 하위 디렉토리의

모든 데이터를 삭제하고, 경고 메시지를 이용한다.


133 TTAK.OT-10.0323



예외

• DeviceAPIError:



코드 예



if (files[i].isDirectory) documentsDir.deleteDirectory(

function(){

alert("File Deleted"); }, function(e) {


}, files[i].fullPath,

false);

else documentsDir.deleteFile(

function(){

alert("Directory Deleted"); }, function(e) {


}, files[i].fullPath);

);

} }

function errorCB(error) { alert("The error " + error.message + " occurred when listing the files in the

selected folder");

}

var documentsDir;

deviceapis.filesystem.resolve( function(dir){

documentsDir = dir;

dir.listFiles(successCB,errorCB); }, function(e) {


}, 'documents', 'rw' );


134 TTAK.OT-10.0323

deleteFile

지정된 파일을 삭제한다.

서명

PendingOperation deleteFile(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString file);

이 기능은 현재 디렉토리 아래의 파일을 비동기적으로 삭제한다.

삭제되는 파일은 반드시 메소드가 호출되는 디렉토리 아래에 있어야 하고,

그렇지 않은 경우 그 operation 은 결코 실행되어서는 안 된다.

삭제하기가 성공적으로 실행된 경우, successCallback 이 호출된다.



다른 이유로, operation 을 완료할 수 없는 경우, 적절한 에러 코드와 함께

errorCallback 이 반드시 호출되어야 한다.

• INVALID_VALUES_ERR: 입력 파라미터 s 어떤 것이 유효하지 않은 값을



수용한다.

• NOT_FOUND_ERR: 파일이 유효한 파일에 해당하지 않음.

• IO_ERR: delete 메소드가 호출된 파일이 (디렉토리가 아닌) 파일이고, 그

파일이 다른 프로세스가 사용 중이거나 file system 에 허가가 없음.







않음).

파라미터

• successCallback




135 TTAK.OT-10.0323

o 설명: 파일이 성공적으로 삭제된 경우 호출됨.

• errorCallback




• file




o 설명: 삭제대상 파일에 대한 full virtual 경로 (반드시 현재

디렉토리 아래에 있어야 함).



예외

• DeviceAPIError:



코드 예

function successCB(files) { for(var i = 0; files.length; i++) { if (files[i].isDirectory) documentsDir.deleteDirectory( function(){ alert("File Deleted"); }, function(e) { alert("Error" + e.message); }, files[i].fullPath, false); else documentsDir.deleteFile( function(){ alert("Directory Deleted"); }, function(e) { alert("Error" + e.message); }, files[i].fullPath); } } function errorCB(error) { alert("The error " + error.message + " occurred when listing the files in the elected folder"); } var documentsDir; deviceapis.filesystem.resolve( function(dir){ documentsDir = dir; dir.listFiles(successCB,errorCB); }, function(e){ alert("Error" + e.message); }, 'documents', 'rw' );


136 TTAK.OT-10.0323

라. FileFilter

listFiles 메소드에 의해 리턴된 항목을 필터링하기 위해 생성된 객체.

[Callback, NoInterfaceObject] interface FileFilter {


attribute Date startModified;

attribute Date endModified;

attribute Date startCreated;

attribute Date endCreated;

};

이 객체가 listFiles 메소드에서 유효한 형태를 가지는 경우 listFiles 메소드 의

결과-설정은 반드시 그 필터의 속성 값에 맞는 File item entry 만을 포함해야 한다.

File item 은 그 속성이 정의된 필터의 모든 속성값과 맞는 경우에만 FileFilter

객체와 맞는다 (i.e. 미정의(undefined) 또는 null 이외의 맞는 값). 이는 SQL "AND"

operation 과 유사하다.

File entry 의 속성은 다음 규칙에 따라 FileFilter 속성과 맞는다:

DOMString 타입의 FileFilter 속성의 경우, entry 는 그것이 exact match 속성에

해당될 때만 이 값과 맞는다. 필터가 U+0025 'PERCENT SIGN'을 포함하는 경우,

그것은 wildcard 문자로 해석되며 ‘%’는 모든 길이-길이 0 포함-의 모든 스트링과

맞는다. Wildcard 가 사용되면, behavior 는 SQL 의 LIKE 조건과 유사하다. 'PERCENT

SIGN' 문자를 wildcard 로서 해석하는 대신에 문자 그대로 고려하도록 지정하기

위해서는 개발자가 backslash 문자(\)로 빠져나갈 수 있다. 이 매칭(maching)은

민감한 경우가 아니다. 예를 들어 "FOO"는 "foo" 또는 "f%" 필터와 맞는다.

Date 타입(type) 파일 엔트리 속성의 경우, 제공된 두 개의 일자 사이에 파일

엔트리의 필터링을 허용하기 위하여 시작(start) 및 종료(end) 속성이 포함된다. 이들

속성 중 하나 또는 둘 다 지정되면, 다음 규칙을 적용한다: A) 시작(start) 및

종료(end) 일자가 모두 지정되면 (i.e. null 이외), File entry 는 그 해당속성이

시작(start) 또는 종료(end) 중 하나와 동일하거나 또는 제공된 두 개의 일자 사이에

있는 경우 그 필터와 맞는다. B) start 속성이 (null 이외의) 값을 포함하는 경우, File

entry 는 해당 속성이 시작일과 같거나 그 이후인 경우 그 필터와 맞는다. B)

end 일자가 (null 이외의) 값을 포함하는 경우, File 은 해당 속성이 시작일과 같거나

그 이전인 경우 그 필터와 맞는다.


137 TTAK.OT-10.0323

속성

DOMString name

File 이름 속성을 필터링(filtering)하기 위해 사용된다.

이름이 이 속성과 일치하는 파일 (정확하게 또는 특정 wildcards 와 함께)은 이

필터링 기준과 맞는다.

Date startModified

File 수정 속성을 필터링(filtering)하기 위해 사용된다.

이 속성 이후 또는 이와 동일한 수정된 일자를 가지는 파일이 필터링 기준에

맞는다.

Date endModified

File 생성 속성을 필터링(filtering)하기 위해 사용된다.

이 속성 이전 또는 이와 동일한 수정된 일자를 가지는 파일이 필터링 기준에

맞는다.

Date startCreated


이 속성 이후 또는 이와 동일한 수정된 일자를 가지는 파일이 필터링 기준에

맞는다.

Date endCreated


이 속성 이전 또는 이와 동일한 수정된 일자를 가지는 파일이 필터링 기준에

맞는다.

마. FileStream

FileStream API.

[NoInterfaceObject] interface FileStream {

readonly attribute boolean eof;


138 TTAK.OT-10.0323

attribute long position

setraises(DeviceAPIError);

readonly attribute long bytesAvailable;

void close();

DOMString read(in long charCount)


ByteArray readBytes(in long byteCount)


DOMString readBase64(in long byteCount)


void write(in DOMString stringData)


void writeBytes(in ByteArray byteData)


void writeBase64(in DOMString base64Data)


};

FileStream 은 읽기 및/또는 쓰기 작업을 위해 열린 파일에 대한 handle 을

나타낸다. 파일에서 현재 위치를 나타내는 포인터인 위치 속성(position attribute)와

관련하여 읽기와 쓰기 작업이 실행된다.

프로세싱 대상 이진법(binary) 및 텍스트(text)를 허용하는 일련의 읽기/쓰기

메소드 s 를 이용할 수 있다.

file stream 이 닫히면, 이 stream 에 시도된 모든 operation 이 표준 JavaScript

에러를 가져온다.

액세스 권한이 initial resolve() 메소드 또는 File interface 의 openStream()

메소드를 통해 수여될 것으로 기대되기 때문에 이 인터페이스의 읽기/쓰기

operation 은 어떤 보안 예외도 발생시키지 않는다. 따라서, 성공적으로 분해된 File

및 FileStream 에 실행된 모든 조치를 이을 것으로 기대된다. 이는 연속하는 비동기

호출을 피하고 잠재적으로 사용자에 대한 애플리케이션을 증가시킬 수 있다.


139 TTAK.OT-10.0323

속성

readonly boolean eof

현재 파일 포인터(pointer)가 파일 끝에 있는지 여부를 가리킨다.

true 인 경우, 이 속성은 파일 포인터가 파일 끝에 있다는 것을 나타낸다.

false 인 경우, 이 속성은 파일 포인터가 파일 끝에 있고 파일 내의 어딘가에

있을 수 있다는 것을 나타낸다.


코드 예

long position

읽기/쓰기를 위한 Get/set 스트림(stream) 위치

이 스트림 위치는 파일 시트림(file stream)의 시작으로부터 바이트(byte)의

오프셋이다. 그 스트림으로부터 읽거나 쓰는 작업을 호출하면, 이 위치

속성(position attribute)에 의해 정의된 바이트로부터 동작이 일어난다. 읽기 및

쓰기 작업이 성공하면, 스트림의 위치는 바이트 읽기(byte read)의 수로 진행된다.

읽기/쓰기 작업이 성공적이지 않으면, 스트림 위치가 변하지 않는다.

DeviceAPIError:

위치가 스트림 범위 밖에 주어지는 경우 IO_ERR 코드를 가짐.

코드 예

if(stream.eof) {

// file has been read completely

}

alert(stream.position); // displays current stream position

// alters current stream position to the begin of the file,

// like seek() in C

stream.position = 0;


140 TTAK.OT-10.0323

readonly long bytesAvailable

stream 으로부터 읽기 위하여 사용할 수 있는 byte 의 수를 리턴한다.

읽기를 위해 사용할 수 있는 byte 수는 다음 읽기 작업에서 읽을 수 있는

byte 의 최대량이다. 이는 위치 속성에 의해 나타나는 파일 포인터 이후 이용할

수 있는 바이트의 수에 해당한다.

Eof 가 true 인 경우 -1.


코드 예

Methods

close

이 FileStream 을 닫는다.

서명

void close();

모든 pending buffered 쓰기를 플러시(flush)하고 파일을 닫는다. 항상 계속된다.

pending writes 는 계속되지 않을 수 있다는 것에 유의한다.

코드 예

read

이 FileStream 으로부터 지정된 문자 수를 읽는다.

서명

DOMString read(in long charCount);

파일 포인터 위치 이후 지정된 문자 수를 읽고 이를 string 으로 리턴한다. Eof 가

true 인 경우 결과적인 string 길이는 charCount 보다 짧을 수 있다.

alert(stream.bytesAvailable); // displays the available bytes to be read

stream.close(); // closes this stream, no subsequent access to stream

allowed


141 TTAK.OT-10.0323

파라미터

• charCount



o 타입: long.

o 설명: 읽은 문자의 수.


문자열로 읽은 문자의 결과.

예외

• DeviceAPIError:



읽은 에러 코드, 예를 들어 stream 내의 byte 가 사용 중인 encoding 으로

decoding 될 수 없는 경우 IO_ERR 에러 코드를 가짐.

코드 예

readBytes

이 FileStream 으로부터 지정된 바이트 수를 읽는다.

서명

ByteArray readBytes(in long byteCount);

파라미터

• byteCount



o 타입: long.

o 설명: 읽은 바이트의 수.

var text = stream.read(file.fileSize);

stream.close();


142 TTAK.OT-10.0323


바이트 (또는 숫자) 열로서 읽은 바이트의 결과.

예외

• DeviceAPIError:



읽기 에러가 발생할 경우 IO_ERR 에러 코드를 가짐.

코드 예

readBase64

Base64 로 결과를 encoding 하면서 이 FileStream 으로부터 지정된 바이트의

수를 읽는다.

서명

DOMString readBase64(in long byteCount);

파라미터

• byteCount



o 타입: long.

o 설명: 읽은 바이트의 수.


문자열(string)을 encoding 하는 base64 로 읽은 문자의 결과.

// reads up to 256 bytes from the stream

var raw = stream.readBytes(256);

for(var i = 0; i < raw.length; i++) {

// raw[i] contains the i-th byte of the current data chunk

}


143 TTAK.OT-10.0323

예외

• DeviceAPIError:



읽기 에러가 발생할 경우 IO_ERR 에러 코드를 가짐.

코드 예

write

이 FileStream 이 지정된 DOMString 을 쓴다.

서명

void write(in DOMString stringData);

파라미터

• stringData




o 설명: 써지는 실제 문자열(actual string).

Exceptions

• DeviceAPIError:



쓰기 에러가 발생할 경우 IO_ERR 에러 코드를 가짐.

코드 예

// reads up to 256 bytes from the stream

var base64 = stream.readBase64(256);

var text = "Hello world";

stream.write(text);


144 TTAK.OT-10.0323

writeBytes

이 FileStream 에 대하여 지정된 바이트를 쓴다.

서명

void writeBytes(in ByteArray byteData);

파라미터

• byteData

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: 바이트 어레이 o 설명: 써지는 바이트 데이터 어레이.

예외

• DeviceAPIError:



쓰기 에러가 발생할 경우 IO_ERR 에러 코드를 가짐.

코드 예

writeBase64

지정된 base64 DOMString 을 바이트로 변환하고 그 결과를 이 FileStream 을

쓴다.

서명

void writeBase64(in DOMString base64Data);

파라미터

• base64Data

o 선택가능: 아니오. o 무효화가능(nullable): 아니오. o 타입: DOMString. o 설명: 써지는 base64 data

var bytes = in.readBytes(256);

out.writeBytes(bytes); // writes the bytes read from in to out


145 TTAK.OT-10.0323

Exceptions

• DeviceAPIError:



writeBase64 도중 쓰기 에러가 발생하면 IO_ERR 를 가짐.

코드 예

바. FileSystemSuccessCallback

File system success callback.

[Callback=FunctionOnly, NoInterfaceObject] interface FileSystemSuccessCallback

{

void onsuccess(in File file);

};

이 callback 인터페이스는 File 객체를 입력 인수(input argument)로 취하는 기능을

가지는 success callback 을 지정한다. 이는 FileSystemManager.resolve() 등의

비동기 작업과 파일 복사, 이동, 삭제 등에 사용된다.

Methods

onsuccess

비동기 콜을 성공적으로 완료할 때 호출되는 메소드

서명


Parameters

• file


o 타입: File.

o 설명: 비동기 호출 결과로 생성되는 파일.

var base64 = in.readBase64(256);

out.writeBase64(base64); // writes the base64 data read from in to out


146 TTAK.OT-10.0323

사. ReadFileAsStringSuccessCallback

DOMString 으로 파일 내용을 읽는 Success callback.


ReadFileAsStringSuccessCallback {

void onsuccess(in DOMString fileStr);

};

이 callback 인터페이스는 DOMString 객체를 입력 인수(input argument)로 취하는

기능을 가지는 success callback 을 지정한다. 이는 File.readFileAsString() 등의

비동기 operation 에 사용된다.

Methods

onsuccess


서명


Parameters

• fileStr




o 설명: 비동기 호출로부터 생성되는 DOMString 으로 나타낸 파일.

아. FileOpenSuccessCallback

raw access 를 위하여 파일을 열기 위한 Success callback

[Callback=FunctionOnly, NoInterfaceObject] interface FileOpenSuccessCallback {

void onsuccess(in FileStream filestream);

};

이 callback 인터페이스는 FileStream 객체를 입력 인수(input argument)로 취하는

기능을 가지는 success callback 을 지정한다. 이는 File.openStream() 등의 비동기

동작에 사용된다.


147 TTAK.OT-10.0323

Methods

onsuccess

File.openStream 비동기 콜을 성공적으로 완료할 때 호출되는 메소드

서명


파라미터

• filestream

o 선택가능: 아니오. o 타입: FileStream. o 설명: 파일 내용에 접근하는 filestream.

자. FileSystemListSuccessCallback

listing methods 에 대한 File system 특이적 success callback.


FileSystemListSuccessCallback {

void onsuccess(in FileArray files);

};

이 콜백 인터페이스는 File 객체의 어레이를 입력인수(input argument)로 취하는

기능을 가지는 success callback 을 지정한다. 이는 파일 listing 등의 비동기

메소드에 사용된다.

Methods

onsuccess


서명


파라미터

• files

o 선택가능: 아니오. o 타입: 파일 어레이(FileArray) o 설명: 비동기 호출 결과로 생성되는 파일들.


148 TTAK.OT-10.0323

차. DeviceAPIError

이 모듈에 대한 에러 코드를 정의한다.


const short IO_ERR = 100;

};

상수

short IO_ERR

입력/출력(input/output) 문제 때문에 작업을 완료할 수 없음.

4.6.5. Type Definitions

가. FileArray

파일 어레이.

typedef sequence<File> FileArray;

나. Byte어레이

8-비트 정수 값의 어레이.

typedef sequence<octet> ByteArray;

4.6.6. Features

다음 feature:

• http://wacapps.net/api/filesystem

또는 그 feature 아래의 속성 중 어떤 것이 효과적으로 요청되면,

FileSystemManager 인터페이스가 예시되고, 그 결과로 나타나는 대상은 글로벌

namespace 에 deviceapis.filesystem 으로 나타난다.



http://wacapps.net/api/filesystem.read


149 TTAK.OT-10.0323

다음 메소드를 제외한 모든 모듈에 대한 액세스: copyTo(), moveTo(),

createDirectory(), createFile(), deleteDirectory(), deleteFile() 및 쓰기

모드("w")를 가지는 openStream.

http://wacapps.net/api/filesystem.write

다음 메소드를 제외한 모든 모듈에 대한 액세스: readAsText() 및 읽기

모드("r")를 가지는 openStream.

http://wacapps.net/api/filesystem

이 모듈에 대한 모든 features 에 액세스.

4.6.7. Full WebIDL

module filesystem {





};







[TreatUndefinedAs=Null] in optional DOMString? mode)


};









150 TTAK.OT-10.0323






DOMString toURI()


PendingOperation listFiles(in FileSystemListSuccessCallback

successCallback,






in DOMString mode,


encoding)



successCallback,



encoding)













151 TTAK.OT-10.0323
















in DOMString file)


};







};







152 TTAK.OT-10.0323

void close();













};


FileSystemSuccessCallback {


};




};

[Callback=FunctionOnly, NoInterfaceObject] interface FileOpenSuccessCallback

{


};





153 TTAK.OT-10.0323

};



};

};


154 TTAK.OT-10.0323

4.7. 메시징(messaging) 모듈

4.7.1. 요약

Messaging API

4.7.2. 인터페이스및 메소드 요약


DeviceapisMessaging

Messaging Message createMessage(short type)

PendingOperation sendMessage(SuccessCallback

successCallback, ErrorCallback errorCallback, Message

message)

PendingOperation sendMessage(MessageSendCallback

successCallback, ErrorCallback errorCallback, Message

message)

PendingOperation

findMessages(FindMessagesSuccessCallback


MessageFilter filter)

long onSMS(OnIncomingMessage messageHandler)

long onMMS(OnIncomingMessage messageHandler)

long onEmail(OnIncomingMessage messageHandler)

void unsubscribe(long subscriptionHandler)

Message PendingOperation

update(UpdateMessageSuccessCallback


MessageFilter

MessageAttachment

FindMessagesSuccessCallback void onsuccess(MessageArray messages)

UpdateMessageSuccessCallback void onsuccess(Message message)

OnIncomingMessage void onevent(Message message)

MessageSendCallback void onsuccess()

void onmessagesendsuccess(DOMString recipient)

void onmessagesenderror(DeviceAPIError error,

DOMString recipient)


155 TTAK.OT-10.0323

4.7.3. 서문

메시징 API(Messaging API)는 다음 기능에 대한 접근을 가능하게 해 준다::

• SMS, MMS, 이메일 등의 다른 기술을 통한 메시지 전송.

• 다른 폴더(folder)에 있는 메시지 검색.

• 착신 메시지 이벤트(incoming message events) 통지를 받기 위한

서명(subscription).

API 는 메시지나 폴더의 관리를 허용하지 않는 읽기 전용 API 이다.

메시지(즉, MMS 혹은 이메일)에 파일을 첨부하기 위해, 개발자는 사용될 최상위

로케이션(root location)을 보여주면서 http://wacapps.net/api/filesystem.read 에

접근할 것이라는 것을 분명히 밝혀야 한다. 그리고 메시지에 첨부된 파일을 읽기

위해서는 개발자가 특정한 최상위 로케이션(“첨부 파일”)을 밝혀야 한다.


가. DeviceapisMessaging

이는 deviceapis 객체(object)에서 실행되고 있는 것에 대해 정의한다.

[NoInterfaceObject] interface DeviceapisMessaging {

readonly attribute Messaging messaging;

};

Deviceapis implements DeviceapisMessaging;

메시징 모듈(messaging module)의 기능에 대한 접근을 허용해 주는

deviceapis.messaging 객체가 있다.

나. 메시징(Messaging)

메시지 작성, 전송, 읽기, 기능.

[NoInterfaceObject] interface Messaging {

const short TYPE_SMS = 1;

const short TYPE_MMS = 2;

const short TYPE_EMAIL = 3;

const short FOLDER_INBOX = 1;

const short FOLDER_OUTBOX = 2;

const short FOLDER_DRAFTS = 3;

const short FOLDER_SENTBOX = 4;


156 TTAK.OT-10.0323

Message createMessage(in short type)


PendingOperation sendMessage(in SuccessCallback successCallback,


in Message message)


PendingOperation sendMessage(in MessageSendCallback successCallback,


in Message message)


PendingOperation findMessages(in FindMessagesSuccessCallback


in optional MessageFilter filter)


long onSMS(in OnIncomingMessage messageHandler)


long onMMS(in OnIncomingMessage messageHandler)


long onEmail(in OnIncomingMessage messageHandler)


void unsubscribe(in long subscriptionHandler)


};

이 인터페이스는 createMessage() 메소드(method)를 통해 웹 애플리케이션에서

메시지를 작성하도록 해준다. 작성된 메시지는 Message 인터페이스의

예(인스턴스)로써 리턴(return)된다. 메시지는 Message 인터페이스가 제공하는

기능을 통해 처리되며, sendMessage() 메소드를 통해 전송된다.


157 TTAK.OT-10.0323

API 를 통해 작성되는 메시지는 sendMessage() 메소드를 사용하며, 메시지를

보내려는 시도를 할 때까지 디바이스의 메모리에 기억되지 않는다. sendMessage()

메소드를 실행하면, 메시지는 sent 및 draft 와 같은 명령에 따라 관련 폴더에

저장된다. 이 폴더로부터 메시지에 접근하기 위해서는 findMessages 메소드가

사용된다.

이 인터페이스는 착신 메시지 이벤트(incoming message event)의 통지에 서명

등록하는 메소드(method)를 제공해 준다.

주요 예




}




}


var msg =



msg.to = ["+34666666666"];

// Send request

deviceapis.messaging.sendMessage(messageSent, messageFailed, msg);


158 TTAK.OT-10.0323

상수(Constants)

short TYPE_SMS

SMS 타입의 메시지 식별자(Identifier for messages of type SMS)

short TYPE_MMS

MMS 타입의 메시지 식별자(Identifier for messages of type MMS)

short TYPE_EMAIL

이메일 타입의 메시지 식별자(Identifier for messages of type Email)

short FOLDER_INBOX

메시지 인박스 식별자(Identifier for the message inbox)

short FOLDER_OUTBOX

메시지 아웃박스 식별자(Identifier for the message outbox)

short FOLDER_DRAFTS

메시지 드래프트 폴더 식별자(Identifier for the message draft folder)

short FOLDER_SENTBOX

메시지 센트 아이템 폴더 식별자(Identifier for the message sent-items folder)

메소드(Methods)

createMessage

특정 형태의 메시지 작성(Create a message of a given type)

서명

Message createMessage(in short type);

Parameters

• 타입(type)

o 옵션(Optional): No.

o 눌러블(Nullable): No.

o 타입: 짧음(short)

o 설명: 작성되는 메시지 타입. 가능한 값은 TYPE_SMS,

TYPE_MMS 와 TYPE_EMAIL 임.


159 TTAK.OT-10.0323


특정 타입의 메시지 객체(message object), 혹은 메시지 작성 시 문제가 발생할

경우 0.

예외

• DeviceAPIError:

입력 파라미터(입력 파라미터)가 예상되는 파라미터의 타입과 맞지 않는

경우, 에러 코드(error code)는 TYPE_MISMATCH_ERR 임.

입력 파라미터에 유효하지 않은 값이 포함되는 경우, 에러 코드는

INVALID_VALUES_ERR 임.

코드의 예(Code example)

sendMessage

정의된 메시지를 전송하려는 시도

서명

PendingOperation sendMessage(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in Message message);

메시지 타입이 이메일로 설정되고 사용자가 복수의 이메일 계정을 가진 경우,

런타임(runtime)은 디폴트 이메일 계정(디폴트 e-mail account)을 사용해야 한다.

이메일 계정이 설정되지 않은 경우, 런타임은 새로운 이메일 계정을 만들거나

특정 ErrorCallback 을 요청 위젯으로 돌려 보내는 메카니즘을 제공할 수 있다.

특정 기술의 지원을 받으면서 개발자가 설정할 수 있는 유일한 파라미터가 다음

표에서 설명한 것처럼 전송된다(나머지는 무시됨) (Message 인터페이스 속성에

대한 정의 참조).

속성 SMS MMS 이메일

to Yes Yes Yes

body Yes Yes Yes

subject No Yes Yes

attachments No Yes Yes

cc No No Yes

bcc No No Yes

priority No No Yes

var msg =


msg.body = "WAC first SMS message.";


160 TTAK.OT-10.0323

메시지 전송이 성공하거나 실패할 경우, 이 메시지는 해당 폴더(메시지가

성공적으로 전송되는 경우에는 보낸 메시지함 폴더)에 저장된다. 수신자가

다수인 경우 일부 플랫폼에서는 SMS 혹은 MMS 과 같은 메시징 기술을 통해

메시지 복사본을 여러 개로 만들어 보관할 수도 있다.

이러한 작업이 완전히 끝나게 되는 경우(즉, 이로 인해 모든 수신자들에게 전송

작업이 끝나는 경우), 모든 수신자에게 메시지가 성공적으로 전송되면

successCallback 의 onsuccess 메소드가 호출(invoke)된다. 메시징 기술에 따라

다르지만, 메시지가 다수의 수신자에게 보내지는 경우라도 메시지는 메시징

서버(messaging server)에게 한 번만 전송되고 이에 따라 모든 수신자들에게

하나의 결과만 제공된다.

입력 파라미터가 예상되는 파라미터의 타입과 맞지 않을 경우,

TYPE_MISMATCH_ERR 코드를 가진 DeviceAPIError 예외가 발생된다.

다른 이유로 이 작업이 실패할 경우, 해당되는 에러 코드(error code)와 함께

errorCallback 이 호출된다.

• INVALID_VALUES_ERR: 입력 파라미터의 어느 하나에 유효하지 않은 값이

포함되는 경우. 예를 들면, successCallback 이나 메시지의 값이 0 이거나

혹은 메시지가 그 속성 중 어느 하나에 유효하지 않은 값을 포함하고

있는 경우임. 개발자가 에러를 무시하도록 허용하기 위해 errorCallback

는 유효한 값으로써 0 을 받아 들임.

• NOT_SUPPORTED_ERR: 규정된 메시징 기술이 지원되지 않는 경우.

• SECURITY_ERR: 작업(operation)이 허용되지 않는 경우.

• UNKNOWN_ERR: 다른 에러가 발생하는 경우.

errorCallback 이 유효한 함수(즉, 0)를 포함하지 않는 경우 혹은

errorCallback 으로 리턴(return)되어야 하는 다른 에러가 발생하는 경우(위의

설명 참조), 그 실행(implementation)은 실패한 것이 되어야 한다. 그러나 다른

행동을 추가로 할 필요는 없다(즉, 개발자는 에러에 대한 통지를 받지 못함).


161 TTAK.OT-10.0323

파라미터(Parameters)

• successCallback


o 타입(Type): SuccessCallback.

o 설명: 메시지가 성공적으로 전송될 경우 호출됨.

• errorCallback



o 설명: 전송 요청이 실패할 경우 호출됨.

• message


o 타입: 메시지.

o 설명: 전송되는 메시지.

러턴 값(Return value)

비동기식 명령(asynchronous call)을 취소하기 위한 PendingOperation.

예외

• DeviceAPIError:

입력 파라미터(input parameter)가 예상되는 파라미터의 타입과 맞지 않는





alert("The SMS has been sent to all the recipients"); }

// Define the error callback function messageFailed(error) {


}


var msg = deviceapis.messaging.createMessage(deviceapis.messaging.TYPE_SMS);


msg.to = ["+34666666666", "+34888888888"];

// Send request

deviceapis.messaging.sendMessage(messageSent, messageFailed, msg);


162 TTAK.OT-10.0323

sendMessage

개별 수신자(Per-recipient)에 대한 통지와 함께 규정된 메시지를 전송하려는

시도.

서명

PendingOperation sendMessage(in MessageSendCallback successCallback, in

ErrorCallback errorCallback, in Message message);

메시지 타입이 이메일로 설정되고 사용자가 복수의 이메일 계정을 가진 경우,

런타임(runtime)은 디폴트 이메일 계정(디폴트 e-mail account)을 사용해야 한다.

이메일 계정이 설정되지 않은 경우, 런타임은 새로운 이메일 계정을 만들거나

특정 ErrorCallback 을 요청 위젯으로 돌려 보내는 메카니즘을 제공할 수 있다.

특정 기술의 지원을 받으면서 개발자가 설정할 수 있는 유일한 파라미터가 다음

표에서 설명한 것처럼 전송된다(나머지는 무시됨)(Message 인터페이스 속성에

대한 정의 참조).

속성 SMS MMS Email

to Yes Yes Yes

body Yes Yes Yes

subject No Yes Yes

attachments No Yes Yes

cc No No Yes

bcc No No Yes

priority No No Yes

메시지 전송이 성공하거나 실패할 경우, 이 메시지는 해당 폴더(메시지가

성공적으로 전송되는 경우에는 보낸 메시지함 폴더)에 저장된다. 수신자가

다수인 경우 일부 플랫폼에서는 SMS 혹은 MMS 과 같은 메시징 기술을 통해

메시지 복사본을 여러 개로 만들어 보관할 수도 있다.

메시지가 모든 수신자에게 개별적으로 전송되는 기술의 경우, 개별

통지(individual notification)는 다음과 같이 지원되어야 한다: 목적지

리스트(destination list)에 있는 모든 개별 수신자의 경우로써 메시지가 이

리스트로 성공적으로 전송될 때, successCallback 아규먼트(argument)의

onmessagesendsuccess 메소드가 호출되어야 한다. 메시지가 수신자에게

전송되지 않는 경우에는 입력 파라미터로써 수신자 및 에러 코드와 함께

successCallback 아규먼트(argument)의 onmessagesendsuccess 메소드가


163 TTAK.OT-10.0323

호출되어야 한다. 그리고 에러 조건(error condition)에 따라 다음의 에러 코드가

나타날 수 있다:


포함되는 경우. 즉, successCallback 나 메시지의 값이 0 이거나 혹은

메시지가 그 속성 중 어느 하나에 유효하지 않은 값을 포함하고 있는

경우임. 개발자가 에러를 무시하도록 허용하기 위해 errorCallback 는

유효한 값으로서 0 을 받아 들임.


• SECURITY_ERR: 작업이 허용되지 않는 경우.


이러한 작업이 완전히 끝나게 되는 경우(즉, 이로 인해 모든 수신자들에게 전송

작업이 끝나는 경우)로써 모든 수신자에게 메시지가 성공적으로 전송되면

successCallback 의 onsuccess 메소드가 호출된다.

입력 파라미터(input parameter)가 예상되는 파라미터의 타입과 맞지 않을 경우,

TYPE_MISMATCH_ERR 코드를 가진 DeviceAPIError 예외가 발생된다. 다른

이유로 이 작업이 실패할 경우에는 해당되는 에러 코드(error code)와 함께

errorCallback 가 호출된다:


포함되는 경우. 예를 들면, successCallback 나 메시지의 값이 0 이거나

혹은 메시지가 그 속성 중 어느 하나에 유효하지 않은 값을 포함하고

있는 경우. 개발자가 에러를 무시하도록 허용하기 위해 errorCallback 은

유효한 값으로써 0 을 받아 들임.


• SECURITY_ERR: 작업이 허용되지 않는 경우.


errorCallback 이 유효한 함수(즉, 0)를 포함하지 않는 경우 혹은

errorCallback 으로 리턴(return)되어야 하는 다른 에러의 경우(위의 내용 참조),

그 실행(implementation)은 실패한 것이 되어야 한다. 그러나 다른 행동을

추가로 할 필요는 없다(즉, 개발자는 에러에 대한 통지를 받지 못함).

파라미터

• successCallback


o 타입: MessageSendCallback.

o 설명: 개별 통지 메소드를 포함함.


164 TTAK.OT-10.0323

• errorCallback



o 설명: 전송 요청이 실패하는 경우 호출됨.

• message


o 타입: Message.

o 설명: 전송되는 메시지


비동기식 명령(asynchronous call)을 취소하기 위한 PendingOperation.

예외

• DeviceAPIError:




// Define the send callback

var messageSendCallback = { onsuccess: function() {

alert("The SMS has been sent to all the recipients");},

onmessagesendsuccess: function(recipient) { alert("The SMS has been sent to " + recipient);},

onmessagesenderror: function(error, recipient) {

alert("The SMS has not been sent to " + recipient + " error " + error);}

};



alert("The SMS could not be sent " + error.message); }

// SMS sending example var msg =


msg.body = "I will arrive in 10 minutes"; msg.to = ["+34666666666", "+34888888888"];

// Send request deviceapis.messaging.sendMessage(messageSendCallback, messageFailed,

msg);


165 TTAK.OT-10.0323

findMessages

선택된 필터(filter)와 일치하는 메시지 폴더(message folder)로부터 메시지의

어레이(array of message)를 찾는 메소드(method)

서명



MessageFilter filter);

입력 파라미터(input parameter)가 예상되는 파라미터의 타입과 맞지 않는 경우,


이 피쳐(feature)가 지원되지 않는 경우, 코드 NOT_SUPPORTED_ERR 코드를

가진 DeviceAPIError 는 DeviceAPIError 로 리턴(return)되어야 한다. 이 기능이

허용되지 않는 경우에는 errorCallbackd 가 SECURITY_ERR 코드를 가진

DeviceAPIError 와 함께 호출되어야 한다.

successCallback 가 함수(즉, 0)를 포함하고 있지 않은 경우,

INVALID_VALUES_ERR 코드를 가진 DeviceAPIError 는 리턴(return)되어야 한다.

필터(filter)가 생기고 유효한 값을 가진다면, MessageFilter 인터페이스에서

설명한 필터 기준(filter criteria)과 일치하는 메시지 리스트에 있는 이들 값은

successCallback 으로 리턴된다. 그리고 필터가 나타나지 않고 그 값이 0 이거나

정해지지 않거나 유효하지 않은 값을 가지고 있는 경우에는 successCallback 에

있는 풀 메시지 리스트(full message list)을 리턴시켜야 한다. 메시지 리스트가

비어 있는 경우 혹은 필터 기준이 메시지와 일치하지 않는 경우, 빈

어레이(array)과 함께 successCallback 이 호출된다.

메시지 검색을 시도하다 다른 에러가 발생하는 경우, UNKONWN_ERR 코드를

가진 DeviceAPIError 객체를 포함하여 호출 과정에서 나타나는 errorCallback

기능이 실행되어야 한다.

errorCallback 이 호출되어야 하는 경우(위의 내용 참조)나 개발자가

ErrorCallback 을 제시하지 않거나 그 값이 ‘0’인 경우에는 어떤 행동도 필요하지

않다(즉, 개발자는 에러 통지를 받지 못함).

파라미터

• successCallback


o 타입: FindMessagesSuccessCallback.

o 설명: 호출이 성공적으로 종료될 요구되는 기능


166 TTAK.OT-10.0323

• errorCallback

o 옵션(Optional): Yes.


o 설명: 에러가 발생할 때 요구되는 기능

• filter


o 타입: MessageFilter.

o 설명: 필터링(filtering) 시 사용되어야 하는 메시지 데이터


비동기식 호(asynchronous call)을 취소하기 위한 PendingOperation.

예외

• DeviceAPIError:




var msg = { type:[deviceapis.messaging.TYPE_SMS], body:"first

messa%" };

deviceapis.messaging.findMessages(

function (messages) {

alert(messages.length + " message(s) found!");

for (var i=0; i<messages.length; i++) {

alert(i + ". message from " + messages[i].from);

}

},

null,

msg);


167 TTAK.OT-10.0323

onSMS

이 메소드(method)는 착신 SMS 메시지(incoming SMS message)의 통지 등록을

위한 메커니즘을 제공한다.

서명

long onSMS(in OnIncomingMessage messageHandler);

이 메소드가 호출되는 경우, 착신 SMS 가 도착할 때마다 호출되는 기능으로써

messageHandler 기능을 등록해야 한다.

가입(subscription)이 성공적으로 끝나면, 핸들러 식별자(identifier for handler)가

만들어져서 리턴된다. 이 식별자를 사용하여 서명이 취소될 수 있다. 이 가입이

성공적이지 않은 경우, 적절한 에러 코드가 있는 DeviceAPIError 예외가

발생된다.

파라미터

• messageHandler


o 타입: OnIncomingMessage.

o 설명: SMS 메시지가 들어올 때 호출되는 기능


서명 식별자(Subscription identifier).

예외

• DeviceAPIError:


경우, 에러 코드는 TYPE_MISMATCH_ERR 임.

messageHandler 가 ‘0’ 혹은 정의되지 않는 경우, 에러 코드는


작업이 허용되지 않는 경우, 에러 코드는 SECURITY_ERR 임.

이 피쳐(feature)가 지원되지 않는 경우, 에러 코드는

NOT_SUPPORTED_ERR 임.


168 TTAK.OT-10.0323


onMMS

이 메소드(method)는 착신 SMS 메시지(incoming MMS message)의 통지 등록을

위한 메커니즘을 제공한다.

서명

long onMMS(in OnIncomingMessage messageHandler);

이 메소드가 호출되는 경우에는 착신 MMS 가 도착할 때마다 호출되는 기능으로

써 messageHandler 기능을 등록해야 한다.

서명(subscription)이 성공적으로 끝나면, 핸들러 식별자(identifier for handler)가

만들어져서 리턴된다. 이 식별자를 사용하여 서명이 취소될 수 있다. 이 서명이

성공적이지 않은 경우, 적절한 에러 코드를 가진 DeviceAPIError 예외가

발생된다.

파라미터

• messageHandler



o 설명: MMS 메시지가 들어올 때 호출되는 기능

// function to receive new SMS notifications

function incomingSMS(message)

{

alert("New incoming SMS from " + message.from);

// The subscription is cancelled to prevent further notifications

if (mySMSListener != null)

deviceapis.messaging.unsubscribe(mySMSListener);

}

// Register listener for new SMS events

var mySMSListener = null;

mySMSListener = deviceapis.messaging.onSMS(incomingSMS);


169 TTAK.OT-10.0323



예외

• DeviceAPIError:



messageHandler 가 ‘0’ 혹은 정의되지 않는 경우, 에러 코드는





코드의 예

// function to receive new MMS notifications

function incomingMMS(message)

{

alert("New incoming MMS from " + message.from);


if (myMMSListener != null)

deviceapis.messaging.unsubscribe(myMMSListener);

}

// Register listener for new MMS events

var myMMSListener = null;

myMMSListener = deviceapis.messaging.onMMS(incomingMMS);


170 TTAK.OT-10.0323

onEmail

이 메소드(method)는 착신 이메일 메시지(incoming email message)의 통지

등록을 위한 메커니즘을 제공한다.

서명

long onEmail(in OnIncomingMessage messageHandler);

이 메소드가 호출되는 경우, 착신 이메일이 도착할 때마다 호출되는 기능으로써

messageHandler 기능을 등록해야 한다.

서명(subscription)이 성공적으로 끝나면, 핸들러 식별자(identifier for handler)가

만들어져서 리턴된다. 이 식별자를 사용하여 서명이 취소될 수 있다. 이 서명이

성공적이지 않은 경우, 적절한 에러 코드를 가진 DeviceAPIError 예외가

발생된다.

파라미터

• messageHandler



o 설명: 이메일 메시지가 들어올 때 호출되는 기능.



예외

• DeviceAPIError:




messageHandler 가 0 혹은 정의되지 않는 경우. 에러 코드는





171 TTAK.OT-10.0323


서명 취소(unsubscribe)

. 이 메소드는 메시지 통지 서명의 취소를 허용한다.

서명

void unsubscribe(in long subscriptionHandler);

subscriptionHandler 아규먼트(argument)가 유효하고 이미 제시된 서명과

일치하는 경우, 서명 과정이 즉각 중단되어야 하며 메시지 통지(message

notification)가 추가로 호출되어서는 안 된다. 그리고 subscriptionHandler

아규먼트(argument)가 유효한 서명과 일치하지 않는 경우, 별도의 행동 없이 이

메소드는 리턴되어야 한다.

파라미터

• subscriptionHandler



o 타입: 김(long)

o 설명: onSMS(), onMMS(), onEmail() methods 에 의해 리턴되는

서명 식별자

// function to receive new Email notifications

function incomingEmail(message)

{

alert("New incoming Email from " + message.from);


if (myEmailListener != null)

deviceapis.messaging.unsubscribe(myEmailListener);

}

// Register listener for new Email events

var myEmailListener = null;

myEmailListener = deviceapis.messaging.onEmail(incomingEmail);


172 TTAK.OT-10.0323

예외

• DeviceAPIError:



다. Message

이는 메시지의 콘텐트(content)와 속성에 대해 정의한다.

[NoInterfaceObject] interface Message {


attribute short type;

attribute short folder;

readonly attribute Date timestamp;

readonly attribute DOMString from;

attribute StringArray to;

attribute StringArray cc;

attribute StringArray bcc;

attribute DOMString body;

attribute boolean isRead;

attribute boolean priority;

attribute DOMString subject;

attribute FileArray attachments;

PendingOperation update(in UpdateMessageSuccessCallback

successCallback,



};

이 인터페이스는 웹 애플리케이션이 메시징 인터페이스(Messaging Interface)에서의

createMessage() 메소드를 통해, 이전에 작성되었던 메시지와 링크(link)된 여러

가지 속성에 대해 정의할 수 있도록 해준다.

또한 애플리케이션이 findMessages, onSMS, onMMS, onEmail 등의 메소드를 통해

메시지의 콘텐트를 검색할 수 있도록 해준다. 그러나 이와 같이 실행한다고 해도 그

크기로 인해 전체의 일부분만 리턴시키는 경우도 있다. 이런 경우, 실행이 되더라도

개발자가 메시지(Message)에 의해 실행되는 동기화 인터페이스(Synchronisable


173 TTAK.OT-10.0323

interface)의 동기화 메소드 멤버(sync method member)를 사용하여 메시지의

나머지 부분을 검색할 수 있도록 허용해야 한다.

그리고 동일한 이유로 이와 같은 실행을 한다고 하더라고 첨부 내용이 아닌 첨부

정보만을 제공하도록 결정할 수 있어야 한다. 이는 MessageAttachments(동기화

인터페이스를 실행시킴)의 시퀀스(sequence)가 아닌 파일(File)의 시퀀스를

첨부파일 속성(attachments attribute)으로 리턴(return)시킴으로써 가능하다.

개발자가 메시징 기술(속성에 대한 설명이나 sendMessage mehtod description 에

있는 요약 표 참조)의 지원을 받지 않는 속성에 접근하려는 경우, 실행하면서

이러한 시도를 무시해야 한다.


var msg =


msg.body = "WAC first SMS message.";

msg.to = ["+34666666666"];

속성(Attributes)


메시지 단일 식별자(The message unique identifier).

이 속성은 메시지를 위한 단일 식별자이다.

id 는 디바이스나 웹 런타임(WRT)에서 부여 받은 유일하고 지속적인 속성을

가지고 있다. Messaging.createMessage()를 사용하여 작성되는 신규 메시지의

경우, send(), call to send() 등과 같은 기본 플랫폼에 의해 메시지가 처음으로

처리되는 경우에 id 를 부여 받는다. 디바이스의 전원이 켜져 있는 동안 이

속성은 유일한 속성이 된다.


short type

특정 메시지 타입

이는 다음 값 중의 하나일 수 있다:

• TYPE_SMS = 1, • TYPE_MMS = 2, • TYPE_EMAIL = 3.


174 TTAK.OT-10.0323

short folder

특정 메시지의 폴더 로케이션(folder location)

메소드를 통해 작성되는 메시지의 경우, 이 속성은 정의되지 않는다.

readonly Date timestamp

메시지의 타임 스탬프(timestamp)

이 속성은 디바이스나 웹 런타임 환경에 의해 설정된다.


readonly DOMString from

메시지의 소스 주소(source address).

이 속성은 디바이스나 웹 런타임 환경에 의해 설정되며, 이메일의 경우에만

적용되어야 한다.


StringArray to

메시지의 목적지(destination).

StringArray cc

메시지의 카본 카피(carbon copy) 주소.

이 속성은 이메일의 경우에만 적용되어야 한다..

StringArray bcc

메시지의 블라인드 카본 카피(blind carbon copy) 주소.

이 속성은 이메일의 경우에만 적용되어야 한다.

DOMString body

메시지 몸체(body).


175 TTAK.OT-10.0323

boolean isRead

이 메시지를 위한 “read” 플래그(flag).

메시지를 읽을 경우 이 속성은 참(true), 읽지 않을 경우에는 거짓(false)이 된다.

boolean priority

메시지의 우선 순위.

메시지가 최우선 순위일 경우 이 속성은 참(false), 우선 순위가 보통이나 낮을

경우에는 거짓(false)이 된다.

이 속성은 이메일의 경우에만 적용된다.

DOMString subject

메시지의 주체(subject).

이 속성은 MMS 와 이메일의 경우에만 적용되어야 한다.

FileArray attachments

메시지 첨부 파일(attachment) 리스트

개발자가 메시지를 작성하지 않았지만 findMessage, onMMS, onEmail 메소드를

통해 리턴(return)되는 경우, 첨부 파일은 API 를 통해서만 접근할 수 있는

“attachments” 파일 시스템 최상위 로케이션(root location)에 저장된다.

이 속성은 이메일과 MMS 의 경우에만 적용된다.

메소드(Methods)

update

메소드를 통해 검색된 메시지를 업데이트함.

서명

PendingOperation update(in UpdateMessageSuccessCallback successCallback,

in optional ErrorCallback errorCallback);

이 메소드는 특정 메시지 객체에 대한 모든 변경된 속성을 기본 시스템으로, 즉,

예를 들면 기본 메시징 데이터베이스(native messaging database)와 LDAP


176 TTAK.OT-10.0323

등으로 전송해 준다. 변경된 내용이 시스템으로 전송되지 않는 경우에는 실행 시

취소된다.

이 전송 명령이 내려질 때까지 계속 저장되지 않기 때문에 이 메소드는

createMessage 메소드를 통해 작성된 메시지를 업데이트 하지 않는다.

인박스(inbox)(deviceapis, messaging, FOLDER_INBOX),

아웃박스(outbox)(deviceapis.messaging.FOLDER_OUTBOX), 센트박스(sent

box)(deviceapis.messaging.FOLDER_SENTBOX)에 보관되어 있는 메시지의 경우,

실행으로 메시지 객체(Message object)의 isRead 속성만 변경되어야 한다.

드래프트 폴더(draft foldler)(deviceapis.messaging.FOLDER_DRAFTS)에

보관되어 있는 메시지의 경우, 실행으로 다른 속성도 업데이트할 수 있다.

그러나 이는 실제 실행 여부에 달렸으며, 기본 시스템에 의존한다.

실행으로 업데이트된 메시지 객체(Message object)가 메시지의 현재 상태를

나타내는 success callback 에 제공된다는 것이 확인되어야 한다. 개발자는 이

실행으로 인해 어떤 영역이 전송되고 또 어떤 영역이 전송되지 않았는지를

확인하기 위해 이전의 객체(former object)와 비교하는데 업데이트된 메시지를

사용할 수 있다.

입력 파라미터(input parameter)가 예상되는 파라미터의 타입과 맞지 않는 경우,


다른 이유로 이 작업이 실패할 경우, 해당되는 에러 코드(error code)와 함께

errorCallback 이 호출된다.

• 이 피쳐(feature)가 지원되지 않는 경우, NOT_SUPPORTED_ERR 코드를

가진 DeviceAPIError 는 errorCallback 으로 리턴되어야 한다.

• 이 기능이 허용되지 않는 경우, errorCallback 코드는 SECURITY_ERR

코드를 가진 DeviceAPIError 와 함께 호출되어야 한다.

• successCallback 이 유효하지 않은 값(즉, 0 혹은 정의되지 않은 값)을

가진 경우, INVALID_VALUES_ERR 코드를 가진 DeviceAPIError 는

리턴되어야 함.

• 메시지를 업데이트하는 동안 다른 에러가 발생하는 경우, UNKNOWN_ERR

코드를 가진 DeviceAPIError 객체를 포함하여 호출 과정에서 나타나는

errorCack 기능이 명령되어야 한다.

errorCallback 이 유효한 값을 갖지 않은 경우(즉, 0) 혹은 errorCallback 으로

리턴되어야 하는 에러가 발생하는 경우, 실행은 실패한 것이 되어야 한다.

그러나 다른 행동을 추가로 할 필요는 없다(즉, 개발자는 에러에 대한 통지를

받지 못함).


177 TTAK.OT-10.0323

파라미터

• successCallback


o 타입: UpdateMessageSuccessCallback.

o 설명: 메시지가 성공적으로 업데이트될 때 요구되는 기능

• errorCallback



o 설명: 에러가 발생할 때 요구되는 기능


비동기식 명령을 취소하기 위한 PendingOperation

예외

• DeviceAPIError:


경우의 TYPE_MISMATCH_ERR 코드를 가진 DeviceAPIError.

라. MessageFilter

메소드에 의해 리턴되는 항목(item)을 제한하는 데 사용되는 필터.

[Callback, NoInterfaceObject] interface MessageFilter {

attribute DOMString id;

attribute ShortArray type;

attribute ShortArray folder;

attribute Date startTimestamp;

attribute Date endTimestamp;

attribute DOMString from;






attribute boolean messagePriority;


};


178 TTAK.OT-10.0323

이 필터는 findMessages 작업을 하는 데 사용되며, 이 작업의 결과에는 필터 값과

일치하는 메시지 엔트리(Message entries)만 포함되어야 한다.

엔트리(entry)의 속성이 필터의 모든 속성과 일치하는 경우, 메시지 엔트리는 필터와

일치한다. 필터에 정의되지 않거나 ‘0’인 값이 포함되는 경우, 이는 무시될 수 있다.

즉, SQL 과 유사한 방식으로 검색이 실행된다.

메시지 엔트리 속성은 다음 규정에 따라 필터 값과 일치하게 된다:

• DOMString 타입 필터 속성의 경우, 이 속성이 필터의 속성과 정확히 일치하는

경우 엔트리(entry)는 이 값과 일치한다. 그러나 U+0025 'PERCENT SIGN' 등의

와일드 카드 문자(wildcard character)와 같은 와일드 카드가 사용되는 경우,

필터의 성질은 SQL(%는 길이가 ‘0’인 경우를 포함하여 모든 길이의 문자열에

사용할 수 있음)에서의 LIKE 조건과 비슷해진다. 'PERCENT SIGN' 문자를 와일드

카드로 해석하는 대신 글자로 간주해야 하는 것으로 정하기 위해 개발자들은

백슬래시(backslash) 문자(\)를 사용하여 이를 에스케이프(escape)할 수 있다.

이와 같은 일치에는 대소문자 구별이 필요 없다. 즉, “FOO”는 “foo” 혹은 “f%”

필터(filter)와 일치한다.

• StringArray 타입 필터 속성의 경우, DOMString 타입 필터에서 설명한 규정이

특정 어레이(Array) 내의 각각의 영역에 적용된다. Message 와 MessageFilter 의

필드 순서(field order)에서 생길 수 있는 차이를 고려하지 않으면, 포함된 모든

영역에 대한 검색은 SQL “AND” 작업과 유사하다.

• 숫자 타입(numeric type) WeblDL 어레이 필터 속성의 경우(즉, 타입), 상응하는

메시지 엔트리(Message entry) 속성이 모든 어레이 요소(array element)의 속성과

정확히 일치할 때에만 메시지 엔트리와 필터가 일치한다.

• 불 타입(boolen type) WebIDL 필터 속성의 경우(즉, isRead, messagePriority),

상응하는 메시지 엔트리 속성이 정확한 상태(즉, 참 혹은 거짓)를 보일 경우에만

메시지 엔트리가 필터와 일치한다.

• 다음 규정이 적용된다: A) 처음 및 마지막 날짜 모두 정의되는 경우(즉, ‘0’이

아닌 경우)로 이에 상응하는 속성이 제공된 두 날짜인 처음(initial) 혹은

마지막(end) 중의 하나이거나 이 둘 사이일 때(즉 처음 이후 마지막 이전), 파일

엔트리(File entry)는 필터와 일치한다. B)처음 속성(initial attribute)이 어떤

값(0 이 아닌 값)을 포함하고 있는 경우로 이에 상응하는 속성이 처음 속성보다

늦거나 같을 때, 파일 엔트리(File entry)는 필터와 일치한다. C)마지막 날짜(end

date)가 어떤 값(0 이 아닌 값)을 포함하고 있는 경우로 이에 상응하는 속성이

마지막 날짜(end date)보다 빠르거나 같을 때 파일 엔트리는 필터와 일치한다.


179 TTAK.OT-10.0323

속성(Property)

DOMString id

메시지 id 속성(Message id attribute)을 필터링(filtering)하는 데 사용됨.

정확히 일치하는 Id 속성(attribute id) 혹은 정의된 와일드 카드가 포함된 id

속성을 가진 메시지(Message). 제공된 필터 속성은 이 필터링 기준(filtering

criteria)과 일치함.

ShortArray type

메시지 타입(Message Type) 속성을 필터링(filtering)하는 데 사용됨.

이 필터 어레이(filter array)에서 제공하는 값 중의 하나와 일치하는 타입

속성(attribute type)을 가진 메시지는 이 필터링 기준(filtering criteria)과 일치한다.

ShortArray folder

메시지 폴더 (Message folder) 속성을 필터링(filtering)하는 데 사용됨.

이 필터 어레이에서 제공하는 값 중의 하나와 일치하는 폴더 속성(attribute

folder)을 가진 메시지는 이 필터링 기준(filtering criteria)과 일치한다.

Date startTimestamp

메시지 타임 스탬프(Message timestamp) 속성을 필터링하는 데 사용됨.

제공된 필터보다 시간적으로 늦거나 같은 타임 스탬프 속성(attribute

timestamp)을 가진 메시지는 이 필터링 기준과 일치한다.

Date endTimestamp

메시지 타임 스탬프(Message timestamp) 속성을 필터링하는 데 사용됨.

제공된 필터보다 시간적으로 빠르거나 같은 타임 스탬프 속성(attribute

timestamp)을 가진 메시지는 이 필터링 기준과 일치한다.

DOMString from

메시지 from 속성(attribute)을 필터링 하는 데 사용됨.

속성과 정확히 일치하는 from 속성을 가지거나 정의된 와일드 카드가 포함된

속성을 가진 메시지는 이 필터링 기준과 일치한다.


180 TTAK.OT-10.0323

StringArray to

메시지 to 속성을 필터링하는 데 사용됨.

이 속성의 모든 엘레멘트와 일치하는어레이(array) 요소를 가진 메시지(정확히

일치하거나 정의된 와일드 카드가 포함된 속성을 가진 메시지)는 이 필터링

기준과 일치한다.

StringArray cc

메지시 cc 속성을 필터링하는 데 사용됨.

이 속성의 모든 엘레멘트와 일치하는 cc 어레이(array) 엘레멘트를 가진

메시지(정확히 일치하거나 정의된 와일드 카드가 포함된 속성을 가진 메시지)는

이 필터링 기준과 일치한다.

StringArray bcc

bcc 속성을 필터링하는 데 사용됨.

이 속성의 모든 엘레멘트와 일치하는 bcc 어레이(array)에서의 모든 엘레멘트를

가진 메시지(정확히 일치하거나 정의된 와일드 카드가 포함된 속성을 가진

메시지)는 이 필터링 기준과 일치한다.

DOMString body

메시지 body 속성을 필터링하는 데 사용됨.

제공된 filter 속성과 정확하게 일치하거나 정의된 와일드 카드가 포함된 body

속성을 가진 메시지는 이 필터링 기준과 일치한다.

boolean isRead

메시지 isRead 속성을 필터링하는 데 사용됨.

제공된 필터와 정확하게 일치하는 isRead 속성을 가진 메시지는 이 필터링


boolean messagePriority

메시지 mesagePriority 속성을 필터링하는 데 사용됨.

제공된 filter 속성과 정확하게 일치하는 priority 속성을 가진 메시지는 이 필터링



181 TTAK.OT-10.0323

DOMString subject

메시지 subject 속성을 필터링하는 데 사용됨.

제공된 filter 속성과 정확하게 일치하거나 정의된 와일드 카드가 포함된 subject

속성을 가진 메시지는 이 필터링 기준과 정확히 일치한다.

마. MessageAttachment

메시지 첨부 파일에 대해 정의함.

interface MessageAttachment : File {

readonly attribute DOMString MIMEType;

};

이 속성은 동기화 인터페이스(synchronizable interface)를 동시에 실행시킴으로써

File 속성을 확장시켜 준다. 이는 사용자가 동기화 인터페이스에서 규정한 동기화

메소드를 사용하면서 첨부 파일 다운로드를 요청할 때 이를 허용해 준다.

속성(Attributes)

readonly DOMString MIMEType

MIME 타입의 첨부 파일(Attachment MIME type)

MIME 타입의 첨부파일에 대해 설명함. 예: “text/html”.

This attribute is readonly. 이 속성은 읽기 전용임.

바. FindMessagesSuccessCallback

findMessages 는 success callback 에 대해 정의함.


FindMessagesSuccessCallback {

void onsuccess(in MessageArray messages);

};

이 callback 인터페이스는 success callback 을 입력 인수(input argument)로써

메시지 리스트를 가져오는 기능으로 정의한다. 이는 findMessage 의 비동기식

작업(asynchronous operation)에 사용된다.


182 TTAK.OT-10.0323

메소드(Methods)

onsuccess

비동기식 명령(asynchronous call)이 성공적으로 완성될 때 호출되는 메소드.

서명


파라미터

• messages

o 옵션(Optional): No. o 타입: MessageArray. o 설명: findMessage 기준과 일치하는 메시지 리스트.

사. UpdateMessageSuccessCallback

특정한 success callback 을 업데이트함.


UpdateMessageSuccessCallback {

void onsuccess(in Message message);

};

callback 인터페이스는 업데이트가 시작된 후 메시지의 실제 상태를 나타내는

메시지 객체(message object)를 제공하는 기능으로써 success callback 을

정의한다.

메소드(Methods)

onsuccess

비동기식 명령(asynchronous call)이 성공적으로 완성될 때 호출되는 메소드.

서명


파라미터

• message

o 옵션(Optional): No. o 타입: Message. o 설명: 실제 업데이트된 상태를 나타내는 새로운 메시지.


183 TTAK.OT-10.0323

아. OnIncomingMessage

새로운 착신 메시지(incoming message)에 명령하는 메소드에 대해 정의하는

인터페이스.

[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingMessage {

void onevent (in Message message);

};

이 인터페이스는 메시지 객체로써 수신된 메시지를 제공하는 메소드에 대해

정의한다.

메소드

onevent

착신 메시지(incoming message)가 수신될 때 호출되는 메소드.

서명

void onevent(in Message message);

파라미터

• message


o 타입: Message.

o 설명: 수신된 메시지

자. MessageSendCallback

각 수신자에 대한 메시지 전송 결과를 얻기 위해 명령하는 메소드에 대해 정의하는

인터페이스.

[Callback, NoInterfaceObject] interface MessageSendCallback {

void onsuccess();

void onmessagesendsuccess(in DOMString recipient);

void onmessagesenderror(in DeviceAPIError error, in DOMString recipient);

};

이 인터페이스는 개별 수신자에 대한 전송 작업의 결과를 얻을 때마다 혹은

메시지가 모든 수신자에게 성공적으로 전송될 때 호출되는 기능에 대해 정의한다.


184 TTAK.OT-10.0323

메소드

onsuccess

모든 수신자에게 메시지가 성공적으로 전송될 때 호출되는 메소드.

서명

void onsuccess();

onmessagesendsuccess

. 메시지가 특정 수신자에게 전송될 때 호출되는 메시지.

서명


파라미터

• recipient




o 설명: 메시지 수신자

onmessagesenderror

메시지가 특정 수신자에게 성공적으로 전송되지 않을 때 호출됨.

서명


파라미터

• error


o 타입: DeviceAPIError.

o 설명: 실패 원인을 설명해 주는 에러 코드(error code)

• recipient



o 타이프: DOMString.

o 설명: 메시지 수신자.


185 TTAK.OT-10.0323

4.7.5. 타입의 정의

가. MessageArray

메시지 어레이(Array of Messages)

typedef sequence<Message> MessageArray;

4.7.6. 피쳐(Features)

다음의 피쳐

• http://wacapps.net/api/messaging

혹은 이 피쳐의 하위에 있는 피쳐가 성공적으로 요청되는 경우, Messaging

인터페이스가 실행되고 이에 따른 객체(object)가 글로벌 네임스페이스(global

namespace)에 deviceapis.messaging 으로 나타난다.

이는 위젯 config.xml 에서 사용하기 위해 API 의 피쳐를 나타내는데 사용되는 URI

리스트로, 각각의 URL 에 대해 해당되는 기능의 리스트가 제공된다.

http://wacapps.net/api/messaging.send

Messaging.findMessages(), Message.update(), Messaging.onSMS(),

Messaging.onMMS(), Messaging.onEmail() 메소드를 제외한 전체 모듈에 대한

접근.

http://wacapps.net/api/messaging.find

Messaging.sendMessage(), Message.update(), Messaging.onSMS(),


접근.

http://wacapps.net/api/messaging.subscribe

Messaging.sendMessage(), Message.update(), Messaging.findMessages()

메소드를 제외한 전체 모듈에 대한 접근

http://wacapps.net/api/messaging.write

Messaging.sendMessage(), Messaging.findMessages(), Messaging.onSMS(),


접근.

http://wacapps.net/api/messaging

이 모듈에 있는 전체 피쳐(feature)에 대한 접근.


186 TTAK.OT-10.0323

4.7.7. Full WebIDL

module messaging {




};














in Message message)




in Message message)



successCallback,





187 TTAK.OT-10.0323









};
















successCallback,



};

Message implements Synchronisable;


188 TTAK.OT-10.0323















};



};

MessageAttachment implements Synchronisable;




};




};



};


void onsuccess();



189 TTAK.OT-10.0323


};

};

4.7.8. 위치 정보(geolocation) 모듈

4.7.9. 요약

본 표준은 geolocation 정보 탐색 시 WAC 디바이스의 기능을 설명한다.

4.7.10. 서론

이 섹션은 정보성(INFORMATIVE)이다.

WAC 는 가능할 때마다 Open Standards 사용을 실시하고 있으므로, WAC 에서

geolocation 에 대한 액세스 W3C Geolocation API [GEOLOCATION]를 통한다.

이 모듈은 W3C 명세서는 Application Programming Interface (API)가

geolocation 이라는 이름을 가지는 Navigator 인터페이스에서 예시되는 것을 필수로

하기 때문에 WAC 에 의해 지정되는 것보다 다양한 위치에 적재된다. 한편으로는

WAC 에 의해 지정되는 API 는 deviceapis 인터페이스에 적재된다.

4.7.11. API

이 섹션은 NORMATIVE 이다.

WAC compliant implementation 은 반드시 W3C Geolocation specification

[GEOLOCATION]을 지원해야 한다.

이 API 를 사용하기 위해서는, widget 구성 문서(i.e. config.xml)에 그에 대한

액세스를 밝혀야 한다. 이 선언은 http://www.w3.org/TR/geolocation-API/ 특징을

통해 이루어진다.

4.7.12. Security

이 섹션은 NORMATIVE 이다.

WAC compliant implementation 은 디폴트로 이 API 에 대한 접근을 가능하게

해서는 안된다. 그 API 에 대한 접근은 오직 적절한 feature tag 를 통하여 widget

configuration document 에서 선언될 때뿐이다.


190 TTAK.OT-10.0323

주의: WAC Security Framework 은 구성 문서에서의 선언과 독립적으로 API 에

대한 접근을 거절할 수 있다.

4.7.13. WebIDL

이 섹션은 정보성(INFORMATIVE)이다.

완전성을 위하여, 이 명세서는 W3C Geolocation specification [GEOLOCATION]에

포함된 WebIDL declaration 사본을 포함한다. 관련 명세서는 conformant

implementation 을 생성하기 위해 필요한 상세사항 모두를 포함한다.

Geolocation Instatiation

[NoInterfaceObject]

interface NavigatorGeolocation {

readonly attribute Geolocation geolocation;

}

Navigator implements NavigatorGeolocation;

Geolocation Interface

[NoInterfaceObject]

interface Geolocation {

void getCurrentPosition(in PositionCallback successCallback,

in optional PositionErrorCallback errorCallback,

in optional PositionOptions options);

long watchPosition(in PositionCallback successCallback,

in optional PositionErrorCallback errorCallback,

in optional PositionOptions options);


};

[Callback=FunctionOnly, NoInterfaceObject]

interface PositionCallback {

void handleEvent(in Position position);

};

[Callback=FunctionOnly, NoInterfaceObject]

interface PositionErrorCallback {


191 TTAK.OT-10.0323

void handleEvent(in PositionError error);

};

Position Options

[Callback, NoInterfaceObject]

interface PositionOptions {

attribute boolean enableHighAccuracy;

attribute long timeout;

attribute long maximumAge;

};

Position Interface

interface Position {

readonly attribute Coordinates coords;

readonly attribute DOMTimeStamp timestamp;

};

Coordinates Interface

interface Coordinates {

readonly attribute double latitude;

readonly attribute double longitude;

readonly attribute double? altitude;

readonly attribute double accuracy;

readonly attribute double? altitudeAccuracy;

readonly attribute double? heading;

readonly attribute double? speed;

};

PositionError Interface

interface PositionError {

const unsigned short PERMISSION_DENIED = 1;

const unsigned short POSITION_UNAVAILABLE = 2;

const unsigned short TIMEOUT = 3;

readonly attribute unsigned short code;


};


192 TTAK.OT-10.0323

4.7.14. 참고문헌

[GEOLOCATION]

NORMATIVE: Geolocation API Specification (W3C Candidate Recommendation

07 September 2010) , see http://www.w3.org/TR/2010/CR-geolocation-API-

20100907/

4.8. 개인 정보 관리(PIM) 모듈

4.8.1. 요약

본 spec 에서는 개인 정보 관리(PIM)모듈의 체계(hierarchy)를 정의한다.

4.8.2. 인터페이스와 메소드 요약


PimObject

Pim

4.8.3. 개요

개인 정보 관리(PIM) 모듈은 다음으로 구성된다, 즉:

• contact

• task

• calendar.

상기 모듈들에 대한 접근은 다음에 보이는 인터페이스들을 통해 가능하다.

• deviceapis.pim.contact

• deviceapis.pim.task

• deviceapis.pim.calendar.


가. PimObject

deviceapis 객체에 무엇을 예시할 것인가를 정의한다.

[NoInterfaceObject] interface PimObject {

readonly attribute Pim pim;

};


193 TTAK.OT-10.0323

Deviceapis implements PimObject;

pim 모듈들의 기능들에 대한 접근을 허용하는 것으로서 deviceapis.pim 객체 가

있다.

나. Pim

연관된 properties 들을 예시하는 PIM 인터페이스

[NoInterfaceObject] interface Pim {

};

PIM 모듈의 하위모듈(즉 contact, calendar, task)들로서 이것들은 request 를 받아서

instantiate 를 해 주는 것이 가능한 각 name 들과 feature 들을 정의한다.

다. Features

라. Full WebIDL

module pim {



};



};

};


194 TTAK.OT-10.0323

4.9. 콘택트(contact) 모듈

4.9.1. 요약

주소록(address book)관리를 위한 API 표준



ContactManagerObject

ContactManager PendingOperation

getAddressBooks(AddressBookArraySuccessCallback


AddressBook Contact createContact(ContactProperties

contactProperties)

PendingOperation

addContact(AddContactSuccessCallback

successCallback, ErrorCallback errorCallback, Contact

contact)

PendingOperation updateContact(SuccessCallback

successCallback, ErrorCallback errorCallback, Contact

contact)

PendingOperation deleteContact(SuccessCallback


DOMString id)

PendingOperation

findContacts(ContactArraySuccessCallback


ContactFilter filter)

Contact

ContactProperties

Address

ContactAddress

PhoneNumber

EmailAddress

ContactFilter

ContactArraySuccessCallback void onsuccess(ContactArray contacts)

AddContactSuccessCallback void onsuccess(Contact contact)

AddressBookArraySuccessCallback void onsuccess(AddressBookArray addressbooks)


195 TTAK.OT-10.0323

4.9.3. 개요

인명관리에서 contact 란 사람에 대한 일련의 정보의 집합을 일컫는 것으로 가령

전화번호, 이메일 주소 등을 포함한다. 그리고 주소록이란 contact 들을 모아놓은

것이다.

RFC 2426 vCard MIME Directory Profile 은 contact 를 교환하는 포멧에 대한 정의를

담고 있다. 이에 본 API 는 상기 스펙의 정의 내용들을 차용하여 본 표준서에서

contact 속성들을 매핑하는데 활용을 하였음을 밝힌다.

이 API 표준서는 주소록에 있는 contact 들을 기능적으로 읽기(read), 생성(create),

삭제(delete) 및 업데이트(update)하는 것을 내용으로 한다. 주소록은 AddressBook

객체의 어레이를 반환하는 getAddressBooks 방법을 통해 획득이 가능하다.


가. ContactManager객체

deviceapis 객체에 대한 정의는 아래 예시와 같다.

[NoInterfaceobject] interface ContactManagerObject {

readonly attribute ContactManager contact;

};

Pim implements ContactManagerObject;

contact module 의 제 함수들에 접근할 때 deviceapis.pim.contact 객체를

사용한다.

나. ContactManager

Contact manager class 는 모듈 함수들에 접근할 수 있도록 한다.

[NoInterfaceObject] interface ContactManager {

const short SIM_ADDRESS_BOOK = 0x0000;

const short DEVICE_ADDRESS_BOOK = 0x000F;

const short PHONE_ADDRESS_BOOK = 0x00FF;

PendingOperation getAddressBooks(in AddressBookArraySuccessCallback



};


196 TTAK.OT-10.0323

이 인터페이스는 주소록의 여러 객체들을 retrieve 하는 방법을 제공한다. 주소록에

있는 객체들은 manipulate 가 가능하며 또한 객체를 추가(add), 제거(remove) 및

업데이트(update)를 위한 함수들을 포함하고 있다.

상수

short SIM_ADDRESS_BOOK

SIM 주소록을 식별하는데 사용되는 상수

short DEVICE_ADDRESS_BOOK

Device 주소록을 식별하는 데 사용되는 상수.

short PHONE_ADDRESS_BOOK

Phone 주소록을 식별하는데 사용되는 상수.

Method

getAddressBooks

원하는 주소록을 획득

서명



만일 입력 파라미터들 중에서 타입(type)과 호환(compatible)하지 못하는

파라미터가 하나라도 존재한다면, 반드시 TYPE_MISMATCH_ERR 코드를 갖는

DeviceAPIError 가 동기적으로 발생되도록 하여야 한다.

만약 successCallback 이 어떤 함수도 포함하고 있지 않다면(즉 null(0)값을

포함하고 있다면) 반드시 DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는

errorCallback 이 트리거 되도록 하여야 한다.

만일 이 feature(특징)가 지원되는 않는다면, NOT_SUPPORTED_ERR 코드를

갖는 DeviceAPIError 가 errorCallback 으로 반드시 반환되도록 하여야 한다.

만일 이 기능을 허용하지 않을 경우, errorCallback 은 반드시

SECURITY_ERR 코드를 갖는 DeviceAPIError 와 함께 invoke 되어야 한다.


197 TTAK.OT-10.0323

조작이 성공적으로 완료가 되면 successCallback 은 phone address book 및

SIM address book(존재하는 경우)과 함께 반드시 invoke 되어야 한다.

디바이스에 만일 다른 타입의 주소록(address book)이 있다면 이것도 반드시

반환되어야 한다.

만약 존재하는 주소록이 없다면 successCallback 은 빈 어레이(empty array)

상태로 invoke 되어야 한다.

만일 주소록을 획득하는 과정에서 상기와 다른 타입의 에러가 발생하는 경우,

invocation 에 유효하게 pass 되었던 errorCallback 함수를 호출하되,

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 pass 하도록 한다.

상기에 언급한 예시들 중에서 errorCallback 이 invoke 되어야 하는 경우에 한해

만일 개발자가 유효한 값을 갖는 ErrorCallback 를 pass 하지 않도록

구성하였다면(가령 null(0)값을 갖거나 미정의된 경우), 이는 후속적인 action 을

요구하지 않는 것과 같다(즉 에러내용이 개발자에게 통지되지 않게 된다.)

파라미터

• successCallback

o Optional: No.

o Type: AddressBookArraySuccessCallback.

o 설명: invocation 이 성공적으로 종료될 때 함수가 호출이 됨.

• errorCallback

o Optional: Yes.

o Type: ErrorCallback.

o 설명: 에러가 발생할 때 함수가 호출이 됨.

반환값

비동기적인 호출을 취소하기 위한 PendingOperation

예외

• DeviceAPIError:

만일 어떤 입력 파라미터가 자신에 대응하는 type 과 compatible 하지

못할 경우 TYPE_MISMATCH_ERR 코드와 함께 이 에러가 발생


198 TTAK.OT-10.0323

코드 예제

var addressbook; // Define the error callback for all the asynchronous calls function errorCallback(response) { alert( "The following error occurred: " + response.code); } function contactUpdatedCB() { // The contact has been successfully updated alert('Contact Successfully updated'); } function contactFoundCB(contacts) { // The contact has been successfully found // Let's try to change the summary contacts[0].firstName = "Jeffrey Ross"; addressbook.updateContact(contactUpdatedCB, errorCallback, contacts[0]); } function contactAddedCB(contact) { // The contact has been successfully added // Let's try to check if we can retrieve the added // contact from the address book. If the address book // was empty only the item added through addContact should // be returned addressbook.findContacts(contactFoundCB, errorCallback, {firstName:'%Jeffrey%'}); } // Define the success callback for retrieveing all the // Address Books function AddressBooksCB(addressbooks) { if(addressbooks.length > 0) { addressbook = addressbooks[0]; alert("The addressbook type is " + addressbook.type + " and name " + addressbook.name); var contact = addressbook.createContact( {firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone'], emails:[{email:'[email protected]'}], phoneNumbers:[{number:'666666666'}]}); addressbook.addContact(contactAddedCB, errorCallback, contact); } } // Get a list of available Address Books. deviceapis.pim.contact.getAddressBooks(AddressBooksCB, errorCallback);


199 TTAK.OT-10.0323

다. AddressBook

이 메소드는 주소록을 관리하는 방법을 제공한다.

[NoInterfaceObject] interface AddressBook {

readonly attribute short type;


Contact createContact(in optional ContactProperties contactProperties)


PendingOperation addContact(in AddContactSuccessCallback

successCallback,


in Contact contact)


PendingOperation updateContact(in SuccessCallback successCallback,


in Contact contact)


PendingOperation deleteContact(in SuccessCallback successCallback,


in DOMString id)


PendingOperation findContacts(in ContactArraySuccessCallback

successCallback,


in optional ContactFilter filter)


};

주소록은 contact 들의 집합이다. 이 인터페이스는 주소록을 관리하는 메소드를

제공하는 것으로서, 다음과 같이 주소록 내에서 contact 들을 조작할 수 있도록

한다.

• findContact() 메소드를 통한 filter 를 사용하여 contact 들을 find 한다. • addContact() 메소드를 사용하여 특정 주소록에 contact 를 add 한다. • updateContact() 메소드를 사용하여 기존의 contact 를 update 한다. • deleteContact() 메소드를 사용하여 기존의 contact 를 delete 한다.


200 TTAK.OT-10.0323

속성

readonly short type

주소록(address book)의 한 type 이다.

이 type 은 반드시 아래에 보이는 상수들 중의 하나를 포함하고 있어야 한다.

• SIM_ADDRESS_BOOK = 0

• DEVICE_ADDRESS_BOOK = 1

이 type 의 속성은 readonly 이다.


주소록에서 문으로 된(descriptive) name.

이 속성은 readonly 이다.

.

Method

createContact

ContactProperties 의 선택사항인 셋트(set)를 갖는 contact 객체의 인스턴스를

생성한다..

서명

Contact createContact(in optional ContactProperties contactProperties);

만일 contactProperties 속성이 omitted 된 경우라면, 디폴트 값이 모든 contact

속성들에 할당 되면서 contact 인터페이스에 대한 인스턴스생성을 시도 하도록

implementation 이 구성되어야 한다. 그러나 입력 파라미터로 pass 된

contactProperties 속성이 (유효한 값으로) 동 contactProperties 속성의 subset

속성만을 포함하고 있는 경우라면, 상기 이외의 다른 속성에 디폴트 값를 할당

하면서 contact 인터페이스의 인스턴스 생성을 시도하도록 implementation 이

구성되어야 한다. 만일 입력파라미터로 pass 되었던 contact 가 모든

contactProperties 속성에 대해 유효한 값들을 포함하고 있는 경우에는

implementation 이 contact 인터페이스의 인스턴스를 생성하도록 시도하여야

한다.


201 TTAK.OT-10.0323

contact 의 인스턴스가 성공적으로 생성이 된 경우, 인스턴스는 이 방법에 의해

반드시 반환이 되어야 한다. 그러나 생성 과정에서 에러가 발생한 경우에는

메소드 상 적절한 에러코드를 갖는 DeviceAPIError 를 반드시 발생 시켜야 한다.

이 operation 은 생성된 contact 를 주소록에 add 하는 것이 아니며 또한 동

contact 에 identifier(id 속성)를 할당 하는 것이 아니다. 그러나 개발자가

의도적으로 invoke 시킬 경우 addContact 메소드를 통해 이 과제의 수행이

가능하다.

파라미터

• contactProperties

o Optional: Yes.

o Type: ContactProperties.

o 설명: Contact 정보

반환값

생성된 contact 객체.

예외

• DeviceAPIError:



만일 contactProperties 의 입력 파라미터가 유효하지 않은 값들을

포함하고 있을 경우 INVALID_VALUES_ERR 코드와 함께 이 에러가 발생

만일 feature 가 지원되지 않을 경우, NOT_SUPPORTED_ERR 코드와 함께

이 에러가 발생

contact 인스턴스를 생성하는 과정에서 만일 에러가 발생한 경우

UNKNOWN_ERR 코드와 함께 이 에러가 발생


202 TTAK.OT-10.0323

코드 예제

var addressbook;

// Define the error callback for all the asynchronous calls

function errorCallback(response) {

alert( "The following error occurred: " + response.code);

}

function contactAddedCB(contact) {

alert("Contact Added with id " + contact.id);

}

// Define the success callback for retrieving all the

// Address Books

function AddressBooksCB(addressbooks) {

if(addressbooks.length > 0)

{

addressbook = addressbooks[0];

alert("The addressbook type is " + addressbook.type +

" and name " + addressbook.name);

var contact = addressbook.createContact(

{firstName:'Jeffrey',

lastName:'Hyman',

nicknames:['joey ramone'],

emails:[{email:'[email protected]'}],

phoneNumbers:[{number:'666666666'}]});

addressbook.addContact(contactAddedCB, errorCallback, contact);

}

}

// Get a list of available Address Books.

deviceapis.pim.contact.getAddressBooks(AddressBooksCB,

errorCallback);


203 TTAK.OT-10.0323

addContact

주소록에 contact 를 비동기적으로 add 한다.

서명

PendingOperation addContact(in AddContactSuccessCallback successCallback,

in ErrorCallback errorCallback, in Contact contact);

만일입력 파라미터들 중에서 타입(type)과 호환(compatible)하지 못하는







만일 어떤 입력 파라미터에 null 값이나 미정의된 successCallback 과 같은

유효하지 않은 값이 포함되어 있거나, 또는 contact 에 유효하지 않은 값이

포함된 경우나 주소록에서 어떤 contact 항목을 입력하는 것이 잘 되지 않는

경우(가령 텍스트 속성의 size 의 제한 등의 이유로) 반드시 request 를

reject 하면서 DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는

errorCallback 을 invoke 시키도록 implementation 이 구성되어야 한다. 그러나

개발자가 에러들을 무시할 수 있도록 허용하려면 errorCallback 은 null 값을

유효한 값으로 인식하도록 해야 한다.

contact 가 주소록에 성공적으로 추가(add)가 이루어진 경우 successCallback 이

반드시 invoke 되어야 한다. 이 successCallback 에는 추가된 contact 를

설명하는 contact element 와 부여된 id 속성을 포함한다.

만일 contact 항목들을 add 하는 과정에서 상기와 다른 타입의 에러가 발생하는

경우, invocation 에 유효하게 pass 되었던 errorCallback 함수를 호출하되,

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 포함하도록 한다.






204 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: No.

o Type: AddContactSuccessCallback.


• errorCallback

o Optional: No.



• contact

o Optional: No.

o Type: Contact.

o 설명: contact 객체가 저장터미널에 add 됨.

반환값


예외

• DeviceAPIError:

만일 어떤 입력 파라미터가 자신에 대응하는 type 과 compatible 하지 못할 경우

TYPE_MISMATCH_ERR 코드와 함께 이 에러가 발생


205 TTAK.OT-10.0323

코드 예제

var addressbook;




}

function contactAddedCB(contact) {

alert("Contact Added with id " + contact.id);

}

// Define the success callback for retrieveing all the

// Address Books



{




var contact = addressbook.createContact(

{firstName:'Jeffrey',

lastName:'Hyman',

nicknames:['joey ramone'],

emails:[{email:'[email protected]'}],

phoneNumbers:[{number:'666666666'}]});

addressbook.addContact(contactAddedCB, errorCallback, contact);

}

}


deviceapis.pim.contact.getAddressBooks(AddressBooksCB,

errorCallback);


206 TTAK.OT-10.0323

updateContact

주소록에 있는 기존의 contact 를 비동기적으로 업데이트 한다.

서명

PendingOperation updateContact(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in Contact contact);

만일입력 파라미터들 중에서 타입(type)과 호환(compatible)하지 못하는



만일 contact 를 업데이트하는 이 feature(특징)가 지원되는 않는다면,

NOT_SUPPORTED_ERR 코드를 갖는 DeviceAPIError 가 errorCallback 으로

반드시 반환되도록 하여야 한다.



만일 어떤 입력 파라미터에 null 값이나 미 정의된 successCallback 과 같은

유효하지 않은 값이 포함되어 있거나, 또는 contact 에 유효하지 않은 값이

포함된 경우나 주소록에서 어떤 contact 를 업데이트하는 것이 실패하는

경우(가령 텍스트 속성의 size 의 제한 등의 이유로) 반드시 request 를

reject 하면서 DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는

errorCallback 을 invoke 시키도록 implementation 이 구성되어야 한다. 그러나

개발자가 에러들을 무시할 수 있도록 허용하려면 errorCallback 은 null 값을

유효한 값으로 인식하도록 해야 한다.

만일 id 속성이 주소록에 있는 contact 들의 id 속성들 중에서 대응하는 것을

찾지 못하는 경우(가령 해당 id 에 match 가 되는 것으로서 업데이트할

contact 가 기존의 리스트에 없는 경우 등), NOT_FOUND_ERR 코드를 갖는

DeviceAPIError 가 반드시 반환되어야 한다.

만일 모든 속성들이 다 유효한 값들이고 그 id 속성이 주소록에 있는 기존의 한

contact 와 대응(correspond)하는 것이 가능한 경우, implementation 은

업데이트된 속성을 갖는 그 식별자에 대응하는 contact 를 반드시 업데이트

시도를 하도록 구성이 되어야 한다.

contact 가 성공적으로 업데이트 되었으면 SuccessCallback 이 반드시

invoke 되어야 한다.


207 TTAK.OT-10.0323

만일 contact 항목을 업데이트 하는 과정에서 상기와 다른 타입의 에러가

발생하는 경우, invocation 에 유효하게 pass 되었던 errorCallback 함수를

호출하되, UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 pass 하도록 한다.


만일 개발자가 유효한 값을 갖는 errorCallback 를 pass 하지 않도록



파라미터

• successCallback

o Optional: No.

o Type: SuccessCallback.


• errorCallback

o Optional: No.



• contact

o Optional: No.

o Type: Contact.

o 설명: contact 객체가 업데이트됨.

반환값


예외

• DeviceAPIError:



.


208 TTAK.OT-10.0323

코드 예제

var addressbook;




}

function contactUpdatedCB() {

// The contact has been successfully updated

alert('Contact Successfully updated');

}

function contactFoundCB(contacts) {

// The contact has been successfully found

// Let's try to add a new nickName

var nicknames = contacts[0].nicknames;

nicknames.push("Dee Dee");

contacts[0].nicknames = nicknames;

addressbook.updateContact(contactUpdatedCB,

errorCallback,

contacts[0]);

}

// Define the success callback for retrieving all the

// Address Books



{




addressbook.findContacts(contactFoundCB, errorCallback,

{firstName:'%Jeffrey%'});

}

}


deviceapis.pim.contact.getAddressBooks(AddressBooksCB, errorCallback);


209 TTAK.OT-10.0323

deleteContact

주소록으로부터 contact 를 비동기적으로 delete 한다.

서명

PendingOperation deleteContact(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString id);

만일입력 파라미터들 중에서 type 과 compatible 하지 못하는 파라미터가

하나라도 존재한다면, 반드시 TYPE_MISMATCH_ERR 코드를 갖는


만일 이 feature 가 지원되는 않는다면, NOT_SUPPORTED_ERR 코드를 갖는

DeviceAPIError 가 errorCallback 으로 반드시 반환되도록 하여야 한다.



만일 successCallbac 이 유효한 함수를 포함하고 있는 않는 경우(즉 null(0)값을

갖거나 미 정의된 경우), INVALID_VALUES_ERR 코드를 갖는 DeviceAPIError 가

반드시 errorCallback 에 반환이 되어야 한다.

만일 id 파라미터가 주소록에 있는 contact 들의 id 속성과 correspond 가 되지

않는 경우, NOT_FOUND_ERR 코드를 갖는 DeviceAPIError 가 반드시

errorCallback 에 반환이 되어야 한다.

그렇지 않을 경우 해당 identifier 와 correspond 되는 contact 를 delete 하도록

implementation 이 구성되어야 한다.

contact 가 성공적으로 delete 되었으면, SuccessCallback 가 반드시


만일 contact 를 delete 하는 과정에서 상기와 다른 타입의 에러가 발생하는 경우,

invocation 에 유효하게 pass 되었던 errorCallback 함수를 호출하되,

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 pass 하도록 한다.



구성하였다면(가령 null(0)값을 갖거나 미 정의인 경우), 이는 후속적인 action 을



210 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: No.



• errorCallback

o Optional: No.



• id

o Optional: No.

o Nullable: No.

o Type: DOMString.

o 설명: contact 객체의 identifier (id 속성)가 delete 됨.

반환값


예외

• DeviceAPIError:



.


211 TTAK.OT-10.0323

코드 예제

var adddressbook;

// Define the error callback.



}

// Define the contact delete success callback.

function contactDeleteSuccessCallback() {

alert("Deleted");

}

// Define the contact success callback.

function contactSearchSuccessCallback(contacts) {

// Delete the first existing contact.

addressBook.deleteContact(contactDeleteSuccessCallback,

errorCallback, contacts[0].id);

}

// Define the address books success callback.

function addressbooksSuccessCallback(addressbooks) {


// Find all contacts in Address Book 0.

addressbook.findContacts(contactSearchSuccessCallback,

errorCallback);

}

// Get a list of available address books.

deviceapis.pim.contact.getAddressBooks(addressbooksSuccessCallback,

errorCallback);


212 TTAK.OT-10.0323

findContacts

특정한 주소록에 있는 모든 contact 객체들의 어레이를 획득하거나 또는

optional 한 경우로 제공된 filter 와 match 가 되는 contact 객체들의 어레이를

획득한다.

서명



ContactFilter filter);











만일 filter 가 정상적으로 pass 되어 유효한 값들을 포함하고 있다면, ContactFilter

인터페이스에서 정의하였던 필터기준(filter criteria)에 match 가 되는 주소록의

값들만이 successCallback 에 반환이 된다. 그러나 pass 가 된 filter 가 없다거나

또는 filter 에 유효하지 않은 값이 하나라도 포함이 되거나 null 또는 미정의된

경우에는, implementation 은 모든 contact 의 항목 리스트을 다

successCallback 에 반환하도록 하여야 한다. 만일 주소록에 contact 가 하나도

없거나 또는 필터기준에 match 되는 contact 를 찾을 수 없는 경우,

successCallback 은 빈 어레이(empty array) 상태로 invoke 시킨다.

contact 를 retrieve 하는 과정에서 상기에서 설명한 경우의 수가 아닌 다른

타입의 에러가 발생한 경우, invocation 에 pass 가 되었던 errorCallback 함수가,

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체와 함께 pass 되면서

호출되어야 한다.




213 TTAK.OT-10.0323


요구하지 않는 것과 같은 것으로서, 즉 에러내용이 개발자에게 통지되지 않게

된다.

파라미터

• successCallback

o Optional: No.

o Type: ContactArraySuccessCallback.


• errorCallback

o Optional: Yes.



• filter

o Optional: Yes.

o Type: ContactFilter.

o 설명: 반환시킬 contact 를 선택할 때 사용되는 filter

반환값


예외

• DeviceAPIError:



.


214 TTAK.OT-10.0323

코드 예제

라. Contact

Contact object.

[NoInterfaceObject] interface Contact : ContactProperties {


};

이 인터페이스는 ContactProperties 를 확장한 개념으로서 즉 하나의 주소록 내에

존재하는 단일 contact 를 추상적으로 객체화한 것이다 contact 가 만약 SIM

contact 인 경우에는 전화번호와 이름정보만이 저장될 수 있으므로 따라서 phone 과

name 만을 반환시킬 수 있다.




}

// Define the contact search success callback.

function contactSearchSuccessCallback(contacts) {

alert(contacts.length + " results found.");

}

// Define the address book lists success callback.

function abListSuccessCallback(addressbooks) {

// Find all contacts in the first address book that contains in

// the nick name list the word ramone

addressbooks[0].findContacts(contactSearchSuccessCallback,

errorCallback,

{nickname:"%ramone%"});

}


deviceapis.pim.contact.getAddressBooks(abListSuccessCallback,

errorCallback);


215 TTAK.OT-10.0323

속성


implementation 에서 contact 를 지속적이고(persistent) 고유한 값으로(unique)

식별하도록 해 주는 식별자(identifier).

이 id 속성값은 contact 항목이 주소록에 add 가 될 때 플랫폼에서 부여되므로,

이 항목이 존재하는 전 기간 동안 단말기의 사용국가(locally)에서 unique 하고

persistent 한 값을 가지므로 개발자가 임의로 바꿀 수 없다.

좀 더 자세한 내용은 RFC 2426, Section 3.6.6.7 을 참고한다.


코드 예제




}

// Define the success callback.

function contactFindSuccessCallback(response) {

alert("The first Ramone id is " + response[0].id);

}

// Define the address book success callback.

function addressBookSuccessCallback(addressBooks) {

// Find all contacts in the first address book

// with nick name 'Ramone'.

addressBooks[0].findContacts(contactFindSuccessCallback, null,

{nickName:"Ramone"});

}


deviceapis.pim.contact.getAddressBooks(addressBookSuccessCallback,erro

rCallback);


216 TTAK.OT-10.0323

마. ContactProperties

Contact 가 생성이 되면 그 contact 의 특성을 인터페이스에 제공한다.

[Callback, NoInterfaceObject] interface ContactProperties {

attribute DOMString firstName;

attribute DOMString lastName;

attribute StringArray nicknames;

attribute DOMString phoneticName;

attribute ContactAddressArray addresses;

attribute DOMString photoURI;

attribute PhoneNumberArray phoneNumbers;

attribute EmailAddressArray emails;

};

contact 가 createContact 메소드를 사용하여 생성이 된 경우 이 인터페이스는 입력

파라미터에 사용이 된다.

모든 속성들은 optional 하며, 별도의 파라미터 설명으로 명시가 되지 않는 한

디폴트값에 의해 미 정의된다.

속성

DOMString firstName

contact 의 first name(이름).

디폴트에 의해 이 속성은 empty string 으로 초기화된다. RFC 2426, Section

3.1.1 참조 요망.

코드 예제

var contact = addressBook.createContact(); contact.firstName = "Douglas Glenn";


217 TTAK.OT-10.0323

DOMString lastName

contact 의 last name(성).

디폴트에 의해 이 속성은 empty string 으로 초기화된다. RFC 2426, Section

3.1.1 참조 요망.

코드 예제

StringArray nicknames

contact 의 nickname.

nickname 이란 사람, 장소, 물건에 주어진 이름 대신에 또는 그 이름에 추가하여

사용되는 하나의 name 이고, 또한 사용자에게 친숙한 형태로 편의적으로 정할

수도 있다.

디폴트에 의해 이 속성은 빈 어레이(empty array)로 초기화된다.

nickname 이 복수로 존재하는 경우, 맨 처음의 nickname 이 디폴트값이 된다.

RFC 2426, Section 3.1.3 참조할 것.

코드 예제

DOMString phoneticName

contact 의 표음식 이름.

contact name 을 어떻게 부를지를 발음 기준으로 명시하는 것으로서, 일부

국가들의 경우 특히 일본어와 같은 언어에서 똑같이 “Kanji”로 쓰더라도 여러

가지로 발음이 가능할 경우 특히 유용하다.

디폴트에 의해 이 속성은 빈 어레이(empty array)로 초기화된다.

var contact = addressBook.createContact();

contact.lastName = "Colvin";


var nicknames = contact.nicknames;

nicknames.push("Dee Dee");

contact.nicknames = nicknames;


218 TTAK.OT-10.0323

ContactAddressArray addresses

Contact 주소.

디폴트에 의해 이 속성은 미 정의된다.

복수의 주소가 존재하는데, 그 중에 preferred 로 지정된 주소가 없을 경우(즉

'PREF' type), 첫 번째 entry 를 디폴트 주소로 간주한다.

코드 예제

DOMString photoURI

Contact 의 사진에 관한 URI

디폴트에 의해 이 속성은 미정의 된다.

URI 를 contact 객체와 관련된 이미지로 지정할 때 사용되는 속성. RFC 2426,

Section 3.1.4 참조 요망.

코드 예제

PhoneNumberArray phoneNumbers

contact 의 전화번호.


복수의 전화번호가 존재하는데, 그 중에 preferred 로 지정된 전화번호가 없을

경우(즉 'PREF' type), 첫 번째 entry 를 디폴트 전화번호로 간주한다.


var contactAddr = {streetAddress:"Gran Via, 32",

postalCode:"50013",city:"Zaragoza",country:"ES"};

contact.addresses = [contactAddr];


contact.photoURI = "http://www.mysite.com/mypicture.jpg"; // remote

picture


219 TTAK.OT-10.0323

코드 예제

EmailAddressArray emails

contact 의 이메일 주소.


복수의 이메일 주소가 존재하는데, 그 중에 preferred 로 지정된 이메일 주소가

없을 경우(즉 'PREF' type), 첫 번째 entry 를 디폴트 이메일 주소로 간주한다.

코드 예제

바. Address

지구 지표상의 어느 특정한 지점을 나타내는 일련의 속성들을 포함하는 인터페이스

[Callback, NoInterfaceObject] interface Address

{

attribute DOMString country;

attribute DOMString region;

attribute DOMString county;

attribute DOMString city;

attribute DOMString streetAddress;

attribute DOMString additionalInformation;

attribute DOMString postalCode;

};


var phoneNumber = {number:"666666666"};

contact.phoneNumbers = [phoneNumber];


var email = {email:"[email protected]"};

contact.emails = [email];


220 TTAK.OT-10.0323

디폴트에 의해 이 인터페이스의 각 속성은 모두 정의 되어 있지 않다.

더 자세한 내용은 RFC 2426, Section 3.2.1 을 참고한다.

코드 예제

속성

DOMString country

address 를 갖는 국가.

각 국가를 나타내는 코드는 2 자리 수로 구성하는 고유 코드쳬계[ISO 3166-1]를

따를 것을 권장한다.

DOMString region

국가내의 대단위 구역명

예를 들어 주(가령 미국의 경우)나 지방(가령 스페인의 경우)명이 여기에

해당한다.

DOMString county

국가의 대단위 구역명 내의 소단위 구역명으로 가령 카운티나 지역(district)정도

크기의 단위를 지칭한다.

DOMString city

지역적으로 세분화한 명칭으로 가령 시, 타운, 빌리지 급의 크기를 지칭한다.

DOMString streetAddress

거리(street)명으로서 가령 건물번호, 스트리트 번호나 이름 등을 지칭한다.

var addressbooks = deviceapis.pim.contact.getAddressBooks();

// Create a contact.

var contact = addressbooks[0].createContact(

{firstName:'Douglas Glenn', lastName:'Colvin', nicknames:['deedee'],

addresses:[{streetAddress:"Gran Via, 1", postalCode:"50013",

city:"Zaragoza",country:"ES"}],

emails:[{email:'[email protected]'}]});


221 TTAK.OT-10.0323

DOMString additionalInformation

최종적으로 세분화된 정확한 주소지를 일컫는 것으로 가령 건물 내 호실 번호,

아파트 동 번호, 룸 이름, 오피스 거주자 이름 등으로 구성된다.

DOMString postalCode

해당 지역의 우편번호를 지칭(미국의 경우 zip code 가 여기에 해당)

사. ContactAddress

contact 의 address 객체 및 address type 속성을 포함한다.

[Callback, NoInterfaceObject] interface ContactAddress : Address

{

attribute StringArray types;

};

코드 예제

속성

StringArray types

address type 에 대한 list 와는 무관함

좀 더 자세한 내용은 RFC 2426, Section 3.2.1 을 참조할 것.

최소한 다음과 같은 값들이 지원되어야 한다.

• WORK - work address 를 지칭

• PREF - preferred address 를 지칭

• HOME - home address 를 지칭


var contactAddress = {streetAddress:"Gran Via,

32",postalCode:"50013",city:"Zaragoza",

country:"ES",types:['WORK','PREF']};

contact.contactAddress = [contactAdress];


222 TTAK.OT-10.0323

아. PhoneNumber

전화번호의 number 와 type 을 포함하는 PhoneNumber object

[Callback, NoInterfaceObject] interface PhoneNumber

{

attribute DOMString number;


};

이 인터페이스는 전화번호 그 자체와 번호의 type 으로서, 가령 직장, 가정,

자동차번호 등과 같은 타입이나 또는 팩스번호, 유무선 전화번호 등과 같은 타입을

제공한다.

좀 더 자세한 내용은 RFC 2426, Section 3.3.1 을 참고한다.

코드 예제

속성

DOMString number

전호번호의 전체(full)번호

StringArray types

RFC 2426 에 정의된 바와 같이 전화 타입에 대한 리스트를 제공한다.

사용하고자 하는 전화번호를 규정한다.

여기에는 최소 다음과 같은 값들이 지원되어야 한다.

• WORK - 직장의 번호를 지칭

• PREF – preferred 인 번호를 지칭

• HOME - 집 번호를 지칭

• VOICE – 음성번호(voice number) (디폴트)를 지칭


var phoneNumber = {number:"666666666",types:['WORK','VOICE']};

contact.phoneNumbers = [phoneNumber];


223 TTAK.OT-10.0323

• FAX - 팩스번호를 지칭

• MSG – 메시징 서비스번호를 지칭

• CELL – 이동전화번호를 지칭

• PAGER – 페이저 번호를 지칭

• BBS – 게시판 서비스의 번호를 지칭

• MODEM - 모뎀 번호를 지칭

• CAR – 카폰번호를 지칭

• ISDN - ISDN 번호를 지칭

• VIDEO – 비디오폰 번호를 지칭

• PCS – 개인통신규격(Personal Communication Standard)

자. EmailAddress

이메일 주소와 그 주소의 타입(type)을 포함하는 EmailAddress 객체

[Callback, NoInterfaceObject] interface EmailAddress

{

attribute DOMString email;


};

더 자세한 내용은 RFC 2426, Section 3.3.2 을 참조할 것.

코드 예제

속성

DOMString email

이메일 주소의 전체(full) 주소

StringArray types

이메일 type 에 대한 list 와는 무관하다.

사용하고자 하는 이메일 주소를 규정한다.

여기에는 최소한 다음과 같은 값들이 지원되어야 한다:


var email = {email:"[email protected]",types:['WORK','PREF']};

contact.emails = [email];


224 TTAK.OT-10.0323

• WORK - 직장의 email 을 지칭

• PREF - preferred 한 email 을 지칭

• HOME - 집 email 을 지칭

차. ContactFilter

findContacts 메소드에 의해 반환이 된 항목들을 규정하는 filter.

[Callback, NoInterfaceObject] interface ContactFilter { attribute DOMString id; attribute DOMString firstName; attribute DOMString lastName; attribute DOMString phoneticName; attribute DOMString nickname; attribute DOMString phoneNumber; attribute DOMString email; attribute Address address; };

filter 가 findContacts 메소드에 제공이 될 때 이 방법에 의한 result-set 에는 filter

value 들과 match 가 된 주소록에 있는 contactt entry 만을 반드시 포함하여야 한다.

contact 의 속성이 filter 의 모든 속성들과 일치가 되는 경우 해당 contact 는

filter 와 match 가 된 것으로 간주한다. 만일 filter 가 null 값이나 미 정의된 값을

포함하고 있는 경우, 이 값들은 무시되어야 하는 바, 즉 SQL 의 "AND" 동작에서와

같은 방식으로 serch 가 이루어져야 한다.

contact 의 한 속성은 다음에 설명하는 규칙(rule)을 통해 filter 값과 match 가

이루어진다.

• DOMString type 인 filter 속성에 있어, 자신과 대응하는 속성이 이 filter 속성과

완전히 일치하는 경우 entry 는 이 값과 match 가 이루어지는 것으로 간주한다.

그러나 filter 에 U+0025 'PERCENT SIGN' 와일드카드 문자가 포함이 된 경우에는

그 filter 거동이 SQL 에서의 LIKE 조건과 유사하다.('%' 와일드카드문자는 길이가

0 인 값을 포함하여 모든 길이의 string 값과 match 가 가능하다) 개발자가

와일드카드 형식으로 interpret 하지 않고 'PERCENT SIGN' 문자를 literally 하게

규정을 하고자 할 경우, 와일드카드 대신에 backslash 문자(\)의 사용을 고려해

볼 수 있다. Matching 은 sensitive 한 것이 아니기 때문에 가령 "FOO"는"foo"나

"f%" filter 로도 match 가 가능하다.


225 TTAK.OT-10.0323

속성

DOMString id

Contact id 속성을 필터링 하는 데 사용됨.

이 제공된 속성과 match 가 되는(서로 일치하게 match 될 수도 있고 또는 특정한

와일드카드를 포함하여 match 가 될 수도 있다) id 속성을 가진 contact 들이

filtering criteria 에 match 된다.

DOMString firstName

Contact firstName 속성을 필터링 하는 데 사용됨


와일드카드를 포함하여 match 가 될 수도 있다) firstName 속성을 가진

contact 들이 filtering criteria 에 match 된다.

DOMString lastName

Contact lastName 속성을 필터링 하는 데 사용됨.


와일드카드를 포함하여 match 가 될 수도 있다) lastName 속성을 가진


DOMString phoneticName

Contact phoneticName 속성을 필터링 하는 데 사용됨.


와일드카드를 포함하여 match 가 될 수도 있다) phoneticName 속성을 가진


DOMString nickname

Contact nickNames 속성을 필터링 하는 데 사용됨


와일드카드를 포함하여 match 가 될 수도 있다) nickNames 어레이에서 최소

하나 이상의 element 를 갖는 contact 들이 filtering criteria 에 match 된다.


226 TTAK.OT-10.0323

DOMString phoneNumber

Contact phoneNumbers 속성을 필터링 하는 데 사용됨.


와일드카드를 포함하여 match 가 될 수도 있다) phoneNumbers 어레이에서 최소

하나 이상의 phone number 를 갖는 contact 들이 filtering criteria 에 match 된다.

DOMString email

Contact email 속성을 필터링 하는 데 사용됨.

이 제공된 속성과 match 가 되는(서로 일치하게 match 될 수도 있고 또는

와일드카드를 포함하여 match 가 될 수도 있다) emails 어레이에서 최소 하나

이상의 email address 를 갖는 contact 들이 filtering criteria 에 match 된다.

Address address

contact address 속성을 필터링 하는 데 사용됨.

제공된 address 객체에 있는 모든 특정한 address 속성들과 match 가 되는(서로

일치하게 match 될 수도 있고 또는 와일드카드를 포함하여 match 가 될 수도

있다) address 어레이 중에서 address 를 최소 하나 이상을 갖는 contact 들이

filtering criteria 에 match 된다. 만약 제공된 address 객체에 있는 어떤 속성에서

null 값을 갖거나 또는 미 정의된 값을 갖는 경우, 이것들을 무시할 수 있다.

카. ContactArraySuccessCallback

contact 들의 list 를 retrieve 할 때 사용되는 success callback.


ContactArraySuccessCallback {

void onsuccess(in ContactArray contacts);

};

입력 인수로서 contact 들의 어레이를 갖는 success 콜백은 비동기적 조작으로

contact 들의 리스트를 획득할 때 사용된다.


227 TTAK.OT-10.0323

Method

onsuccess

contact 들의 리스트이 성공적으로 retrieve 되면 메소드가 invoke 된다.

서명


파라미터

• contacts

o Optional: No. o Type: Contact 어레이. o 설명: contact 들의 list.

타. AddContactSuccessCallback

주소록에 contact 를 추가(add)하기 위한 success callback.


AddContactSuccessCallback {

void onsuccess(in Contact contact);

};

입력 인수로서 하나의 contact 를 갖는 success 콜백은 비동기적 조작으로

주소록에 하나의 contact 를 추가(add)할 때 사용된다.

Methods

onsuccess

contact 가 주소록에 성공적으로 추가(add)되면 메소드가 invoke 된다

서명


파라미터

• contact

o Optional: No. o Type: Contact. o 설명: 주소록에 추가 된 contact


228 TTAK.OT-10.0323

파. AddressBookArraySuccessCallback

주소록들의 list 를 retrieve 할 때의 success callback


AddressBookArraySuccessCallback {

void onsuccess(in AddressBookArray addressbooks);

};

입력 인수로서 AddressBooks 의 어레이를 갖는 success 콜백은

getAddressBooks 를 비동기적 조작으로 획득할 때 사용된다.

Method

onsuccess

주소록들의 리스트가 성공적으로 retrieve 되면 메소드가 invoke 된다

서명


파라미터

• addressbooks

o Optional: No.

o Type: AddressBook 어레이.

o 설명: 주소록.

4.9.5. Type Definitions

가. AddressBook어레이

AddressBook 객체들의 어레이.

typedef sequence<AddressBook> AddressBookArray;

나. Contact어레이

Contact 객체들의 어레이.

typedef sequence<Contact> Contact 어레이;


229 TTAK.OT-10.0323

다. honeNumberArray

PhoneNumber 객체들의 어레이.

typedef sequence<PhoneNumber> PhoneNumberArray;

라. EmailAddressArray

EmailAddress 객체들의 어레이.

typedef sequence<EmailAddress> EmailAddressArray;

마. ContactAddressArray

Address 객체들의 어레이.

typedef sequence<ContactAddress> ContactAddressArray;

4.9.6. Features

Feature 가 다음과 같은 feature 이거나:

• http://wacapps.net/api/pim.contact

또는 tree 에서 상기 feature 의 하부 feature 가 성공적으로 request 된 경우,

ContactManager 인터페이스가 표출되며, 여기서 보이는 객체는 국제적인(전역)

namespace 로서 pim.contact 를 갖는다.

이것은 위젯 config.xml 을 사용하기 위해 API 의 feature 들을 선언하고자 할 때

사용이 되는 URL 리스트이고, 여기에 포함되어 있는 함수들의 list 가 아래에

제공되어 있다.

http://wacapps.net/api/pim.contact.read

addContact(), deleteContact(), updateContact()을 제외한 전체 모듈에 대한

접근.

http://wacapps.net/api/pim.contact.write

findContacts()을 제외한 전체 모듈에 대한 접근..

http://wacapps.net/api/pim.contact

이 모듈에서의 모든 feature 들에 대한 접근


230 TTAK.OT-10.0323

4.9.7. Full WebIDL

module contact {


typedef sequence<Contact> ContactArray;




[NoInterfaceObject] interface ContactManagerObject {


};







successCallback,



};







successCallback,


in Contact contact)




231 TTAK.OT-10.0323


in Contact contact)




in DOMString id)



successCallback,




};



};










};


{







232 TTAK.OT-10.0323



};


{


};


{



};


{



};

[Callback, NoInterfaceObject] interface ContactFilter {





attribute DOMString nickname;

attribute DOMString phoneNumber;


attribute Address address;

};




};




};


233 TTAK.OT-10.0323




};

};


234 TTAK.OT-10.0323

4.10. 캘린더(calendar) 모듈

4.10.1. 요약

단말의 캘린더 모듈에 대한 API 표준.



CalendarManagerObject

CalendarManager PendingOperation

getCalendars(CalendarArraySuccessCallback


Calendar Event createEvent(EventProperties eventProperties)

PendingOperation addEvent(AddEventSuccessCallback

successCallback, ErrorCallback errorCallback, Event event)

PendingOperation updateEvent(SuccessCallback

successCallback, ErrorCallback errorCallback, Event event)

PendingOperation deleteEvent(SuccessCallback

successCallback, ErrorCallback errorCallback, DOMString id)

PendingOperation findEvents(EventArraySuccessCallback

successCallback, ErrorCallback errorCallback, EventFilter

filter)

EventProperties

Event

EventFilter

EventsArraySuccessCallback void onsuccess(EventsArray obj)

AddEventSuccessCallback void onsuccess(Event event)

CalendarArraySuccessCallback void onsuccess(CalendarArray obj)


235 TTAK.OT-10.0323

4.10.3. 개요

캘린더 모듈은 사용자가 자신의 일정관리는 물론 별도의 캘린더를 만들어 하나의

그룹으로 이벤트(event)들을 관리할 수 있도록 해 준다. 예를 들어 업무일정,

개인일정, 가족일정 등에 대한 캘린더 관리가 그것이다. 캘린더 모듈에서 entry

하나는 하나의 이벤트를 가리키며 가령 일정의 내용, 시작시간, 기간 등과 같은

일련의 속성으로 이루어져 있다. 따라서 캘린더는 이와 같은 이벤트들의 집합이라

할 수 있다.

RFC 5545 - Internet Calendaring and Scheduling Core Object Specification

(iCalendar), 에서는 각 이벤트들을 교환하는 포맷(format)에 대해 정의하고 있다.

본 API 는 바로 이 규격를 참고하여 이벤트의 속성을 규정하는데 매핑을 하였다.

본 API 는 캘린더 모듈을 통해 읽기, 생성, 삭제, 업데이트가 기능적으로 가능하도록

하였다. 캘린더는 calendar 객체의 어레이를 반환하는 getCalendars 메소드를

사용하여 획득될 수 있다.

4.10.4. 인터페이스

가. CalendarManagerObject (캘린더매니저 객체)

CalendarManagerObject(캘린더 매니저 객체 함수)는 deviceapis.pim 객체를 통해

API 캘린더에 접근할 수 있도록 한다.

[NoInterfaceObject] interface CalendarManagerObject{

readonly attribute CalendarManager calendar;

};

Pim implements CalendarManagerObject;

나. CalendarManager

calendar manager 는 기능적으로 다음과 같은 모듈에 접근하도록 한다.

[NoInterfaceObject] interface CalendarManager {

const short SIM_CALENDAR = 0;

const short DEVICE_CALENDAR = 1;

const short NO_RECURRENCE = 0;

const short DAILY_RECURRENCE = 1;


236 TTAK.OT-10.0323

const short WEEKLY_RECURRENCE = 2;

const short MONTHLY_RECURRENCE = 3;

const short YEARLY_RECURRENCE = 4;

const short TENTATIVE_STATUS = 0;

const short CONFIRMED_STATUS = 1;

const short CANCELLED_STATUS = 2;

const short NO_ALARM = 0;

const short SILENT_ALARM = 1;

const short SOUND_ALARM = 2;

PendingOperation getCalendars(in CalendarArraySuccessCallback

successCallback,



};

이 인터페이스는 캘린더 모듈에서의 캘린더와 속성에 접근하는 방법을 제공한다.

캘린더 객체가 일단 획득이 되면 calendar interface 메소드를 통해 캘린더에

보관되어 있는 정보들을 추가/삭제 또는 업데이트가 가능하다.

상수

short SIM_CALENDAR

SIM Calendar 를 식별하는 데 사용되는 상수.

short DEVICE_CALENDAR

Device Calendar 를 식별하는 데 사용되는 상수.

short NO_RECURRENCE

calendar entry 가 1 번 발생


237 TTAK.OT-10.0323

short DAILY_RECURRENCE

calendar entry 가 매일 발생

short WEEKLY_RECURRENCE

calendar entry 가 매주 발생

short MONTHLY_RECURRENCE

calendar entry 가 매월 발생

short YEARLY_RECURRENCE

calendar entry 가 매년 발생

short TENTATIVE_STATUS

한시적인 calendar entry

short CONFIRMED_STATUS

confirmed 된 calendar entry

short CANCELLED_STATUS

취소된 calendar entry

short NO_ALARM

alarm 이 없는 calendar entry

short SILENT_ALARM

silent alarm 을 갖는 calendar entry

short SOUND_ALARM

sound 를 동반하는 alarm 을 갖는 calendar entry


238 TTAK.OT-10.0323

메소드(Method)

getCalendars

Calendar 객체의 어레이를 획득.

서명

PendingOperation getCalendars(CalendarArraySuccessCallback,

successCallback 및 optional 한 ErrorCallback errorCallback 의 경우);

입력 파라미터가 동 파라미터에 대한 타입과 연동되지 않을 경우

TYPE_MISMATCH_ERR 코드를 갖는 DeviceAPIError 에러가 반드시 동기적으로

throw 되어야 한다.

만일 successCallback 이 함수를 갖고 있지 않는 경우(즉 null 을 포함하고 있는

경우) DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는 errorCallback 를

생성시켜야 한다.

만일 이 feature 가 지원되는 않는다면 NOT_SUPPORTED_ERR 코드를 갖는

DeviceAPIError 가 errorCallback 에 반환되어야 한다.

만일 이 기능성이 허용되지 않을 경우에는 SECURITY_ERR 코드를 갖는

DeviceAPIError 와 함께 errorCallback 이 invoke 되어야 한다.

만일 조작이 성공적으로 완료가 되면 획득된 모든 calendar 에 대해

successCallback 이 invoke 되어야 한다.

이때 획득된 calendar 가 없을 경우라면 successCallback 은 빈 어레이(empty

array)로 invoke 된다.

Calendar 를 획득하는 시도 과정에서 만일 다른 타입의 에러가 발생한 경우

invocation 에 pass 되었던 errorCallback 함수는 UNKNOWN_ERR 코드와 함께

DeviceAPIError 객체를 포함하여 호출된다.

상기에 설명한 여러 예시들 중의 어느 하나에서 errorCallback 이 invoke 되어야

할 경우, 만일 개발자가 유효한 ErrorCallback(가령 null 값 또는 미 정의된)을

pass 하지 않았다면 동 기능을 요구하지 않은 것이므로 개발자에게 에러내용이

통지되지 않는다.


239 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: 없음

o Type: CalendarArraySuccessCallback.

o 설명: invocation 이 성공적으로 수행이 되면 함수가 호출됨

• errorCallback

o Optional: 있음.


o 설명: error 가 발생하면 함수가 호출됨

반환값(Return value)

비동기적 호출을 취소하기 위한 PendingOperation

예외(Exceptions)

• DeviceAPIError:

입력 파라미터가 동 파라미터에 대응하는 형식과 연동되지 않을 경우

TYPE_MISMATCH_ERR 를 갖는 에러


240 TTAK.OT-10.0323

코드 예제

var calendar;

function eventUpdatedCB() {

// The event has been successfully updated

alert('Event Successfully updated'); }

function eventFoundCB(events) { // The event has been successfully found

// Let's try to change the summary

events[0].summary = "HTML6 Webinar"; calendar.updateEvent(eventUpdatedCB, errorCallback, events[0]);

}

function eventAddedCB(event) {

// The event has been successfully added

// Let's try to check if we can retrieve the added event from the calendar // If the calendar was empty only the item added through addEvent

should

// be returned list.findEvents(eventFoundCB, errorCallback, {summary:'%HTML5%'});

}



alert( "The following error occurred: " + response.code); }

// Define the success callback for retrieveing the list of calendars function calendarListCB(calendars) {

if(calendars.length > 0)

{ calendar = calendars[0];

alert("The calendar type is " + calendar.type +

" and name " + calendar.name);

var event = calendar.createEvent({description:'HTML5 Introduction',

summary:'HTML5 Webinar ', startTime: new Date(2011, 3, 30, 10, 0),

duration:60

location:'Huesca' }); calendar.addEvent(eventAddedCB, errorCallback, event);

}

}

// Get a list of available calendars.

deviceapis.pim.calendar.getCalendars(calendarListCB, errorCallback);


241 TTAK.OT-10.0323

다. 캘린더(Calendar)

캘린더 객체(calendar object)

[NoInterfaceObject] interface Calendar {



Event createEvent(in optional EventProperties eventProperties)


PendingOperation addEvent(in AddEventSuccessCallback successCallback,


in Event event)


PendingOperation updateEvent(in SuccessCallback successCallback,


in Event event)


PendingOperation deleteEvent(in SuccessCallback successCallback,


in DOMString id)


PendingOperation findEvents(in successCallback,


in optional EventFilter filter)


};

calendar 에는 일련의 이벤트들을 포함한다. 이 인터페이스는 캘린더에서 다음과

같이 이벤트들을 관리하는 메소드를 제공한다.

• key-value filter 를 사용한 이벤트찾기.

• addEvent() 메소드를 사용하여 특정 캘린더에 이벤트를 추가하기.

• updateEvent() 메소드를 사용하여 기존 이벤트를 업데이트 하기.

• deleteEvent() 메소드를 사용하여 기존 이벤트를 삭제하기.


242 TTAK.OT-10.0323

속성(Attributes)

readonly short type

Calendar Type.

Calendar type 에는 반드시 다음 중 하나의 상수를 포함하고 있어야 한다.

• SIM_CALENDAR = 0

• DEVICE_CALENDAR = 1

속성은 readonly(읽기전용)이다.

코드 예제


읽을 수 있는 캘린더 name 으로서 가령 업무, 인명 등이다.


코드 예제

// Define the success callback. function calendarsRetrieved(calendars) { alert("The calendar type is " + calendars[0].type); } // Define the error callback. function errorCallback(response) { alert( "The following error occurred: " + response.code); } // Get a list of available calendars. deviceapis.pim.calendar.getCalendars(calendarsRetrieved, errorCallback);

// Define the success callback. function calendarsRetrieved(calendars) { alert("The calendar name is " + calendars[0].name); } // Define the error callback. function errorCallback(response) { alert( "The following error occurred: " + response.code); } // Get a list of available calendars. deviceapis.pim.calendar.getCalendars(calendarsRetrieved, errorCallback);


243 TTAK.OT-10.0323

메소드(Methods)

createEvent

일련의 EventProperties 를 갖는 이벤트 객체에 대해 인스턴스를 생성한다.

서명

Event createEvent(in optional EventProperties eventProperties);

입력 파라미터가 동 파라미터에 대한 타입과 연동되지 않을 경우




DeviceAPIError 가 반드시 throw 되어야 한다.

만일 pass 된 이벤트가 하나 이상의 EventProperties 속성에 대해 유효하지 않은

값을 포함하고 있을 경우 INVALID_VALUES_ERR 코드를 갖는 DeviceAPIError 가

반드시 throw 되어야 한다.

만일 eventProperties 속성이 omitted 되거나 또는 null 로 된 경우라면, 디폴트

값이 모든 이벤트 속성들에 할당이 되면서 이벤트 인터페이스에 대한

인스턴스생성을 시도하도록 implementation 이 구성되어야 한다. 그러나 입력

파라미터로 pass 된 eventProperties 속성이 (유효한 값으로) 동 EventProperties

속성의 subset 속성만을 포함하고 있는 경우라면, 아무런 value 를 갖지 않고

있는 속성에 디폴트 값를 할당하면서 이벤트 인터페이스에 대한 인스턴스생성을

시도하도록 implementation 이 구성되어야 한다. 만일 입력 파라미터로 pass 된

eventProperties 가 모든 EventProperties 속성에 대해 유효한 값들을 포함하고

있는 경우에는 implementation 이 이벤트 인터페이스의 인스턴스를 생성하도록

시도하여야 한다.

이벤트의 인스턴스가 성공적으로 생성이 된 경우, 인스턴스는 이 방법에 의해

반환이 되어야 한다. 그러나 생성 과정에서 에러가 발생한 경우에는 메소드 상

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 를 반드시 throw 시켜야 한다.

이 operation 은 생성된 이벤트 객체를 캘린더에 추가시키지 않을 뿐만 아니라

또한 동 이벤트 객체에 식별자(id 속성)를 할당 하지도 않는다. 그러나 개발자가

addEvent 메소드로써 invoke 하는 경우에는 상기와는 반대로 이벤트객체를

캘린더에 추가하고 식별자(id 속성)을 이벤트객체에 할당하는 것이 가능하다


244 TTAK.OT-10.0323

파라미터

• eventProperties

o Optional: 있음

o Type: EventProperties.

o 설명: 이벤트 정보.


생성된 이벤트 객체.

예외(Exceptions)

• DeviceAPIError:

입력 파라미터가 동 파라미터에 대응하는 형식과 연동되지 않을 경우

TYPE_MISMATCH_ERR 를 갖는 에러

eventProperties 의 입력 파라미터가 유효하지 않은 값을 포함하고 있는

경우 INVALID_VALUES_ERR 코드를 갖는 에러

이 feature 가 지원되지 않는 경우 NOT_SUPPORTED_ERR 코드를 갖는

에러

이벤트의 인스턴스를 생성하는 과정에서 에러가 발생한 경우

UNKNOWN_ERR 코드를 갖는 에러

코드 예제

// Define the error callback. function errorCallback(response) { alert( "The following error occurred: " + response.code); } function eventAddedCB(event) { alert("Event successfully added with id " + event.id); } // Define the success callback. function calendarListSuccessCallback(calendars) { var event = calendar.createEvent({description:'HTML5 Introduction', summary:'HTML5 Webinar ', startTime: new Date(2011, 3, 30, 10, 0), duration:60 location:'Huesca' }); calendar.addEvent(eventAddedCB, errorCallback, event); } // Get a list of available calendars. deviceapis.pim.calendar.getCalendars(calendarListSuccessCallback, errorCallback);


245 TTAK.OT-10.0323

addEvent

캘린더에 이벤트를 비동기적으로 추가한다.

서명

PendingOperation addEvent(in AddEventSuccessCallback successCallback, in

ErrorCallback errorCallback, in Event event);

어떤 입력 파라미터가 동 파라미터에 대한 타입과 연동되지 않을 경우




DeviceAPIError 가 반드시 errorCallback 으로 반환되어야 한다.




유효하지 않은 값이 포함되어 있거나, 또는 이벤트에 유효하지 않은 값이 포함된

경우나 캘린더에서 contact 항목을 입력하는 것이 잘 되지 않는 경우(가령

텍스트 값의 크기의 제한) 반드시 request 를 거절하면서 DeviceAPIError 와

INVALID_VALUES_ERR 코드를 갖는 errorCallback 을 invoke 시키도록

implementation 이 구성되어야 한다. 그러나 개발자가 에러들을 무시할 수

있도록 허용하려면 errorCallback 은 null 값을 유효한 값으로 인식하도록 해야

한다.

이벤트가 캘린더에 성공적으로 추가가 이루어진 경우 successCallback 이

invoke 되어야 한다. 이 successCallback 에는 추가된 이벤트에 대한 이벤트

요소(element)와 부여된 id 속성을 포함한다.

이벤트항목을 추가하는 과정에서 만일 어떤 다른 에러가 발생한 경우,

invocation 에 pass 된 errorCallback 함수는 UNKNOWN_ERR 코드를 갖는

DeviceAPIError 객체와 함께 반드시 호출이 되어야 한다.






246 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: 없음.

o Type: AddEventSuccessCallback.

o 설명: invocation 이 성공적으로 종료되면 함수가 호출됨.

• errorCallback

o Optional: 없음.


o 설명: 에러가 발생할 때 함수가 호출됨

• event

o Optional: 없음.

o Type: 이벤트.

o 설명: 이벤트 객체가 저장 터미널에 추가가 됨.



예외(Exceptions)

• DeviceAPIError:

입력 파라미터가 동 파라미터에 대응하는 타입과 연동되지 않을 경우

TYPE_MISMATCH_ERR 코드를 갖는 에러

코드 예제

// Define the error callback. function errorCallback(response) { alert( "The following error occurred: " + response.code); } function eventAddedCB(event) { alert("Event successfully added with id " + event.id); } // Define the success callback. function calendarListSuccessCallback(calendars) { var event = calendar.createEvent({description:'HTML5 Introduction', summary:'HTML5 Webinar ', startTime: new Date(2011, 3, 30, 10, 0), duration:60 location:'Huesca' }); calendar.addEvent(eventAddedCB, errorCallback, event); } // Get a list of available calendars. deviceapis.pim.calendar.getCalendars(calendarListSuccessCallback, errorCallback);


247 TTAK.OT-10.0323

updateEvent

기존의 이벤트를 비동기적으로 캘린더에 업데이트 한다.

서명

PendingOperation updateEvent(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in Event event);




만일 이벤트를 업데이트 하는 feature 가 지원되는 않는다면

NOT_SUPPORTED_ERR 코드를 갖는 DeviceAPIError 가 반드시

errorCallback 으로 반환되어야 한다.




유효하지 않은 값이 포함되어 있거나, 또는 이벤트에 유효하지 않은 값이 포함된

경우나 캘린더에서 이벤트를 업데이트하는 것이 불가능한 경우(가령 텍스트 값의

크기의 제한) 반드시 request 를 거절하면서 DeviceAPIError 와




한다.

입력된 이벤트가 유효한 값들을 포함하고는 있으나 그 id 속성이 캘린더에 있는

기존의 이벤트들의 타 id 속성들과 서로 대응(correspond)되는 것을 찾을 수

없는 경우(즉 업데이트된 이벤트를 찾을 수 없는 경우) NOT_FOUND_ERR 코드를

갖는 DeviceAPIError 가 반드시 반환되어야 한다.

반대로 입력된 이벤트의 id 속성에 대응하는 이벤트가 캘린더에 존재하는 경우,

implementation 은 동 이벤트를 새로운 값을 갖는 identifier 에 부응하도록

반드시 업데이트 시도를 하여야 한다. 그 후 성공적으로 업데이트가 완료되면

SuccessCallback 이 반드시 invoke 되어야 한다.

이벤트 항목을 추가하는 과정에서 상기에서 설명한 경우의 수가 아닌 다른

타입의 에러상황이 발생한 경우, invocation 에 pass 가 된 errorCallback 함수가,


248 TTAK.OT-10.0323

입력 인수로 pass 가 되었던 것으로 UNKNOWN_ERR 코드를 갖는

DeviceAPIError 객체와 함께 반드시 호출되어야 한다.





파라미터

• successCallback

o Optional: 없음.



• errorCallback

o Optional: 없음.



• event

o Optional: 없음.

o Type: 이벤트.

o 설명: 이벤트 객체를 업데이트 함.



예외(Exceptions)

• DeviceAPIError:




249 TTAK.OT-10.0323

코드 예제

var calendar;

// Define the event update success callback.

function eventUpdateSuccessCallback(response) {

alert("Updated");

}

// Define the event success callback.

function eventSearchSuccessCallback(events) {

events[0].description = "New Description";

// Update the first existing event.

calendar.updateEvent(eventUpdateSuccessCallback,

errorCallback, events[0]);

}

// Define the calendar lists success callback.

function calendarListSuccessCallback(calendars) {

calendar = calendars[0];

// Find all events in Calendar at position 0.

calendar.findEvents(eventSearchSuccessCallback,

errorCallback, null);

}




}


deviceapis.pim.calendar.getCalendars(calendarListSuccessCallback,

errorCallback);


250 TTAK.OT-10.0323

deleteEvent

비동기적으로 캘린더에 있는 이벤트를 삭제한다.

서명

PendingOperation deleteEvent(in SuccessCallback successCallback, in









만일 successCallback 이 null 값이나 미정의된 유효한 함수를 포함하지 않는

경우, INVALID_VALUES_ERR 코드를 갖는 DeviceAPIError 가 반드시

errorCallback 에 반환되어야 한다.

id 파라미터가 캘린더에 있는 이벤트들의 타 id 속성들과 서로

대응(correspond)되는 것을 찾을 수 없는 경우(즉 삭제할 이벤트가 존재하지

않는 경우) NOT_FOUND_ERR 코드를 갖는 DeviceAPIError 가 반드시

errorCallback 으로 반환되어야 한다.


implementation 은 동 identifier 에 부응하는 이벤트를 삭제하는 시도를 하여야

한다.

그 후 성공적으로 업데이트가 완료되면 SuccessCallback 이 반드시


이벤트를 삭제하는 과정에서 상기에서 설명한 경우의 수가 아닌 다른 타입의

에러가 발생한 경우, invocation 에 pass 가 된 errorCallback 함수가,

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체와 함께 반드시 호출되어야

한다.




251 TTAK.OT-10.0323



파라미터

• successCallback

o Optional: 없음.



• errorCallback

o Optional: 없음.



• id

o Optional: 없음

o Nullable: 없음

o Type: DOMString.

o 설명: 이벤트 객체의 identifier(id 속성)를 삭제함



예외(Exceptions)

• DeviceAPIError:




252 TTAK.OT-10.0323

코드 예제

var calendar;

// Define the delete event success callback.

function eventDeleteSuccessCallback(response) {

alert("Deleted");

}

// Define the event success callback.


// Delete the first existing event.

calendar.deleteEvent(eventDeleteSuccessCallback,

errorCallback, events[0].id);

}



calendar = calendars[0];

// Find all events in Calendar at position 0.

calendar.findEvents(eventSearchSuccessCallback,


}




}



errorCallback);


253 TTAK.OT-10.0323

findEvents

캘린더에 저장된 이벤트들의 이벤트 객체 어레이를 획득하고 optional 한

경우로서 제공된 filter 와 match 를 시킨다.

서명

PendingOperation findEvents(in EventArraySuccessCallback successCallback,

in optional ErrorCallback errorCallback, in optional EventFilter filter);








만일 successCallback 이 null 값이나 미 정의되어 유효한 함수를 포함하지 않는

경우, INVALID_VALUES_ERR 코드를 갖는 DeviceAPIError 가 반드시

errorCallback 에 반환되어야 한다.

만일 filter 가 pass 되고 정상적으로 유효한 값들을 포함하고 있다면, EventFilter

인터페이스에서 정의하였던 필터기준(filter criteria)에 match 가 되는 캘린더의

값들만이 successCallback 에 반환이 된다. 그러나 pass 가 된 filter 가 없다거나

또는 filter 에 유효하지 않은 값이 하나라도 포함이 되거나 null 또는 미 정의인

경우에는, implementation 은 모든 이벤트의 항목 list 를 다 successCallback 에

반환하도록 하여야 한다. 만일 캘린더에 이벤트가 하나도 없다거나(즉 비어있는

경우) 또는 필터기준에 match 되는 이벤트를 찾을 수 없는 경우,

successCallback 은 빈 어레이(empty array) 상태로 invoke 시킨다..


implementation 은 동 identifier 에 부응하는 이벤트를 삭제하는 시도를 하여야

한다.

그 후 성공적으로 업데이트가 완료되면 SuccessCallback 이 반드시


이벤트를 retrieve 하는 과정에서 상기에서 설명한 경우의 수가 아닌 다른 타입의

에러가 발생한 경우, invocation 에 pass 가 된 errorCallback 함수가,


254 TTAK.OT-10.0323

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체와 함께 반드시 호출되어야

한다.





파라미터

• successCallback

o Optional: 없음.

o Type: EventArraySuccessCallback.


• errorCallback

o Optional: 있음.



• filter

o Optional: Yes.

o Type: EventFilter.

o 설명: 제공된 데이터가 find 방법을 통한 결과를 filter 하는 데

사용이 됨.



예외(Exceptions)

• DeviceAPIError:




255 TTAK.OT-10.0323

코드 예제




}

// Define the event search success callback.


alert(events.length + " results found.");

}



// Find all events in the first calendar that contains in the summary

// the string WAC.

calendars[0].findEvents(eventSearchSuccessCallback,

errorCallback,

{summary:"%WAC%");

}



errorCallback);


256 TTAK.OT-10.0323

라. EventProperties

이벤트 생성을 위해 사용되는 인터페이스

[Callback, NoInterfaceObject] interface EventProperties {

attribute DOMString description;

attribute DOMString summary;

attribute Date startTime;

attribute long duration;

attribute DOMString location;

attribute StringArray categories;

attribute short recurrence;

attribute Date expires;

attribute short interval;

attribute short status;

attribute long alarmTrigger;

attribute short alarmType;

};

Contact 가 생성이 되면 contact properties 를 구성하는 인터페이스를 제공한다.

모든 속성들은 선택사항이고 디폴트에 의해 미정의된다.

속성

DOMString 설명

이벤트 설명

이 속성은 이벤트를 텍스트 문으로 설명할 때 사용이 된다. 이 속성은 summary

속성보다 좀 더 자세하게 이벤트에 대한 정보를 설명적으로 제공할 때 사용된다.

(See RFC 5545 - Section 3.8.1.5).

이 속성의 디폴트값은 empty string 이다.


257 TTAK.OT-10.0323

코드 예제

DOMString summary

이벤트의 요약.

이벤트를 간략히 요약하는 것으로 정의된다. (RFC 5545 - Section 3.8.1.12 참조).


코드 예제

Date startTime

이벤트의 start time(시작시간).

이벤트가 시작되는 시각으로 정의된다.(RFC 5545 - Section 3.8.2.4 참조).

이 속성의 디폴트값은 이벤트가 생성된 바로 그 순간에서의 implementation

date 를 의미한다.

코드 예제

long duration

이벤트의 기간.

이 속성의 디폴트값은 ‘0’이다.

캘린더 컴포넌트(calendar component)의 기간(분 단위임). (RFC 5545 - Section

3.8.2.5 참조).

var event = calendar.createEvent();

event.description = "WAC Codefest";


event.summary = "Launching the WAC reference implementation";


event.startTime = new Date(2010, 3, 30, 9, 0);


258 TTAK.OT-10.0323

DOMString 위치

이벤트의 위치.

이 속성은 이벤트에 의해 정의된 activity 에서 의도한(intended) venue 를

정의한다.(RFC 5545 - Section 3.8.1.7 참조).


코드 예제

StringArray 카테고리

이벤트 카테고리.

이 속성은 이벤트 컨포넌트(event component)의 카테고리나 subtype 를 규정할

때 사용된다. 카테고리를 구성시켜 둘 경우 어떤 캘린더 컴포넌트가 특정한

타입이나 카테고리를 가질 때 이를 검색하는데 유용하다.(RFC 5545 - Section

3.8.1.2 참조).

카테고리의 예들로는 가령 개인일정, 업무일정, 휴가, 여행 등이다.

이 속성의 디폴트값은 미 정의다.

코드 예제

short recurrence

이벤트의 박복.

이 속성에서 유효한 값들로는 다음과 같은 경우들뿐이다.

• NO_RECURRENCE: 이벤트가 1 회 발생

• DAILY_RECURRENCE: 이벤트가 매일 발생

• WEEKLY_RECURRENCE: 이벤트가 매주 발생.

• MONTHLY_RECURRENCE: 이벤트가 매월 발생.

• YEARLY_RECURRENCE: 이벤트가 매년 발생.


event.location = "Huesca";


event.categories = ["Personal"];


259 TTAK.OT-10.0323

이 속성의 디폴트값은 NO_RECURRENCE.이다

코드 예제

Date expires

일련의 반복적 이벤트들의 만료일자

반복속성(recurrence attribute)이 적용될 때까지의 일자와 시간

디폴트에 의해 이 파라미터는 null(0) 값으로 초기화(set)되므로 이벤트는 확정된

만료일자를 가질 수 없는데, 이 말의 의미는 이벤트를 무한으로 반복시켜

스케줄링 할 수 있다는 것을 뜻한다.

이벤트 반복속성을 NO_RECURRENCE 로 설정할 경우 expires 속성은 무시된다.

short interval

반복 이벤트의 빈도(frequency)를 설명한다.

이 속성은 반복속성과 링크되어 있고, interval 을 n 으로 설정할 경우, 반복속성이

n 이 될 때마다 매번 이벤트가 다시 발생한다.

예를 들어 interval 속성을 2 로 맞추고 반복속성을 WEEKLY_RECURRENCE 로

설정시키면, 이벤트는 매 2 주마다 다시 반복된다.

디폴트 인터벌(default interval)의 값은 ‘1’로 되어 있으므로, ‘1’로 설정 된

상태에서 가령 이벤트 반복속성(recurrence attribute)이 DAILY_RECURRENCE 인

경우에는 이벤트가 매일 발생하고, WEEKLY_RECURRENCE 인 경우에는 매주

발생하며, MONTHLY_RECURRENCE 인 경우는 매월, YEARLY_RECURRENCE 인

경우는 매년 발생한다.

반복속성이 NO_RECURRENCE 인 경우, 이 파라미터는 무시된다.

short status

이벤트의 상태.

이 속성은 캘린더 컴포넌트의 전체적인 상태(status) 또는 확인(confirmation)을

정의한다.(RFC 5545 - Section 3.8.1.11 참조).


event.recurrence = deviceapis.pim.calendar.NO_RECURRENCE;


260 TTAK.OT-10.0323

이 속성에서의 유효값들을 리스트 하면 아래와 같다.

• TENTATIVE_STATUS: 이벤트가 tentative 임.

• CONFIRMED_STATUS: 이벤트가 confirmed 됨.

• CANCELLED_STATUS: 이벤트가 cancelled 됨

이 속성의 디폴트값은 CONFIRMED_STATUS 이다.

코드 예제

long alarmTrigger

alarm 을 동작시키는 시간을 규정한다. .

alarm 이 트리거(trigger)되는 시간으로써 분 단위를 가지며 이벤트의 시작(즉

startTime)과 상대적인 연관성을 갖는다. (RFC_5545 - 3.8.6.3 참조).

이 속성에는 음의 기간값과 양의 기간값 둘 다 지원되어야 하며, 여기서

양(positive)이란 이벤트가 start 된 뒤에 alarm 이 동작되어야 함을 의미하며,

음(negative)이란 이벤트가 start 되기 전에 alarm 이 동작되어야 함을 의미한다.

이 속성에서의 디폴트값은 ’0’이다.

만일 alarmType 이 NO_ALARM 값을 갖는 경우 이 속성은 무시된다.

코드 예제

short alarmType

Event Alarm Type.

이 속성은 동작하게 되는 alarm 의 타입(type)을 정의한다.(RFC-5545 - 3.8.6.1

참조).

이 속성에서 가능한 값들로는 다음과 같다.


event.status = deviceapis.pim.calendar.TENTATIVE_STATUS;


event.alarmTrigger = -15;


261 TTAK.OT-10.0323

• NO_ALARM: 이벤트와 링크된 alarm 이 존재하지 않음.

• SOUND_ALARM: 사용자를 환기시킬 목적으로 sound 가 발생함.

• SILENT_ALARM: sound 없이 alarm 이 screen 에 표출됨.

이 속성의 디폴트값은 NO_ALARM 이다.

코드 예제

마. 이벤트

이벤트 객체(Event object).

[NoInterfaceObject] interface Event : EventProperties {


};

이 인터페이스는 EventProperties 를 확장한 개념으로서 즉 하나의 캘린더에 존재하는

단일 이벤트(event)를 추상적으로 객체화한 것이다.

속성들


implementation 에서 이벤트를 지속적이고(persistent) 고유한 값으로(unique)


이 값은 이벤트 항목이 캘린더에 추가가 될 때 플랫폼에서 부여되는 값으로서,

단말기의 사용국가(locally)에서 unique 하고 persistent 한 값이므로 개발자가

임의로 바꿀 수 없다.

이와 같은 고유값 부여를 보증하는 파라미터와 알고리즘에 대한 좀 더 자세한

정보를 얻고자 할 경우 RFC 5545 (section 3.8.4.7)를 참조하기 바란다. 이 값은

addEvent 가 성공적으로 invoke 될 때 플랫폼에서 부여가 된다.

이 속성의 특징은 readonly 이다.


event.alarmType = deviceapis.pim.calendar.NO_ALARM;


262 TTAK.OT-10.0323

바. EventFilter

findEvents 메소드에 의해 반환되는 항목을 제한하는 필터(filter).

[Callback, NoInterfaceObject] interface EventFilter {





attribute DOMString category;

attribute UnsignedShortArray status;

attribute Date initialStartDate;

attribute Date endStartDate;

};

이 함수가 사용될 때 filter 가 findEvents operation 에 제공이 되며 이 방법에 의한

result-set 은 캘린더에서 filter value 들과 match 가 되는 event entry 만을 반드시

포함하여야 한다.

이벤트의 속성이 filter 의 모든 속성들과 일치가 되는 경우 해당 이벤트는 filter 와

match 가 된 것으로 간주한다. 만일 filter 가 null 값이나 미 정의된 값을 포함하고

있는 경우, 이 값들은 무시되어야 하는 바, 즉 SQL 의 "AND" operation 에서와 같은

방식으로 serch 가 이루어져야 한다.

이벤트의 한 속성은 다음에 설명하는 rule 을 통해 filter value 와 match 가

이루어진다.

• DOMString type 인 filter 속성에 있어, 자신과 대응하는 속성이 이 filter 속성과


그러나 U+0025 'PERCENT SIGN' 와일드카드 문자가 사용이 되는 경우에는 그

filter 거동이 SQL 에서의 LIKE 조건과 유사하다.('%' 와일드카드문자는 길이가

0 인 값을 포함하여 모든 길이의 값과 match 가 가능하다) 개발자가 와일드카드

형식으로 interpret 하지 않고 'PERCENT SIGN' 문자를 literally 하게 규정을


263 TTAK.OT-10.0323

하고자 할 경우, 와일드카드 대신에 backslash 문자(\)의 사용을 고려해 볼 수

있다. Matching 은 sensitive 한 것이 아니기 때문에 가령 "FOO"는"foo"나 "f%"

filter 로도 match 가 가능하다.

• Filter 속성이 웹 IDL 의 숫자(numeric)형식인 경우, 이벤트는 대응하는 이벤트

속성의 값이 정확히 자신의 속성값과 같을 때에 한해 filter 속성과 match 가 된다.

만약 filter 속성이 numeric type 으로서 WebIDL 어레이(array)인 경우라면,

캘린더에 대한 entry 는 대응하는 이벤트 속성이 filter 속성의 어레이중의 하나와

꼭 일치하는 값이 존재할 때에 match 가 가능하다.

• date type 인 이벤트 속성(즉 startDate)인 경우, 최초(initial)와 최종(end)의

startDate 의 속성들을 포함시키도록 하는데, 이는 제공된 두 date 들 사이에

존재하는 이벤트들을 search 하기 위함이다. 이 속성들 중 하나나 혹은 둘 다

스펙이 규정되어 졌다면 다음 규칙을 적용한다. A) initialStartDate 와

endStartdate 속성 둘 다 규정된 경우(즉. null(0)이 아닌 다른 값이 지정된 경우)

대응하는 속성의 값이 initial 이든 end 이든, 또는 두 일자 사이이든 상관없이

일치하는 값이 존재할 경우 이벤트는 filter 와 match 가 된다. B) initialStartDate

속성 하나만이 유효한 값을 갖는 경우(즉. null(0)이 아닌 다른 값이 지정된

경우)에는 대응하는 속성이 initial date 와 일치하거나 그 이후일 때 이벤트는

filter 와 match 가 된다. C) endStartDate 속성 하나만이 유효한 값을 갖는

경우(즉. null(0)이 아닌 다른 값이 지정된 경우)에는 대응하는 속성이 end

date 와 일치하거나 그 이전일 때 이벤트는 filter 와 match 가 된다.

속성들

DOMString id

이벤트 id 속성을 필터링 하는 데 사용되는 속성

id 속성을 갖는 이벤트를 정확히 match 하거나 규정된 와일드카드를 갖는 속성과

match 를 해 주며, 제공된 filter 속성은 본 filtering criteria 를 기준으로 match 가

이루어진다.

DOMString summary

Event summary 속성을 필터링 하는 데 사용되는 속성

summary 속성을 갖는 이벤트를 정확히 match 하거나 규정해 준 wildcard 를

갖는 속성과 match 해 주며 제공된 filter 속성은 본 filtering criteria 를 기준으로

match 가 이루어진다.


264 TTAK.OT-10.0323

DOMString description

Event description 속성을 필터링 하는 데 사용되는 속성.

description 속성을 갖는 이벤트를 정확히 match 하거나 규정해 준 wildcard 를

갖는 속성과 match 해 주며 제공된 filter 속성은 본 filtering criteria 를 기준으로

match 가 이루어진다.

DOMString location

Event location 속성을 필터링 하는 데 사용되는 속성

Location(위치) 속성을 갖는 이벤트를 정확히 match 하거나 규정 ify 해 준

wildcard 를 갖는 속성과 match 해 주며 제공된 filter 속성은 본 filtering

criteria 를 기준으로 match 가 이루어진다.

DOMString category

Event categories 속성을 필터링 하는 데 사용되는 속성.

categories 어레이 속성에서 그 한 element 를 갖는 이벤트를 정확히

match 하거나 규정 ify 해 준 wildcard 를 갖는 속성과 match 해 주며 제공된

filter 속성은 본 filtering criteria 를 기준으로 match 가 이루어진다.

UnsignedShortArray status

Event status 속성을 필터링 하는 데 사용되는 속성.

이 어레이의 값들 중 하나의 값과 같은 상태(status)속성을 갖는 이벤트가

filtering criteria 와 match 가 된다.

Date initialStartDate

Event startDate 속성을 필터링 할 때 사용되는 initial 일자.

이 속성과 같거나 더 늦은 startDate 속성을 갖는 이벤트가 filtering criteria 와

match 가 된다.

Date endStartDate

Event startDate 속성을 필터링 할 때 사용되는 end 일자.

이 속성과 같거나 더 빠른 startDate 속성을 갖는 이벤트가 filtering criteria 와

match 가 된다.


265 TTAK.OT-10.0323

사. EventsArraySuccessCallback

캘린더 이벤트들의 list 를 retrieve 하기 위한 Success callback

[Callback=FunctionOnly, NoInterfaceObject] interface EventsArraySuccessCallback

{

void onsuccess(in EventsArray obj);

};

이벤트의 리스트을 획득하는 Success callback 은 비동기적 조작으로 사용이 된다.

Methods

onsuccess

캘린더 이벤트들의 list 가 성공적으로 retrieve 되면 메소드가 invoke 된다. .

서명


파라미터

• obj

o Optional: 없음.

o Type: 이벤트 어레이.

o 설명:이벤트 객체의 어레이.

아. AddEventSuccessCallback

캘린더에 이벤트를 추가시키기 위한 Success callback

[Callback=FunctionOnly, NoInterfaceObject] interface AddEventSuccessCallback

{

void onsuccess(in Event event);

};

Success callback 은 이벤트를 입력 인수로 간주하며, 캘린더에 이벤트를 추가할 때

비동기적 조작으로 사용이 된다.

Methods

onsuccess

캘린더에 이벤트가 성공적으로 add 가 되면 메소드가 invoke 된다


266 TTAK.OT-10.0323

서명


파라미터

• event

o Optional: 없음.

o Type: 이벤트.

o 설명: 이벤트 객체를 캘린더에 추가

자. CalendarArraySuccessCallback

getCalendars 메소드를 위한 Success callback .


CalendarArraySuccessCallback {

void onsuccess(in CalendarArray obj);

};

캘린더 list 를 획득하기 위해 비동기적으로 사용이 되는 Success callback

Methods

onsuccess

캘린더 객체들의 어레이가 성공적으로 retrieve 되면 메소드가 invoke 된다

서명


파라미터

• obj

o Optional: 없음.

o Type: Calendar 어레이.

o 설명: calendar 객체의 어레이.


267 TTAK.OT-10.0323

4.10.5. Type 에 대한 정의

가. EventsArray

이벤트들의 어레이.

typedef sequence<Event> EventsArray;

나. CalendarArray

Calendar 들의 어레이.

typedef sequence<Calendar> CalendarArray;

4.10.6. Features

Feature 가 다음과 같은 feature 이거나

• http://wacapps.net/api/pim.calendar


CalendarManager 인터페이스가 표출되며, 여기서 보이는 객체는 국제

namespace 로서 pim.calendar 를 갖는다.


사용이 되는 URL 리스트이다. 이 각 URL 마다 여러 함수들이 제공되어 있다.

http://wacapps.net/api/pim.calendar.read

addEvent(), deleteEvent(), updateEvent()을 제외한 모든 모듈들에 접근

http://wacapps.net/api/pim.calendar.write

findEvents()을 제외한 모든 모듈들에 접근.

http://wacapps.net/api/pim.calendar

이 모듈을 제외한 모든 모듈들에 접근


268 TTAK.OT-10.0323

4.10.7. Full WebIDL

module calendar {





};

















successCallback,



};








269 TTAK.OT-10.0323


in Event event)




in Event event)




in DOMString id)


PendingOperation findEvents(in successCallback,




};














};



};


270 TTAK.OT-10.0323










};


EventsArraySuccessCallback {


};


{


};




};

};


271 TTAK.OT-10.0323

4.11. 작업(task) 모듈

4.11.1. 요약

본 규격 task 리스트의 관리를 위한 API 표준을 정의한다.



TaskManagerObject

TaskManager PendingOperation

getTaskLists(TaskListArraySuccessCallback


TaskList Task createTask(TaskProperties taskProperties)

PendingOperation addTask(AddTaskSuccessCallback

successCallback, ErrorCallback errorCallback, Task task)

PendingOperation updateTask(SuccessCallback

successCallback, ErrorCallback errorCallback, Task task)

PendingOperation deleteTask(SuccessCallback

successCallback, ErrorCallback errorCallback, DOMString

id)

PendingOperation findTasks(TaskArraySuccessCallback

successCallback, ErrorCallback errorCallback, TaskFilter

filter)

TaskProperties

Task

TaskFilter

TaskArraySuccessCallback void onsuccess(TaskArray tasks)

AddTaskSuccessCallback void onsuccess(Task task)

TaskListArraySuccessCallback void onsuccess(TaskListArray taskLists)


272 TTAK.OT-10.0323

4.11.3. 개요

task list 란 to-do list 로 설명할 수 있는 과제리스트를 말하는 것으로 수행하고자

하는 과제항목들의 집합(리스트)이라 할 수 있다. 또한 하나의 task(과제) 안에는 동

과제의 성격, 상태, 우선순위, 완료일자 등과 같이 task 의 속성를 나타내는 많은

수의 속성들로 구성되어 있다. .

RFC 5545 - Internet Calendaring and Scheduling Core Object Specification

(iCalendar) 은 task 항목들(RFC 5545 터미놀로지를 따르는 과제들)을 교환하는

포멧에 대한 정의를 담고 있다. 이에 본 API 는 상기 규격의 정의 내용들을

차용하여 본 표준서에서 task 속성들을 규정할 때 매핑하여 활용하였음을 밝힌다

4.11.4. 인터페이스

가. TaskManager객체

TaskManager 객체는 deviceapis.pim (객체로부터 API task 로 접근이 가능하도록

한다.

[NoInterfaceObject] interface TaskManagerObject {

readonly attribute TaskManager task;

};

Pim implements TaskManagerObject;

나. TaskManager

Manager class 로서 여러 모듈함수들에 대한 접근을 제공한다.

[NoInterfaceObject] interface TaskManager {

const short SIM_TASK_LIST = 0;

const short DEVICE_TASK_LIST = 1;

const short HIGH_PRIORITY = 0;

const short MEDIUM_PRIORITY = 1;

const short LOW_PRIORITY = 2;

const short STATUS_COMPLETED = 0;


273 TTAK.OT-10.0323

const short STATUS_NEEDS_ACTION = 1;

const short STATUS_IN_PROCESS = 2;

const short STATUS_CANCELLED = 3;

PendingOperation getTaskLists(in TaskListArraySuccessCallback

successCallback,



};

이 인터페이스는 task list 를 retrieve 하는 방법을 제공한다. 일단 표준이 되는

방법이 획득이 되면, 그 안의 정보들을 추가(add), 제거(remove) 및

업데이트(update)하는 것이 가능하다.

상수

short SIM_TASK_LIST

SIM Task List 를 식별하는 데 사용되는 상수.

short DEVICE_TASK_LIST

Device Task Lists 를 식별하는 데 사용되는 상수.

short HIGH_PRIORITY

높은 레벨의 priority.

short MEDIUM_PRIORITY

중간 레벨의 priority.

short LOW_PRIORITY

낮은 레벨의 priority.

short STATUS_COMPLETED

task 가 완료됨.

short STATUS_NEEDS_ACTION


274 TTAK.OT-10.0323

task 가 아직 시작되지 않음.

short STATUS_IN_PROCESS

task 가 시작되었으나 아직 완료가 되지 않은 상태.

short STATUS_CANCELLED

task 가 취소됨.

Methods

getTaskLists

디바이스에서 가용한 task list 들을 획득한다.

서명





DeviceAPIError 가 동기적으로 발생이 되도록 하여야 한다.

만약 successCallback 이 어떤 함수도 포함하고 있지 않다면(즉 null(0)값을

포함하고 있다면) 반드시 DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는

errorCallback 이 트리거되도록 하여야 한다.





조작이 성공적으로 완료가 되면 successCallback 은 획득 가능하거나 존재하고

있는 모든 task list 들과 함께 반드시 invoke 되어야 한다.

만약 존재하는 task list 가 없다면 successCallback 은 빈 어레이(empty array)

상태로 invoke 되어야 한다.

만일 task list 들을 획득하는 과정에서 에러가 발생하는 경우, invocation 에

유효하게 pass 되었던 errorCallback 함수를 반드시 호출하고, 아울러


275 TTAK.OT-10.0323

UNKNOWN_ERR 코드를 갖는 DeviceAPIError 를 errorCallback 으로

유효하게 pass 시켜야 한다.




요구하지 않는 것과 같으므로 에러에 대한 내용이 개발자에게 통지되지 않게

된다.

파라미터

• successCallback

o Optional: No.

o Type: TaskListArraySuccessCallback.

o 설명: invocation 이 성공적으로 종료될 때 호출되는 함수.

• errorCallback

o Optional: Yes.


o 설명: 에러가 발생할 때 호출되는 함수

반환값


.

예외

• DeviceAPIError:



.


276 TTAK.OT-10.0323

코드 예제

var list;


function errorCallback(response) { alert( "The following error occurred: " + response.code);

}

// Define the success callback for retrieveing the whole task list

function taskListCB(taskLists) {

if(taskLists.length > 0) {

list = taskLists[0];

alert("The task list type is " + list.type + " and name " + list.name); var task = list.createTask({priority:0,

summary:'Meeting with Peter',

설명: 'Discuss details of new website. ', status:0});

list.addTask(taskAddedCB, errorCallback, task);

} }

function taskAddedCB(task) { // The task has been successfully added

// Let's try to check if we can retrieve the added task from the task list

// If the task lits was empty only the item added through addTask should // be returned

list.findTasks(taskFoundCB, errorCallback, {summary:'%Peter%'});

}

function taskFoundCB(tasks) {

// The task has been successfully found // Let's try to change the summary

tasks[0].summary = "Meeting with John";

list.updateTask(taskUpdatedCB, errorCallback, tasks[0]); }

function taskUpdatedCB() { // The task has been successfully updated

alert('Task Successfully updated');

}


function errorCallback(response) { alert( "The following error occurred: " + response.code);

}

// Get a list of available task lists.

deviceapis.pim.task.getTaskLists(taskListCB, errorCallback);


277 TTAK.OT-10.0323

다. TaskList

개략적인 task 들의 list 를 제공하며, 다음에 포함된 task 들을 제어한다.

[NoInterfaceObject] interface TaskList {



Task createTask(in optional TaskProperties taskProperties)


PendingOperation addTask(in AddTaskSuccessCallback successCallback,


in Task task)


PendingOperation updateTask(in SuccessCallback successCallback,


in Task task)


PendingOperation deleteTask(in SuccessCallback successCallback,


in DOMString id)


PendingOperation findTasks(in TaskArraySuccessCallback successCallback,


in optional TaskFilter filter)


};

TaskList 는 Task 객체들을 포함하며 다음과 같은 메소드들을 제공한다:

• createTask() 메소드로써 새로운 task 객체들을 생성한다.

• findTask() 메소드를 갖는 filter 를 사용하여 TaskList 에 있는 task 객체들을

find 한다.

• addTask() 메소드를 사용하여 task 객체를 TaskList 에 add 한다.

• updateTask() 메소드를 사용하여 TaskList 에 있는 기존의 task 객체를 업데이트

한다.

• deleteTask() 메소드를 사용하여 TaskList 에 있는 특정한 task 객체를

delete 한다.


278 TTAK.OT-10.0323

속성

readonly short type

Task List 의 한 Type 임.

이 type 은 반드시 아래에 보이는 상수들 중 하나의 형태를 가져야 한다.

• SIM_TASK_LIST = 0 • DEVICE_TASK_LIST = 1


코드 예제


Task List 에서 사람이 읽을 수 있는 name.


코드 예제

// Define the success callback. function taskListSuccessCallback(tasklists) {

if(taskLists.length > 0)

alert("The task list type is " + tasklists[0].type); }

// Define the error callback. function errorCallback(response) {


}

// Get a list of available task lists

deviceapis.pim.task.getTaskLists(taskListSuccessCallback, errorCallback);

// Define the success callback. function taskListSuccessCallback(tasklists) {


alert("The task list name is " + taskLists[0].name); }

// Define the error callback. function errorCallback(response) {


}

// Get a list of available task lists



279 TTAK.OT-10.0323

Methods

createTask

optional 한 여러 TaskProperties 또는 디폴트 값들을 기초로 하여 하나의 task

객체로서 인스턴스를 생성한다.

서명

Task createTask(in optional TaskProperties taskProperties);





갖는 DeviceAPIError 가 반드시 발생이 되어야 한다.

만일 pass 가 이미 이루어진 task 의 TaskProperties 속성들 중에서 하나 이상의

속성에 유효하지 않은 값이 포함되어 있다면, INVALID_VALUES_ERR 코드를 갖는

DeviceAPIError 가 반드시 발생이 되도록 하여야 한다.

만일 taskProperties 속성이 omitted 된 경우라면, 디폴트 값이 모든 task

속성들에 할당 되면서 task 인터페이스에 대한 인스턴스생성을 시도하도록

implementation 이 구성되어야 한다.

그러나 입력 파라미터로 유효하게 pass 된 taskProperties 속성이 (유효한 값으로)

동 taskProperties 속성의 subset 속성만을 포함하고 있는 경우라면, 상기 이외의

다른 속성에 디폴트 값을 할당 하면서 task 인터페이스의 인스턴스 생성을

시도하도록 implementation 이 구성되어야 한다. 만일 입력 파라미터로

pass 되었던 task 가 모든 taskProperties 속성에 대해 유효한 값들을 포함하고

있는 경우에는 implementation 이 task 인터페이스의 인스턴스를 생성하도록

시도하여야 한다.

task 의 인스턴스가 성공적으로 생성이 된 경우,새로 생성이 된 task 는 이 방법에

의해 반드시 반환이 되어야 한다. 그러나 생성 과정에서 상기 이외의 다른

에러가 발생한 경우에는 메소드 상 UNKNOWN_ERR 코드를 갖는

DeviceAPIError 를 반드시 발생시켜야 한다.

이 operation 은 생성된 task 를 task list 에 add 하는 것이 아니며 또한 동

task 에 identifier(id 속성)를 할당 하는 것이 아니다. 그러나 개발자가 이를 원할

경우에는,addTask 가 invoke 되도록 메소드를 구성하여야 한다.


280 TTAK.OT-10.0323

파라미터

• taskProperties

o Optional: Yes.

o Type: TaskProperties.

o 설명: Task 정보.

반환값

생성된 task 객체.

예외

• DeviceAPIError:



만일 taskProperties 의 입력 파라미터가 유효하지 않은 값들을 포함하고 있을

경우 INVALID_VALUES_ERR 코드와 함께 이 에러가 발생

만일 feature 가 지원되지 않을 경우, NOT_SUPPORTED_ERR 코드와 함께 이

에러가 발생

task 인스턴스를 생성하는 과정에서 만일 에러가 발생한 경우

UNKNOWN_ERR 코드와 함께 이 에러가 발생

코드 예제

// Define the success callback.

function taskListSuccessCallback(taskLists) {

// Create a new task.


task = taskLists[0].createTask({priority:0,

summary:'Talk to Marky',

설명: 'Talk to Marky about the new song details',

status:0});

}




}




281 TTAK.OT-10.0323

addTask

task list 에 task 를 비동기적으로 add 한다.

서명

PendingOperation addTask(in AddTaskSuccessCallback successCallback, in

ErrorCallback errorCallback, in Task task);







SECURITY_ERR 코드를 갖는 DeviceAPIError 와 함께 invoke 되어야 한다. .


유효하지 않은 값이 포함되어 있거나, 또는 task 에 유효하지 않은 값이 포함된

경우나 task list 에서 어떤 task 항목을 입력하는 것이 불가능한 경우(가령 텍스트

값의 size 의 제한 등의 이유로) 반드시 request 를 reject 하면서

DeviceAPIError 와 INVALID_VALUES_ERR 코드를 갖는 errorCallback 을 invoke

시키도록 implementation 이 구성되어야 한다. 그러나 개발자가 에러들을 무시할

수 있도록 허용하려면 errorCallback 은 null 값을 유효한 값으로 인식하도록 해야

한다.

task 가 task list 에 성공적으로 추가(add)가 이루어진 경우 successCallback 이

반드시 invoke 되어야 한다. 이 successCallback 에는 추가된 task 를 설명하는

task element 와 id 속성을 포함한다.

만일 task 항목들을 add 하는 과정에서 상기와 다른 타입의 에러가 발생하는


UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 포함하도록 한다.




요구하지 않는 것과 같이므로 에러내용이 개발자에게 통지되지 않게 된다.


282 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: No.

o Type: AddTaskSuccessCallback.


• errorCallback

o Optional: No.


o 설명: 에러가 발생할 때 호출되는 함수.

• task

o Optional: No.

o Type: Task.

o 설명: 저장터미널에 add 되는 task 객체

반환값


예외

• DeviceAPIError:




283 TTAK.OT-10.0323

코드 예제

updateTask

task list 에 있는 기존의 task 를 비동기적으로 업데이트한다.

서명

PendingOperation updateTask(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in Task task);

// Define the task lists success callback.



{

// Create a new task.

var task = taskLists[0].createTask({priority:0,

summary:'Dont forget the milk',

설명: 'Milk, Butter, Chips',

status:0});

// Add new task to tasklist 0.

tasklists[0].addTask(taskAddSuccessCallback, errorCallback, task);

}

}

// Define the task success callback.

function taskAddSuccessCallback(response) {

alert("Task added successfully with id " + response.id);

}




}


deviceapis.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);


284 TTAK.OT-10.0323




만일 task 를 업데이트하는 이 feature(특징)가 지원되는 않는다면,

NOT_SUPPORTED_ERR 코드를 갖는 DeviceAPIError 가 errorCallback 으로

반드시 반환되도록 하여야 한다.




유효하지 않은 값이 포함되어 있거나, 또는 task 에 유효하지 않은 값이 포함된

경우, 혹은 task 항목을 업데이트하는 것이 실패하는 경우(가령 텍스트 값의

size 의 제한 등의 이유로) 반드시 request 를 reject 하면서 DeviceAPIError 와




한다

만일 task 가 유효한 값들을 갖고는 있지만, 그 id 속성이 task list 에 있는

task 들 중 그 어느 id 속성과도 대응(correspond)하는 것을 찾지 못하는

경우라면, NOT_FOUND_ERR 코드를 갖는 DeviceAPIError 가 반드시 반환되도록

하여야 한다.

만약 그렇지 않을 경우, 그 identifier 에 대해 새로운 값으로 다시 대응이

가능하도록 task 를 업데이트하는 시도를 하게끔 implementation 을 구성하여야

한다. .

task 가 성공적으로 업데이트 되었으면 SuccessCallback 이 반드시 invoke 되어야

한다.

만일 task 항목을 업데이트 하는 과정에서 상기와 다른 타입의 에러가 발생하는


UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 포함하도록 하여야 한다.


만일 개발자가 유효한 값을 갖는 errorCallback 를 pass 하지 않도록


요구하지 않는 것과 같으므로 에러내용이 개발자에게 통지되지 않게 된다.


285 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: No.



• errorCallback

o Optional: No.



• task

o Optional: No.

o Type: Task.

o 설명: 업데이트될 task 객체

반환값


예외

• DeviceAPIError:


TYPE_MISMATCH_ERR 코드와 함께 이 에러가 발생.


286 TTAK.OT-10.0323

코드 예제

var myTaskList;

// Define the task update success callback.

function taskUpdateSuccessCallback(response) {

alert("Updated");

}


function taskSearchSuccessCallback(tasks) {

tasks[0].설명 = "New 설명";

// Update the first existing task.

myTaskList.updateTask(taskUpdateSuccessCallback,

errorCallback, tasks[0]);

}




{

myTaskList = taskLists[0];

// Find all tasks in Task List 0.

myTaskList.findTasks(taskSearchSuccessCallback,


}

}




}


deviceapis.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);


287 TTAK.OT-10.0323

deleteTask

task list 로부터 task 를 비동기적으로 delete 한다.

서명

PendingOperation deleteTask(in SuccessCallback successCallback, in


만일입력 파라미터들 중에서 type 과 호환(compatible)하지 못하는 파라미터가



만일 이 feature 가 지원되는 않는다면, NOT_SUPPORTED_ERR 코드를 갖는







만일 id 파라미터가 task 리스트에 있는 그 어떤 task 의 id 속성과도

correspond 가 되는 것이 없다면(즉 해당하는 task 가 존재하지 않는다면),

NOT_FOUND_ERR 코드를 갖는 DeviceAPIError 가 반드시 반환되어야 한다.

만일 입력된 task 의 id 속성이 TaskList 상의 한 task 와 match 되는 것이

존재한다면, implementation 은 그 id 속성과 해당 되는 task 를 delete 하는

시도를 반드시 하도록 구성하여야 한다.

task 가 성공적으로 삭제(delete)되었으면, SuccessCallback 가 반드시


만일 task 를 삭제(delete)하는 과정에서 상기와 다른 타입의 에러가 발생하는


UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 반드시 포함하도록 한다.




요구하지 않는 것과 같으므로 에러내용이 개발자에게 통지되지 않게 된다.


288 TTAK.OT-10.0323

파라미터

• successCallback

o Optional: No.



• errorCallback

o Optional: No.



• id

o Optional: No.

o Nullable: No.

o Type: DOMString.

o 설명: 삭제 시킬 task 객체의 identifier(즉 id 속성)

반환값


예외

• DeviceAPIError:

만일 어떤 입력 파라미터가 자신에 대응하는 type 과 호한(compatible) 하지

못할 경우 TYPE_MISMATCH_ERR 코드와 함께 이 에러가 발생.


289 TTAK.OT-10.0323

코드 예제

var myTaskList;

// Define the task delete success callback.

function taskDeleteSuccessCallback() {

alert("Deleted");

}



// Delete the first existing task.

myTaskList.deleteTask(taskDeleteSuccessCallback,

errorCallback, tasks[0].id);

}


function taskDeleteSuccessCallback(response) {

alert("Deleted");

}




{


// Find all tasks in Task List 0.

myTaskList.findTasks(taskSearchSuccessCallback, errorCallback, null);

}

}




}




290 TTAK.OT-10.0323

findTasks

task list 로부터 task 객체들의 어레이를 획득하거나 또는 optional 하게 제공된

filter 와 match 가 되는 모든 task 객체들을 선택하여 획득한다.

서명

PendingOperation findTasks(in TaskArraySuccessCallback successCallback, in

optional ErrorCallback errorCallback, in optional TaskFilter filter);

만일입력 파라미터들 중에서 type 과 호한(compatible)하지 못하는 파라미터가



만일 이 feature 이 지원되는 않는다면, NOT_SUPPORTED_ERR 코드를 갖는







만일 filter 가 정상적으로 pass 되어 유효한 값들을 포함하고 있다면, task 리스트

중에서 TaskFilter 인터페이스에서 정의하였던 필터기준(filter criteria)에 match 가

되는 속성을 가진 task 들만이 successCallback 에 반환이 된다. 그러나 pass 가

된 filter 가 없다거나 또는 filter 에 유효하지 않은 값이 하나라도 포함이 되거나

null 또는 미 정의인 값이 존재하는 경우에는, implementation 은 task

리스트로부터 그러한 task 항목 리스트 일체를 successCallback 에 반환하도록

하여야 한다. 만일 task 리스트 에 그러한 task 가 하나도 없거나 또는 task 와

match 되는 filter criteria 에 아무런 task 도 존재하는 않는 경우,

successCallback 은 empty 어레이 상태로 invoke 시킨다.

task 항목을 retrieve 하는 과정에서 에러가 발생한 경우, invocation 에 유효하게

pass 가 되었던 errorCallback 함수를 반드시 호출하되,

이때 UNKNOWN_ERR 코드를 갖는 DeviceAPIError 객체를 포함하도록 한다.



구성하였다면(가령 null(0)값을 갖거나 미 정의된인 경우), 이는 후속적인


291 TTAK.OT-10.0323

action 을 요구하지 않는 것과 같은 것으로서, 즉 에러내용이 개발자에게

통지되지 않게 된다.

파라미터

• successCallback

o Optional: No.

o Type: TaskArraySuccessCallback.


• errorCallback

o Optional: Yes.



• filter

o Optional: Yes.

o Type: TaskFilter.

o 설명: 필터링할 때 사용되는 task 에 대한 데이터

반환값


예외

• DeviceAPIError:

만일 어떤 입력 파라미터가 자신에 대응하는 type 과 호환(compatible)

하지 못할 경우 TYPE_MISMATCH_ERR 코드와 함께 이 에러가 발생

.


292 TTAK.OT-10.0323

코드 예제

var myTaskList;



alert(tasks.length + " results found.");

}




{


// Find all tasks in Task List 0 that contains in the summary

// the string WAC.

myTaskList.findTasks(taskSearchSuccessCallback,

errorCallback,

{summary:"%WAC%");

}

}




}




293 TTAK.OT-10.0323

라. TaskProperties

task 의 특성을 나타내는 프로퍼티(property)를 포함한 인터페이스

[Callback, NoInterfaceObject] interface TaskProperties {

attribute short priority;



attribute Date dueDate;


};

이 인터페이스는 task 를 설명하는 파라미터들을 포함하며 task 가 생성이 될 때

(createTask() 메소드를 통해) 사용이 된다.

모든 속성들은 선택사항(optional)이며, 별도의 파라미터 설명으로 명시가 되지 않는

한 디폴트값에 의해 미 정의된다.

속성

short priority

task 의 priority level

이 속성은 task 의 우선순위(priority)를 규정하는 것으로서, 가령 어느 정해진

시간 동안 복수의 task 들에 대해 그 priority(우선순위)를 상대적으로 결정할 때

사용이 가능하다.(RFC 5545 - Section 3.8.1.9 참조 요망).

이 속성의 경우 아래의 값들이 유일하게 유효한 값들이 된다.

• HIGH_PRIORITY

• MEDIUM_PRIORITY

• LOW_PRIORITY

이 속성에서의 디폴트값은 LOW_PRIORITY 이다.


294 TTAK.OT-10.0323

만약 native 환경에서 task 에 대한 DB 가 상기와는 다른 방식으로 priority 를

정하는 scheme 을 갖는 경우(가령 1~9 까지의 범위로써), 이러한 값들을 반드시

상기에서 설명한 값 체계로 변환하는 implementation 이 수행되어야 한다. 예를

들어 RFC 5545 에서는 1~9 의 범위를 다음과 같이 매핑해 보도록 권장하고 있다.

• 1-4 는 HIGH_PRIORITY 에 해당,

• 5 는 MEDIUM_PRIORITY 에 해당,

• 6-9 는 LOW_PRIORITY 에 해당.

코드 예제


Task 에 대한 설명

이 속성은 task 를 설명적인 문(text)의 형식으로 제공할 때 사용된다. 이 속성은

summary 속성에 의해 제공되는 문보다 더 완전한 형태로 문을 제공하는 것이

일반적이다. (RFC 5545 - Section 3.8.1.5 참조 요망).

디폴트에 의해 이 속성은 empty string 으로 초기화된다.

코드 예제

DOMString summary

Task 의 summary.

task 의 주요요지(summary)를 간략한 형태로 정의한다.(RFC 5545 - Section

3.8.1.12 참조 요망).

디폴트에 의해 이 속성은 empty string 으로 초기화된다.

var task = taskList.createTask();

task.priority = deviceapis.pim.task.HIGH_PRIORITY;


task.설명 = "WAC note";


295 TTAK.OT-10.0323

코드 예제

Date dueDate

task 에 대해 지정이 된 일자와 시간.

이 속성은 task 가 완료가 되기 전에 그 완료 예상일자와 시간을 정의한다. (RFC

5545 - Section 3.8.2.3 참조 요망).

여기서의 디폴트값은 미 정의된다. 아무런 값도 주어지지 않을 경우, 동 task 는

빈 데이터를 갖는다.

코드 예제

short status

task 의 상태(status).

하나의 task 에 발생 가능한 상태(status)를 지칭한다. 이 속성에 있어 유효한

값이 되는 예시들로는 다음과 같다.

• STATUS_NEEDS_ACTION: task 에 대해 어떤 action 이 필요하다.

• STATUS_IN_PROCESS: task 가 진행 중 또는 작업 중이다.

• STATUS_COMPLETED: task 가 완료되었다.

• STATUS_CANCELLED: task 가 취소되었다.

이 속성에 대한 좀 더 자세한 정보는 RFC 5545 - Section 3.8.1.11 을 참조한다.

이 속성에서의 디폴트값은 STATUS_NEEDS_ACTION 이다.

코드 예제


task.summary = "WAC Codefest summary";


task.dueDate = new Date(2011, 2, 11);


task.status = deviceapis.pim.task.STATUS_NEEDS_ACTION;


296 TTAK.OT-10.0323

마. Task

하나의 task 를 TaskProperties 객체와 그 자신에 유일하게 부여된 task id 로

추상화한 것.

[NoInterfaceObject] interface Task : TaskProperties {


};

속성


implementation 에서 task 를 지속적이고(persistent) 고유한 값으로(unique)


이 값은 task list 에 task 항목이 add 될 때 플랫폼에서 부여되는 값으로서,

단말기의 사용국가(locally)에서 unique 하고 persistent 한 값이 되므로 개발자가

임의로 바꿀 수 없다.

이와 같은 고유값 부여를 보증하는 파라미터와 알고리즘에 대한 좀 더 자세한

정보를 얻고자 할 경우 RFC 5545 (section 3.8.4.7)를 참조하기 바란다. 이 값은

addTask 가 성공적으로 invoke 될 때 플랫폼에 의해 부여가 된다.


바. TaskFilter

findTasks 메소드에 의해 반환되는 항목을 필터링 하기 위한 인터페이스.

[Callback, NoInterfaceObject] interface TaskFilter { attribute DOMString id; attribute DOMString summary; attribute DOMString 설명; attribute UnsignedShortArray status; attribute UnsignedShortArray priority; attribute Date initialDueDate; attribute Date endDueDate; };


297 TTAK.OT-10.0323

이 인터페이스가 사용하여 findTasks 를 조작(operation)할 때 filter 가 supply 되며,

이 방법에 의한 result-set 은 TaskList 중에서 filter value 들과 match 가 되는 task

entry 들만을 반드시 포함하고 있어야 한다.

task 의 속성이 filter 의 모든 속성들과 match 가 된다면 이 task 는 filter 와

비로소 match 가 된 것으로 간주한다. 만일 filter 가 null 값이나 미 정의된 값을

포함하고 있는 경우, 이 값들은 무시되어야 하는 바, 즉 SQL 의 "AND"

operation 에서와 같은 방식으로 serch 가 실행되어야 한다.

task 의 한 속성은 다음에 설명하는 rule 을 통해 filter value 와 match 가

이루어진다:

• DOMString type 의 filter 속성에 있어, 자신과 대응하는 속성이 이 filter 속성과


그러나 U+0025 'PERCENT SIGN' 와일드카드 문자가 사용이 되는 경우에는 그

filter 거동이 SQL 에서의 LIKE 조건과 유사하다.('%' 와일드카드문자는 길이가

0 인 값을 포함하여 모든 길이의 값과 match 가 가능하다) 개발자가 와일드카드

형식으로 interpret 하지 않고 'PERCENT SIGN' 문자를 literally 하게 규정을

하고자 할 경우, 와일드카드 대신에 backslash 문자(\)의 사용을 고려해 볼 수

있다. Matching 은 sensitive 한 것이 아니기 때문에 가령 "FOO"는"foo"나 "f%"

filter 로도 match 가 가능하다.

• filter 속성이 웹 IDL 의 숫자(numeric)형식인 경우, task 는 대응하는 task 속성의

값이 정확히 자신의 속성값과 같을 때에 한해 filter 속성과 match 가 된다. 만약

filter 속성이 numeric type 으로서 WebIDL 어레이(array)인 경우라면, TaskLIst 에

대한 entry 는 대응하는 task 속성이 filter 속성의 어레이중의 하나와 꼭 일치하는

값이 존재할 때에 match 가 가능하다.

• date type 인 task 속성(즉 dueDate)인 경우, 최초(initial)와 최종(end)의

dueDate 의 속성들을 포함시키도록 하는데, 이는 제공된 두 date 들 사이에

존재하는 task 들을 search 하기 위함이다. 이 속성들 중 하나나 혹은 둘 다

규정되어 졌다면 다음 규칙을 적용한다. A) initialDueDate 와 endDueDate 속성

둘 다 규정 된 경우(즉. null(0)이 아닌 다른 값이 지정된 경우) 대응하는 속성의

값이 initial 이든 end 이든, 또는 두 일자 사이이든 상관없이 일치하는 값이

존재할 경우 task 는 filter 와 match 가 된다. B) initialDueDate 속성 하나만이

유효한 값을 갖는 경우(즉. null(0)이 아닌 다른 값이 지정된 경우)에는 대응하는

dueDate 속성이 initial date 와 일치하거나 그 이후일 때만 task 는 filter 와

match 가 된다. C) endDueDate 속성 하나만이 유효한 값을 갖는 경우(즉.

null(0)이 아닌 다른 값이 지정된 경우)에는 대응하는 dueDate 속성이 end

date 와 일치하거나 그 이전일 때에만 task 는 filter 와 match 가 된다.


298 TTAK.OT-10.0323

속성

DOMString id

Task id 속성을 필터링 할 때 사용됨.

이 supply 된 filter 속성과 match 가 되는(서로 정확히 일치하여 match 될 수도

있고 또는 특정한 와일드카드를 포함하여 match 가 될 수도 있다) id 속성을

가진 task 들이 filtering criteria 에 match 된다.

DOMString summary

Task summary 속성을 필터링할 때 사용됨


있고 또는 특정한 와일드카드를 포함하여 match 가 될 수도 있다) summary

속성을 가진 task 들이 filtering criteria 에 match 된다.


Task description 속성을 필터링할 때 사용됨


있고 또는 특정한 와일드카드를 포함하여 match 가 될 수도 있다) description

속성을 가진 task 들이 filtering criteria 에 match 된다.

UnsignedShortArray status

Task status 속성을 필터링할 때 사용됨.

이 어레이에 있는 값들 중의 한 값과 일치하는 status 속성을 가진

task 들이 filtering criteria 에 match 된다.

UnsignedShortArray priority

Task priority 속성을 필터링할 때 사용됨.

이 어레이에 있는 값들 중의 한 값과 일치하는 priority 속성을 가진



299 TTAK.OT-10.0323

Date initialDueDate

Task dueDate 속성을 필터링할 때의 initial date.

이 filter 속성과 시간적으로 일치하거나 또는 그 이후인 dueDate 속성을 가진


Date endDueDate

Task dueDate 속성을 필터링할 때의 end date.

이 filter 속성과 시간적으로 일치하거나 또는 그 이전인 dueDate 속성을 가진


사. TaskArraySuccessCallback

하나의 task list 안에 존재하는 task 들을 retrieve 하기 위한 success callback

[Callback=FunctionOnly, NoInterfaceObject] interface TaskArraySuccessCallback

{

void onsuccess(in TaskArray tasks);

};

비동기적 방법으로 task 들의 list 를 획득하고자 할 때 success callback 이

사용된다.

Methods

onsuccess

하나의 task list 안에서 task 들의 리스트가 성공적으로 retrieve 되면 메소드가

invoke 된다.

서명


파라미터

• tasks

o Optional: No.

o Type: Task 어레이.

o 설명: 하나의 task list 안에 존재하는 task 들


300 TTAK.OT-10.0323

아. AddTaskSuccessCallback

하나의 task 를 Task list 로 add 하기 위한 success callback

[Callback=FunctionOnly, NoInterfaceObject] interface AddTaskSuccessCallback {

void onsuccess(in Task task);

};

하나의 task 가 task list 에 add 가 되면 메소드가 invoke 된다.

Methods

onsuccess

하나의 task 가 task list 에 성공적으로 add 될 때 메소드가 invoke 된다.

서명


파라미터

• task

o Optional: No.

o Type: Task.

o 설명: task list 에 add 된 task 항목.

자. TaskListArraySuccessCallback

모든 Task List 들을 retrieve 하기 위한 success callback.


TaskListArraySuccessCallback {

void onsuccess(in TaskListArray taskLists);

};

TaskList 들이 성공적으로 retrieve 되면 메소드가 invoke 된다.


301 TTAK.OT-10.0323

Methods

onsuccess

task list 들이 성공적으로 retrieve 되면 메소드가 invoke 된다.

서명


파라미터

• taskLists

o Optional: No.

o Type: TaskListArray.

o 설명: Task lists.

4.11.5. Type에 대한 정의

가. TaskListArray

Task List 들로 된 어레이.

typedef sequence<TaskList> TaskListArray;

나. TaskArray

Task 들로 된 어레이.

typedef sequence<Task> TaskArray;

4.11.6. Features


• http://wacapps.net/api/pim.task


TaskManager 인터페이스가 예시되며, 여기서 보이는 객체는 국제(전역)

namespace 로서 pim.task 를 갖는다.


302 TTAK.OT-10.0323


사용이 되는 URL 리스트이다. 각 URL 에 대해 포함된 함수들의 list 가 아래

사이트들에 제공이 되어 있다.

http://wacapps.net/api/pim.task.read

addTask(), deleteTask(), updateTask()을 제외한 전체 모듈에 접근이 가능

http://wacapps.net/api/pim.task.write

findTasks()을 제외한 전체 모듈에 접근이 가능.

http://wacapps.net/api/pim.task

본 모듈에서의 모든 feature 들에 대한 접근이 가능.

4.11.7. Full WebIDL

module task {





};













successCallback,


303 TTAK.OT-10.0323



};








in Task task)




in Task task)




in DOMString id)






};



attribute DOMString 설명;




};


304 TTAK.OT-10.0323



};

[Callback, NoInterfaceObject] interface TaskFilter {



attribute DOMString 설명;


attribute UnsignedShortArray priority;

attribute Date initialDueDate;

attribute Date endDueDate;

};


TaskArraySuccessCallback {


};

[Callback=FunctionOnly, NoInterfaceObject] interface AddTaskSuccessCallback

{


};




};

};


305 TTAK.OT-10.0323

4.12. 장치상호작용(deviceinteraction) 모듈

4.12.1. 요약

API 는 소비자와의 직접적인 interaction 을 위한 수단으로서 widget 기능들을

허용하고 있다.



DeviceapisDeviceInteractionManager

DeviceInteractionManager PendingOperation startNotify(SuccessCallback

successCallback, ErrorCallback errorCallback, long

duration)

void stopNotify()

PendingOperation startVibrate(SuccessCallback


long? duration, DOMString? pattern)

void stopVibrate()

PendingOperation lightOn(SuccessCallback

successCallback, ErrorCallback errorCallback, long

duration)

void lightOff()

PendingOperation setWallpaper(SuccessCallback


DOMString fileName)

4.12.3. 개요

본 모듈은 다음과 같은 feature 들을 통해 최종소비자들과의 인터렉션을 위한

메커니즘을 제공한다.

• device vibrator,

• device notifier,

• screen backlight,

• device Wallpaper.


306 TTAK.OT-10.0323

상기와 같은 본 모듈에서의 모든 기능들은 DeviceInteractionManager 인터페이스의

인스턴스인 deviceapis.deviceinteraction 객체를 통해 제공된다. 여기서 만약 어떤

기능이 제공되지 않는 것이 있을 경우에는 DeviceInteractionManager 인터페이스와

관련된 메소드가 invoke 될 때 NOT_SUPPORTED_ERR 코드를 갖는

DeviceAPIError 가 발생하도록 되어 있다.

4.12.4. 인터페이스

가. DeviceapisDeviceInteractionManager

deviceapis 객체에 무엇을 예시할 것인가를 정의한다. .

interface DeviceapisDeviceInteractionManager {

readonly attribute DeviceInteractionManager deviceinteraction;

};

Deviceapis implements DeviceapisDeviceInteractionManager;

deviceinteraction 모듈에서 제공하는 기능들에 접근을 허용하는 객체로서

deviceapis.deviceinteraction 가 있다. .

나. DeviceInteractionManager

DeviceInteractionManager 인터페이스.

interface DeviceInteractionManager {

PendingOperation startNotify(in SuccessCallback successCallback,in

ErrorCallback

errorCallback,in long duration)


void stopNotify();

PendingOperation startVibrate(in SuccessCallback successCallback,


in long? duration,

[TreatUndefinedAs=Null]in optional DOMString? pattern)


void stopVibrate();


307 TTAK.OT-10.0323

PendingOperation lightOn(in SuccessCallback successCallback, in ErrorCallback

errorCallback,in long duration)


void lightOff();

PendingOperation setWallpaper(in SuccessCallback successCallback,


in DOMString fileName)


};

이것은 본 모듈의 제 기능들에 접근하도록 API 가 제공하는 deviceinteraction 에서

top-level 에 해당하는 인터페이스이다.

코드 예제

function alertUser()

{

// switches the light on for 10 secs

deviceapis.deviceinteraction.lightOn( function() { return; },

function(e) { window.console.error(e.code); }, 10000);

// makes the device beep/vibrate/backlight-on for 10 secs

deviceapis.deviceinteraction.startNotify( function() { return; },

function(e) { window.console.error(e.code); },10000);

// makes the device vibrate for 10 secs

deviceapis.deviceinteraction.startVibrate( function() { return; },

function(e) { window.console.error(e.code); },10000);

}

function stopAlertingButtonPressed()

{

deviceapis.deviceinteraction.lightOff();

deviceapis.deviceinteraction.stopNotify();

deviceapis.deviceinteraction.stopVibrate();

}


308 TTAK.OT-10.0323

Methods

startNotify

지정한 시간 동안 단말에 beep/vibrate/backlight-on 기능들을 제공한다.

서명

PendingOperation startNotify(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in long duration);

이 메소드가 invoke 되는 때에는 통지를 반드시 active profile 을 기초로 구성을

하여야 한다.

• 만일 디바이스의 volume 값이 0 을 초과하는 값으로 설정된다면

디바이스의 beeper 는 반드시 기간(duration)에 대한 입력 파라미터에서

규정하는 시간 동안 activate 가 유지되도록 구성되어야 한다.

• 만일 디바이스가 vibrate mode 인 경우(즉 sound volume 이 ‘0’에

설정되어 있고 vibrator alert 가 active 상태인 모드) 디바이스는 반드시

지정한 시간 동안 vibrate 이 되어야 한다.

• 만일 디바이스가 silent mode 인 경우(즉. sound volume 이 ‘0’에 설정되어

있고 vibrator alert 가 active 상태가 아닌(꺼진) 경우) 디바이스의 주

스크린의 backlight 는 duration 에 대한 입력파라미터에서 지정해 준 시간

동안 반드시 켜져 있는 상태가 지속되어야 한다.

통지가 사전에 지정된 시간이 다 지나기도 전에 중지되는 것을 막기 위해

implementation 에서 개발자가 어떤 제한을 가하는 것은 물론 가능하다. 특히

기간(duration)에 대한 입력 인수가 ‘0’으로 설정되어 있다면, 최소제한시간에

도달할 때까지 또는 stopNotify 메소드가 invoke 될 때까지 디바이스 모드가 계속

동작이 되도록 반드시 구성되어야 한다.

implementation 에서 통지를 구현하기로 결정을 하였다면 success callback 은

통지가 이루어진 즉시 invoke 가 되도록 하여야 한다. 여기서 그 어떤

이유로(보안상이나 또는 기타의 이유로) 통지가 구현될 수 없게 된다면 반드시

다음 예시와 같은 적절한 에러코드를 갖는 error callback 이 호출되도록 하여야

한다.

• 입력 파라미터가 유효하지 않은 값을 갖고 있다면

INVALID_VALUES_ERR 코드

• 조작이 허용되지 않는 것이라면 SECURITY_ERR 코드

• 어떤 feature 가 지원되지 않는 경우라면 NOT_SUPPORTED_ERR 코드

• 기타 다른 경우에는 UNKNOWN_ERR 코드


309 TTAK.OT-10.0323

지정해 준 통지를 위한 기간(duration)이 아직 만료가 되지 않은 상태에서

만일 stopNotify 메소드가 invoke 된다면, active 상태에 있는

통지들(가령 notification (beep/vibrate/backlight-on)은 반드시 그 기능이

종료되도록 하여야 한다.

파라미터

• successCallback

o Optional: No.


o 설명: 통지가 성공적으로 구현이 될 때 invoke 된다.

• errorCallback

o Optional: No.


o 설명: 통지가 성공적으로 구현이 될 수 없을 때 invoke 된다.

• duration

o Optional: No.

o Nullable: No.

o Type: long.

o 설명: millisecond 단위의 값임.

반환값


.

예외

• DeviceAPIError:



코드 예제

deviceapis.deviceinteraction.startNotify(function() { return; }, function(e) { window.console.log('error while notifying the user'); } ,10000); // makes the device beep/vibrate/backlight-on for 10 secs function stopNotifierButton() // To be invoked when the user stops the notification manually { deviceapis.deviceinteraction.stopNotify(); }


310 TTAK.OT-10.0323

stopNotify

현재 동작 중인(ongoing), 즉 active 상태인 통지(notification alert)를 종료시킨다.

서명

void stopNotify();

본 메소드가 invoke 되면, implementation 은 즉각 notification 을 중지하도록

request 하게끔 구성되어야 한다. 그러나 이처럼 중지 request 가 즉각

이루어지도록 implementation 이 구성되어 있다 하더라도, 동작 완료를 지체시킬

만한 어떤 제한(가령 timeouts)이 디바이스에 있을 수 있다.

notification 이 active 로 진행 중인 아닌 경우(즉 현재 디바이스가

beeping/vibrating/backlight-on 인 상태가 아닌 경우)에서 만일 이 메소드가

invoke 된다면, 이는 무시되도록 구성하여야 한다.

만일 이 기능이 지원되지 않거나 또는 request 를 실행하는 중에 어떤 다른

에러가 발생한다면 request 는 추가 action 없이 즉각적으로 반환이 되도록

구성하여야 한다.

코드 예제

// makes the device beep/vibrate for 10 secs

deviceapis.deviceinteraction.startNotify(function() { return; },

function(e) { window.console.log( 'Notif not done'); },10000);

// To be invoked when the user stops the notification manually

function stopNotifierButton()

{

deviceapis.deviceinteraction.stopNotify();

}


311 TTAK.OT-10.0323

startVibrate

switch-on 을 시키면 디바이스가 vibration 하는 것으로서, 그 진동시간과

진동패턴은 optional 하게 조정이 가능하다.

서명

PendingOperation startVibrate(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in long? duration, in optional DOMString? pattern);

이 메소드가 invoke 되면, 디바이스의 vibrator 는 지정해 준 시간 동안 반드시

activate 되도록 하여야 한다. 여기서 vibration 기간은 다음의 두 메커니즘으로

지정할 수 있다.

• 기간(duration)에 대한 입력 파라미터,

• on/off pattern.

pattern 인수는'.' 와 '_' 문자로 이루어진 DOMString 이다. 여기서 '.' 는

'vibration pulse'를 의미하고 '_'는 'no vibration pulse'를 의미한다. 이 패턴은

최대 10 개 문자까지로 제한되어 있으며 각 pulse 의 duration 은 100

millisecond 가 되도록 한다.

예를 들어 "..__." 로 패턴이 되어 있다면 이것은 단말이 200 msecs 동안

vibrate 하고 연이어 200 msecs 동안 vibrate 를 중단했다가 다시 100 msecs

동안 vibrate 한다는 것을 의미한다.

implementation 에서 vibrate 를 구현하기로 결정을 하였다면 success callback 은

vibrate 가 이루어진 즉시 invoke 가 되도록 하여야 한다. 여기서 그 어떤

이유로(보안상이나 또는 기타의 이유로) vibrate 가 구현될 수 없게 된다면 반드시

다음 예시와 같은 적절한 에러 코드가 있는 error callback 이 호출되도록 하여야

한다.




• 어떤 feature 가 지원되지 않는 경우라면 NOT_SUPPORTED_ERR 코드


vibration 인수가 2 개 존재할 때 이 두 인수들 모두 null(0)값이 아닌 어떤

유효한 값들을 갖고 있다면 진동 pattern 은 두 기간 값들이 모두 경과가 완료될

때까지 반복되도록, 즉 두 값 모두 실행이 완료되도록 구성이 되어야 한다.(즉

pattern 이 임의로 달라져서는 아니 된다.)


312 TTAK.OT-10.0323

상기에서 만일 하나의 인수만이 유효한 값을 갖고 나머지 하나는 null 값을 갖고

있다면 유효한 인수에 대한 메커니즘만 사용이 된다.

implementation 을 하면서 필요에 따라 지정된 기간(duration)값이 다 만료가

되기 이전이라도 vibration 을 stop 하도록 기간에 제한을 둘 수 있다.

지정된 vibration 기간이 아직 완료되기 이전에 만일 stopVibrate 메소드가

invoke 되도록 하였다면 어떤 vibration 이든 즉각 중지가 되도록 구성하여야 한다.

파라미터

• successCallback

o Optional: No.


o 설명: vibrate 가 성공적으로 구현이 될 때 invoke 된다.

• errorCallback

o Optional: No.


o 설명: vibrate 가 구현에 실패할 때 invoke 된다.

• duration

o Optional: No.

o Nullable: No.

o Type: long.

o 설명: millisecond 단위의 값.

• pattern

o Optional: Yes.

o Nullable: No.

o Type: DOMString.

o 설명: "." 와 "_" 문자로 구성된 vibration pattern

반환값


.

예외

• DeviceAPIError:




313 TTAK.OT-10.0323

코드 예제

stopVibrate

현재 진행 중인 디바이스의 vibration alert 를 종료시킨다.

서명

void stopVibrate();

이 메소드가 invoke 되면 디바이스 vibrator 는 반드시 중지가 되도록 하여야 한다.

그러나 이 메소드가 invoke 될 때 디바이스가 vibration 인 상태가 아니라면 이는

무시시켜야 한다.




코드 예제

// makes the device vibrate for 10 secs

deviceapis.deviceinteraction.startVibrate(function() { return; },

function(e) { window.console.error(e.code)},10000);

// device should vibrate for 200 msecs, stop vibrating for

// another 200 msecs and vibrate again for 100 msecs.

deviceapis.deviceinteraction.startVibrate(function() { return; },

function(e) { alert(e.code); },null, "..__.");

// To be invoked when the user stops the vibration manually

function stopVibrationButton()

{

deviceapis.deviceinteraction.stopVibrate();

}

// makes the device vibrate for 10 secs deviceapis.deviceinteraction.startVibrate(function() { return; }, function(e) { alert(e.code); },10000); // To be invoked when the user stops the vibration manually function stopVibrationButton() { deviceapis.deviceinteraction.stopVibrate(); }


314 TTAK.OT-10.0323

lightOn

지정된(specify) 기간(duration)값 동안 디바이스 디스플리에의

백라이트(backlight)를 switch-on 시킨다.

서명

PendingOperation lightOn(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in long duration);

이 메소드가 invoke 되면, main screen 의 백라이트(backlight)는 기간(duration)에

대한 입력 파라미터를 통해 지정해 준 시간 동안 계속 switch-on 상태가

유지되어야 한다. 만일 지정해 준 기간이 만료되기 이전에 lightoff 메소드가

invoke 되면, screen 의 백라이트(backlight)는 즉시 switch-off 가 되도록 하여야

한다

그러나 specify 해 준 기간이 만료되기 이전이라도 implementation 을 할 때

backlight 가 switch-off 되도록 기간에 제한을 가하는 것이 가능하다. 특히 기간

값에 대한 입력인수가 만약 0 인 경우에는 적어도 제한값의 시간만큼 또는

lightOff 메소드가 invoke 될 때까지 이 조작이 수행되도록 하여야 한다.

implementation 에서 light-on 을 실행하기로 결정을 하여 request 가 이루어지면

그 즉시 success callback 을 호출하도록 구성이 되어야 한다. 그러나 그 어떤

이유로 request 가 실행에 실패할 때에는 반드시 다음 예시와 같은 적절한

에러코드를 갖는 error callback 이 호출시켜야 한다.




• feature 가 지원되지 않는 경우라면 NOT_SUPPORTED_ERR 코드


파라미터

• successCallback

o Optional: No.


o 설명: request 가 실행이 되었을 때 invoke 된다.

• errorCallback

o Optional: No.


o 설명: request 가 실행에 실패할 때 invoke 된다.


315 TTAK.OT-10.0323

• duration

o Optional: No.

o Nullable: No.

o Type: long.

o 설명: millisecond 단위의 값.

반환값


.

예외

• DeviceAPIError:



코드 예제

lightOff

screen backlight 의 notification 을 종료시킨다.

서명

void lightOff();

이 메소드가 invoke 되면, implementation 은 반드시 screen backlight 를

switched off 하도록 request 를 하여야 한다. 이처럼. implementation 상

backlight 를 즉시 switch-off 하도록 request 를 요구함에도 불구하고

// switches the screen backlight on for 10 secs

deviceapis.deviceinteraction.lightOn(function() { return; },

function(e) { alert(e.code); },10000);

// To be invoked when the user requests to switch off the light manually

function noLightButton()

{


}


316 TTAK.OT-10.0323

디바이스에는 그 조작을 delay 시킬 수 있는 어떤 제한(가령 timeouts)이 이미

걸려있을 수가 있다.




코드 예제

setWallpaper

디바이스의 Wallpaper 를 지정된 이미지 파일로 설정한다.

서명

PendingOperation setWallpaper(in SuccessCallback successCallback, in

ErrorCallback errorCallback, in DOMString fileName);

이 메소드는 디바이스의 wallpaper 를 fileName 입력 파라미터를 통해 지정해 둔

이미지 파일로 설정한다 만일 wallpaper 가 성공적으로 설정되면,

successCallback 이 반드시 invoke 되도록(호출되도록) 구성하여야 한다.




만일 예를 들어 image format 이 지원되지 않는다거나 유효하지 않는 file

format 을 갖는 경우처럼 그 어떤 이유로 wallpaper 를 설정할 수 없다면,

errorCallback 이 반드시 invoke 되도록 하여야 한다. 아래에 예시한 에러코드들은

에러타입에 따라 적절히 error callback 에 반환을 시킨다.

• NOT_SUPPORTED_ERR 이 feature 가 지원되지 않을 때

// switches the light on for 10 secs

deviceapis.deviceinteraction.lightOn(function() { return; },

function(e) { alert(e.code); },10000);

// To be invoked when the user requests to switch off the light manually

function noLightButton()

{


}


317 TTAK.OT-10.0323

• SECURITY_ERR: operation 이 허용되지 않을 때

• INVALID_VALUES_ERR:입력 파라미터들 중의 어느 하나에 유효하지 않은

값이 포함되어 있을 때로서 가령 successCallback 에 null 값이 있거나

fileName 이 존재하지 않는 경우. 그러나 개발자가 에러들을 무시하는

것이 가능하도록 erroCallback 에서 null 값을 유효한 값인 것으로

인식하게끔 할 수 있다.

• UNKNOWN_ERR: 기타 다른 타입의 에러일 때.

만약 errorCallback 이 유효하지 않은 함수(가령 null 값)를 포함하거나 상기의

예시처럼 errorCallback 에 반환되어야 할 에러가 발생할 때 silent 하게

fail 하도록 implementation 을 구성하였다면 개발자에게는 그 어떤 에러정보도

통지되지 않으며 추가적인 action 도 뒤따르지 않는다는 것을 유의하여야 한다.

파라미터

• successCallback

o Optional: No.


o 설명: wallpaper 가 성공적으로설정되었을 때 invoke 된다.

• errorCallback

o Optional: No.


o 설명: wallpaper 가 성공적으로설정되지 않았을 때 invoke 된다.

• fileName

o Optional: No.

o Nullable: No.

o Type: DOMString.

o 설명: 디바이스 wallpaper 로서 설정 될 이미지파일의 가상경로.

여기서 가상경로는 WAC file system 에 정의되어 있다. fileName

인수는 Filesystem.resolve()을 호출하여 검증이 되었다면 유효한

것으로 간주된다.

반환값


.

예외

• DeviceAPIError:


318 TTAK.OT-10.0323



코드 예제

4.12.5. Features


• http://wacapps.net/api/deviceinteraction


DeviceInteractionManager 인터페이스가 예시되며, 여기서 보이는 객체는

국제적인(전역) namespace 에서 deviceapis.deviceinteraction 이름을 갖는다.

이것은 위젯(widget) config.xml 을 사용하기 위해 API 의 feature 들을 선언하고자

할 때 사용이 되는 URL 리스트이고, 각 URL 에 포함되어 있는 함수들의 list 가

아래에 제공되어 있다.

http://wacapps.net/api/deviceinteraction

위의 경우 device interaction module 에 대한 접근을 허용하고 있다.

//call async function set wallpaper

try{

// Sets the wallpaper of the device to a.jpg

deviceapis.deviceinteraction.setWallpaper(function() {

alert("wallpaper set");

},

function(e) {

alert(e.message);

},

"images/a.jpg");

}

catch(exp) {

alert("setWallpaper Exception :[" + exp.code + "] " + exp.message);

}


319 TTAK.OT-10.0323

4.12.6. Full WebIDL

module deviceinteraction {



};




ErrorCallback errorCallback,in long duration)


void stopNotify();



in long? duration,



void stopVibrate();




void lightOff();





};

};


320 TTAK.OT-10.0323

4.13. 장치 상태(Device Status) 용어총람

4.13.1. 요약

본 표준은 API 가 디바이스 상태(status)들을 정의할 때 사용되는 WAC 어휘들을

내용으로 담고 있다.

4.13.2. 개요

본 스펙을 이루는 주요 내용들은 아래와 같다.

• Components

• Aspects

• Properties

4.13.3. 소개

본 표준은 API 가 디바이스 상태(status)들을 정의할 때 사용되는 WAC 어휘들을

내용으로 담고 있다.

WAC 체계에서 사용하는 어휘들을 동원하여 트리(tree)를 구성하는 각 카테고리들을

설명하면 다음과 같다.

• "Aspects": 디바이스의 정보들 중에서 관련이 있는 정보들끼리 묶는 특징 (가령

'웹 Runtime', 'Battery', 'MemoryUnit').

• "Components": 동일한 aspect 에 대해 서로 다른 인스턴스를 가질 때 이를

표현하기 위한 값(가령 'MemoryUnit'라는 aspect 는 'physical', 'virtual',

'storage'등과 같은 서로 다른 컴포넌트들을 가질 수 있다). 여기에는 다음과

같은 2 개의 특별한 식별자(identifiers)가 있다:

o _active: aspect 에 대해 활성화된(즉, widget 에 의해 현재 사용이 되는)

인스턴스를 지칭한다. 가령 widget 이 실행되고 있는 웹 runtime,

widget 이 보여지고 있는 display 등등)

o _default: aspect 에 대해 기본이 되는 컴포넌트, 즉 디바이스의 디폴트로

사용이 되는 컴포넌트의 인스턴스를 지칭. 예를 들어 디폴트에 의해

widgets 이 실행되는 웹 runtime 또는 디바이스의 main display 등.

• "Properties": Aspects 를 구성하는 요소로서 컴포넌트의 특성에 대한 정보를

제공한다. 가령 모든 'MemoryUnit' 컴포넌트에는 'size', 'availableSize',

'removable'등과 같은 properties 들이 지원이 되는 식이다. 각 속성에는 값으로

표현되는, [웹 IDL] Type 이 specify 된다.


321 TTAK.OT-10.0323

vocabulary tree 에서 어떤 하나의 속성을 해결 하도록 시도하려면 최소한 aspect 와

속성 명(property name)이 반드시 제공되어야 한다. 만일 규정된 컴포넌트는 없지만

선택된 aspect 에 대해 _active 컴포넌트 가 존재하는 경우, 활성화된 컴포넌트를

사용하여야 한다. 선택된 aspect 에 대해 _active 컴포넌트가 존재하지 않는 경우

디폴트 컴포넌트를 사용하도록 하여야 한다.

컴포넌트

보조어 설명

_active 기준되는 aspect 에 대해 활성화된 컴포넌트를 지칭한다. Delivery Context

Ontology 도 참조할 것: dcn:activeComponent

_default 기준되는 aspect 에 대해 디폴트 컴포넌트를 지칭한다. Delivery Context Ontology 도

참조할 것: dcn:defaultComponent

Aspects

Aspect Properties 컴포넌트

보조어 설명

Battery batteryLevel,

batteryBeingCharged _default

device 에 있는 배터리. Delivery

Context Ontology 참조 요망:

hard:battery

CellularHardware status _default

디바이스 hardware 로서

모바일사업자의 telephony

network 에 억세스할 때 사용이

된다. Delivery Context Ontology

참조 요망: hard:CellularHardware

CellularNetwork

isInRoaming, mcc, mnc,

signalStrength,

operatorName

_default

Cellular Network 를 지칭..

Delivery Context Ontology 참조

요망: net:Network

Device imei, model, version, vendor _default

디바이스를 지칭.. Delivery


dcn:Device

Display

resolutionHeight,

pixelAspectRatio, dpiY,

resolutionWidth, dpiX,

colorDepth

_active,

_default

디바이스에 장착된

시각디스플레이를 지칭. Delivery


hard:Display

MemoryUnit size, removable,

availableSize _default

디바이스에서 사용되는 메모리

유닛. Delivery Context Ontology

참조 요망: hard:MemoryUnit


322 TTAK.OT-10.0323

Aspect Properties 컴포넌트

보조어 설명

OperatingSystem language, version, name,

vendor

_active,

_default

디바이스의 operating system 을

말함. Delivery Context Ontology

참조 요망: soft:OperatingSystem

웹 Runtime

wacVersion,

supportedImageFormats,

version, name, vendor

_active,

_default

widgets 을 실행하는 웹 runtime.


요망: 웹:웹 Runtime

WiFiHardware status _default

WiFi networks 에 억세스 할 때

사용되는 디바이스의 하드웨어.


요망: hard:WiFiHardware

WiFiNetwork ssid, signalStrength,

networkStatus

_active,

_default

WiFi Network 를 가리킴. Delivery


net:WiFiNetwork

Properties

Battery Being Charged

ID

batteryBeingCharged

관련 Aspect

Battery

설명

이 속성은 배터리가 현재 충전 중인지 아닌지를 가리킨다. Delivery Context Ontology

참조 요망


323 TTAK.OT-10.0323

Delivery Context Ontology 의 관련 엔티티(Entity)

hard:batteryBeingCharged

웹 IDL Type

boolean

Battery Level

ID

batteryLevel

관련 Aspect

Battery

설명

이 속성에는 배터리 여유분이 현재 몇 퍼센트가 남아 있는지를 식별하는 정수를

포함한다. Delivery Context Ontology 참조 요망.

Delivery Context Ontology 의 관련 엔티티

hard:batteryLevel

웹 IDL Type

unsigned long

Cellular Hardware Status

ID

status

관련 Aspect

CellularHardware

설명

Cellular 하드웨어의 상태(ON 또는 OFF)를 나타낸다. Delivery Context Ontology 참조

요망


324 TTAK.OT-10.0323


hard:status

웹 IDL Type

DOMString 다음에서 선택된 값을 갖는다.

Value 설명

ON ON

OFF OFF

Is In Roaming

ID

isInRoaming

관련 Aspect

CellularNetwork

설명

단말의 연결상태가 로밍인지의 여부를 가리킨다. true 값은 현재 로밍 상태인 것을

나타내고 false 값은 현재 로밍 상태가 아닌 것을 나타낸다.

웹 IDL Type

boolean

Mobile Country Code

ID

mcc

관련 Aspect

CellularNetwork

설명

이 속성은 현재 단말이 속해 있는 네트워크의 국가명을 식별한다. Delivery Context

Ontology 도 참조 요망


325 TTAK.OT-10.0323


net:mcc

웹 IDL Type

DOMString

Mobile Network Code

ID

mnc

관련 Aspect

CellularNetwork

설명

Mobile Network Code (MNC)는 Mobile Country Code (MCC)("MCC / MNC tuple"로도

알려져 있음)와 함께 사용되는 것으로서, 단말에 대한 이동전화사업자의 네트워크(가령

GSM, CDMA, iDEN, TETRA, UMTS public land mobile networks 및 위성 mobile

networks)를 지칭. Delivery Context Ontology 도 참조 요망


net:mnc

웹 IDL Type

DOMString

Cellular Signal Strength

ID

signalStrength

관련 Aspect

CellularNetwork

설명

이 속성은 단말이 속한 네트워크가 제공하는 상대적인 신호강도(0~100)를 의미.

Delivery Context Ontology 도 참조 요망


326 TTAK.OT-10.0323


net:signalStrength

웹 IDL Type

unsigned long

Operator Name

ID

operatorName

관련 Aspect

CellularNetwork

설명

이 속성은 셀룰러 네트워크 사업자의 사업자명을 포함한다.

웹 IDL Type

DOMString

IMEI

ID

imei

관련 Aspect

Device

설명

IMEI - International Mobile Equipment Identity(IMEI)의 약자로서 GSM 및 UMTS

이동전화기마다 고유하게 부여되는 번호를 말한다. Delivery Context Ontology 참조 요망


327 TTAK.OT-10.0323


hard:imei

웹 IDL Type

DOMString

Device Model

ID

model

관련 Aspect

Device

설명

vendor 가 부여하는 디바이스의 모델을 의미. Delivery Context Ontology 참조 요망


common:model

웹 IDL Type

DOMString

Device Version

ID

version

관련 Aspect

Device

설명

벤더가 임의로 부여하는 디바이스의 버전을 의미. Delivery Context Ontology 참조 요망


328 TTAK.OT-10.0323


common:version

웹 IDL Type

DOMString

Device Vendor

ID

vendor

관련 Aspect

Device

설명

디바이스 vendor. Delivery Context Ontology 참조 요망


common:vendor

웹 IDL Type

DOMString

Resolution Height

ID

resolutionHeight

관련 Aspect

Display

설명

네모 형태의 요소(가령 카메라, 디스플레이, 이미지, 비디오 등)을 디폴트 orientation

방향으로 쥔다고 할 때 수직 방향의 총 픽셀 수. Delivery Context Ontology 참조 요망


329 TTAK.OT-10.0323


common:resolutionHeight

웹 IDL Type

unsigned long

Pixel Aspect Ratio

ID

pixelAspectRatio

관련 Aspect

Display

설명

픽셀 종횡비(pixel aspect ratio)는 십진수로 표현하는데, 가령 4:3 aspect 의 경우 1.33

하는 식이다. 그 정의는 폭에 대한 해상도(픽셀 단위) 대 높이에 대한

해상도(픽셀단위)의 비이다. Delivery Context Ontology 참조 요망


common:pixelAspectRatio

웹 IDL Type

float

Dpi Y

ID

dpiY

관련 Aspect

Display

설명

y 축 기준으로 인치당 도트(dot)수.


330 TTAK.OT-10.0323

웹 IDL Type

unsigned long

Resolution Width

ID

resolutionWidth

관련 Aspect

Display

설명

네모형태의 요소(가령 카메라, 디스플레이, 이미지, 비디오 등)을 디폴트 orientation

방향으로 쥔다고 할 때 수평 방향의 총 픽셀 수. 이 속성은 물체가 네모형태가 아닌

경우에는 적용되지 아니 한다. Delivery Context Ontology 참조 요망


common:resolutionWidth

웹 IDL Type

unsigned long

Dpi X

ID

dpiX

관련 Aspect

Display

설명

Dots per inch in the X axis.


331 TTAK.OT-10.0323

웹 IDL Type

unsigned long

Color Depth

ID

colorDepth

관련 Aspect

Display

설명

컬러 해상도를 나타낼 때 사용되는 비트 수를 포함한다. Delivery Context Ontology 참조

요망


hard:colorDepth

웹 IDL Type

unsigned long

Size

ID

size

관련 Aspect

MemoryUnit

설명

memory 컴포넌트의 총 size 로 단위는 바이트다. Delivery Context Ontology 참조 요망


332 TTAK.OT-10.0323


hard:size

웹 IDL Type

unsigned long

Removable

ID

removable

관련 Aspect

MemoryUnit

설명

memory 컴포넌트를 디바이스로부터 떼어낼 수 있는가 아닌가를 가리킨다. True 는

떼어내는 것을, false 는 떼어낼 수 없는 것을 의미한다.

웹 IDL Type

boolean

Available Size

ID

availableSize

관련 Aspect

MemoryUnit

설명

memory 컴포넌트의 획득 가능한 siz 로서, 바이트 단위이다. Delivery Context Ontology

참조 요망


333 TTAK.OT-10.0323


hard:availableSize

웹 IDL Type

unsigned long

Language

ID

language

관련 Aspect

OperatingSystem

설명

언어 tag 는 RFC 4646 의 규정을 따른다. Delivery Context Ontology 참조 요망


common:languageCode

웹 IDL Type

DOMString

Version

ID

version

관련 Aspect

OperatingSystem

설명

벤더가 임의로 부여하는 운영시스템(operating system)의 버전. Delivery Context

Ontology 참조 요망


334 TTAK.OT-10.0323


common:version

웹 IDL Type

DOMString

Operating System Name

ID

name

관련 Aspect

OperatingSystem

설명

벤더가 임의로 부여하는 운영 시스템(operating system) 명. Delivery Context Ontology

참조 요망


common:name

웹 IDL Type

DOMString

Operating System Vendor

ID

vendor

관련 Aspect

OperatingSystem

설명

벤더가 임의로 부여하는 운영 시스템(operating system) 명. Delivery Context Ontology

참조 요망


335 TTAK.OT-10.0323


common:vendor

웹 IDL Type

DOMString

WAC Version

ID

wacVersion

관련 Aspect

웹 Runtime

설명

웹 런타임(WRT)에 의해 지원되는 WAC 버전.

웹 IDL Type

DOMString

이 버전의 포맷은 [Widget Packaging]에서 설명된 바와 같이 rec-version-tag

grammar 이다.

rec-version-tag = 1*DIGIT "." 1*DIGIT [ "." 1*DIGIT]*[ 1*ALPHA / SP / 1*DIGIT ]

rec-version-tag 의 예시:

• 2.0

• 1.10.1 beta1

• 1.02.12 RC1

Supported Image Formats

ID

SupportedImageFormats

관련 Aspect

웹 Runtime

설명

WRT 에서 지원하는 image 포맷을 나타낸다. Delivery Context Ontology 참조 요망


336 TTAK.OT-10.0323


soft:supportedFormats

웹 IDL Type

DOMString (sequence)에 대한 웹 IDL sequence 의 값은 다음과 같다.(또는

implementation 단계에서 다른 값을 정의할 수도 있다):

Value 설명

gif87 gif87

gif89a gif89a

Jpeg jpeg

Png png

웹 Runtime Version

ID

version

관련 Aspect

웹 Runtime

설명

벤더가 부여하는 웹 런타임 버전. Delivery Context Ontology 참조 요망


common:version

웹 IDL Type

DOMString

Web Runtime Name

ID

name

관련 Aspect

웹 Runtime

설명

벤더가 부여하는 웹 런타임 명. Delivery Context Ontology 참조 요망


337 TTAK.OT-10.0323


common:name

웹 IDL Type

DOMString

Web Runtime Vendor

ID

vendor

관련 Aspect

웹 Runtime

설명

벤더의 웹 런타임. Delivery Context Ontology 참조 요망


common:vendor

웹 IDL Type

DOMString

WiFi Hardware Status

ID

status

관련 Aspect

WiFiHardware

설명

WiFi 하드웨어의 상태(ON 또는 OFF)를 나타낸다. Delivery Context Ontology 참조 요망


338 TTAK.OT-10.0323


hard:status

웹 IDL Type

DOMString 다음에서 선택된 값을 갖는다.

Value 설명

ON ON

OFF OFF

Ssid

ID

ssid

관련 Aspect

WiFiNetwork

설명

WiFi 네트워크의 서브시스템 식별명(SSID: SubSystem identification). Delivery Context

Ontology 참조 요망


net:ssid

웹 IDL 타입

DOMString

WiFi 신호 강도(Signal Strength)

ID

signalStrength

관련 Aspect

WiFiNetwork

설명

이 속성은 단말이 속한 WiFi 네트워크가 제공하는 상대적인 신호 강도(0~100)를 의미.

Delivery Context Ontology 참조 요망


339 TTAK.OT-10.0323


net:signalStrength

웹 IDL Type

unsigned long

Network Status

ID

networkStatus

관련 Aspect

WiFiNetwork

설명

WiFi 네트워크의 상태를 표시

웹 IDL Type

DOMString 다음에서 선택된 하나의 값을 갖는다.

Value 설명

connected connected

available available

forbidden forbidden

4.13.4. 참고자료

[Delivery Context Ontology]

Delivery Context Ontology (Editor's Draft) , Jose Manuel Cantera Fonseca

Telefónica I+D , 16 April 2009, (See http://www.w3.org/2007/uwa/editors-

drafts/DeliveryContextOntology/LastCallWD-April2009/)

[웹 IDL]

WebIDL (Editor's Draft) , 13 December 2010, (See

http://dev.w3.org/2006/웹 api/웹 IDL)

[Widget Packaging]

Widget Packaging and Configuration, M. Cáceres. W3C Working Draft 7 June

2011 (Work in progress). (See http://www.w3.org/TR/widgets/)


340 TTAK.OT-10.0323

4.14. WebIDL 설명

4.14.1. 요약

본 표준은 디바이스 API 와 관련하여 WAC 이 표준화하였던 웹 IDL 에 대한 모든

spec 들을 취합해 놓은 것이다.

4.14.2. 웹IDL (비필수적 정보용)

본 표준은 WAC 모듈들에서 사용되는 웹 IDL 정의들을 담고 있다. 단, API 를

적용함에 있어 이 문서는 비필수적인 단순한 정보 제공용이라는 것과, 가능한 한

웹 IDL 에서의 정의들을 중심으로 고려할 필요가 있음을 밝힌다.

module deviceapis {









};





};









341 TTAK.OT-10.0323




















};


boolean cancel();

};





};




};






342 TTAK.OT-10.0323


};

[Callback=FunctionOnly, NoInterfaceObject] interface SuccessCallback{

void onsuccess();

};



};

};

module accelerometer

{



};





successCallback,


errorCallback)








};



};




343 TTAK.OT-10.0323



};


AccelerationSuccessCallback {


};

};

module orientation

{



};




successCallback,


errorCallback)








};



};





};


344 TTAK.OT-10.0323


OrientationSuccessCallback {


};

};

module camera {




};




successCallback,



};




};




successCallback,





successCallback,





345 TTAK.OT-10.0323



successCallback,



};




};




};




};

};

module devicestatus {



};







property)



346 TTAK.OT-10.0323


successCallback,




long watchPropertyChange(in PropertyValueSuccessCallback

successCallback,







};





};





};



};




};

};

module filesystem {


347 TTAK.OT-10.0323





};








mode)


};













DOMString toURI()


PendingOperation listFiles(in FileSystemListSuccessCallback

successCallback,






in DOMString mode,


348 TTAK.OT-10.0323


encoding)



successCallback,



encoding)



























in DOMString file)


};



349 TTAK.OT-10.0323






};






void close();













};


FileSystemSuccessCallback {


};




};

[Callback=FunctionOnly, NoInterfaceObject] interface FileOpenSuccessCallback

{


350 TTAK.OT-10.0323


};




};



};

};

module messaging {




};














in Message message)




in Message message)



351 TTAK.OT-10.0323


successCallback,












};
















successCallback,



};

Message implements Synchronisable;






352 TTAK.OT-10.0323











};



};

MessageAttachment implements Synchronisable;




};




};



};


void onsuccess();



};

};

module pim {


353 TTAK.OT-10.0323



};



};

};

module contact {


typedef sequence<Contact> ContactArray;




[NoInterfaceObject] interface ContactManagerObject {


};







successCallback,



};







successCallback,


in Contact contact)



354 TTAK.OT-10.0323



in Contact contact)




in DOMString id)



successCallback,




};



};










};


{








};


355 TTAK.OT-10.0323


{


};


{



};


{



};

[Callback, NoInterfaceObject] interface ContactFilter {





attribute DOMString nickname;

attribute DOMString phoneNumber;


attribute Address address;

};




};




};


356 TTAK.OT-10.0323




};

};

module calendar {





};

















successCallback,



};







357 TTAK.OT-10.0323



in Event event)




in Event event)




in DOMString id)


PendingOperation findEvents(in EventArraySuccessCallback successCallback,




};














};



};





358 TTAK.OT-10.0323







};


EventsArraySuccessCallback {


};


{


};




};

};

module task {





};











359 TTAK.OT-10.0323




successCallback,



};








in Task task)




in Task task)




in DOMString id)






};







};


360 TTAK.OT-10.0323



};

[Callback, NoInterfaceObject] interface TaskFilter {





attribute UnsignedShortArray priority;

attribute Date initialDueDate;

attribute Date endDueDate;

};


TaskArraySuccessCallback {


};

[Callback=FunctionOnly, NoInterfaceObject] interface AddTaskSuccessCallback

{


};




};

};

module deviceinteraction {



};






void stopNotify();


361 TTAK.OT-10.0323



in long? duration,



void stopVibrate();




void lightOff();





};

};


362 TTAK.OT-10.0323

4.15. 설계 패턴과 표준을 위한 가이드(Design Patterns & Guidelines)

4.15.1. 요약

본 표준은 WAC API 로서 활용이 가능한 설계 기준과 공통 패턴을 내용으로 한다.

4.15.2. 개요

본 표준은 WAC API 로서 활용이 가능한 설계 기준과 공통 패턴을 내용으로 한다.

WAC API 는 웹과 연동하는 IDL 및 API 인터페이스 거동을 정의하는 텍스트와 방법 및

속성들을 제공하며 본 표준은 다양한 기기에서의 일반적인 API 거동을 취합하여 정리한

것이다.

4.15.3. 웹IDL 사용

WAC 의 디바이스 API 는 2010 년 12 월 13 일에 출시된 "W3C Editor’s Draft"버전에

그 WebIDL 이 정의되어 있으며 W3C 웹 IDL 은 [인터페이스 정의 언어](즉 IDL)을

정의하고 있다. WebIDL 은 여러 feature 들을 가진 하나의 IDL 파라미터로서

ECMAScript 의 거동을 좀 더 쉽게 정의하도록 한다. W3C spec 은 웹 IDL 에서의

인터페이스가 ECMAScript 내에서 어떻게 구성이 되는지를 설명하는 것이다.

개발자들이 사용하는 JavaScript API 는 WAC API 표준에서 정의하는 WebIDL 코드를

ECMAScript 와 결합한 것이다. WAC API 는 웹 IDL 에 대한 정의 외에도 WebIDL 에서

공식적으로 정의하는 방법들에 대한 기능적인 정보를 추가로 제공하고 있다. (가령 실행

중에 발생 가능한 잠재적인 에러(error)들과 충돌에 대한 예시 등)

4.15.4. 비동기적 방법

ECMAScript 메소드는 동기적인 것과 비동기적인 것이 있다. 여기서 동기적 모드를

사용하는 방법이란 operation 이 완료가 되기 이전까지는 caller 에게 컨트롤을 반환해

주지 않는 것이고 비동기적인 방법이란 즉시 반환을 해 주면서 또한 미래의 한 시점에

callback 방법을 통해 caller 에게 그 결과를 통지해 준다. 여기서 callback 방법이란

비동기적 방법에 대한 입력 파라미터로 정의가 가능하며 실행에 시간이 많이 걸리거나

또는 보안 prompt 가 요구되는 방법인 경우 WAC 에서는 비동기적 방법인 것으로

정의된다.

비동기적 방법에는 첫 번째 인수가 함수인가 인터페이스인가에 따라 크게 2 가지

종류가 있다.


363 TTAK.OT-10.0323

가. Only Success Callback 함수

only success callback 함수는 대부분의 경우 단지 해당 동작(operation)이

성공여부 만을 통지할 때 사용된다. 이 함수의 경우 처음 2 개의 입력 인수들은

아래와 같다.

• 콜백을 규정하는 함수로서 성공인 경우 동작된다. (가령. SuccessCallback),

• ErrorCallback 인터페이스를 호출하는 함수.

Only Success Callback 함수의 예

API 에서 이 패턴이 사용될 경우 거의 대부분에 있어 콜백 인터페이스가 특정하게

정의되어 있으므로 비동기적 동작의 결과가 호출자(caller)에게 전달이 될 수 있다.

나. Success Callback 인터페이스

success callback 인터페이스는 서로 다른 여러 동작(가령 다중의 수신자에게

개별적으로 메시지를 전송) 각각에 대해 통지가 필요할 경우 사용된다. 이

인터페이스에서의 2 가지 입력 인수의 순서는 다음과 같다.

• 최종 성공에 대한 개별통지의 방법으로 여러 방법들을 규정하는 인터페이스

• ErrorCallback 인터페이스를 호출하는 함수



in Message message);


void onsuccess();

};



};


364 TTAK.OT-10.0323

Callback 인터페이스의 예

다. 비동기적 방법에 대한 입력 인수

2 가지 방법 모두에 있어(즉 Function Only 함수와 인터페이스) 2 번째의입력 인수

(errorCallback)가 만일 정의되지 않다거나 미포함 또는 무효로 됨으로써 비동기적

operation 이 진행되는 동안 개발자에게 error 정보를 제공하지 못할 경우 언제나

optional 한 상태가 된다. 주: 일부 경우로 이 "optional" 태그를 WebIDL 에서 미리

정의하지 못하는 경우가 있는데, 그 이유는 만일 그렇지 않을 경우 뒤따르는 모든

속성들도 optional 해야 하기 때문이다. 그러나 errorCallback 에 대한 optional

상태는 본 표준에 방법이 설명되어 있다.

한편 첫 번째 입력 파라미터는 필수적이다. 만일 이 파라미터가 어떤 유효한 값을

포함하지 않을 경우(즉 가령 정의되어 있지 않다거나 또는 Only 함수 타입의 함수나

인터페이스를 포함하지 않는 경우 등의 경우 ErrorCallback 은

INVALID_VALUES_ERR 라는 error code 를 발생시킨다.

라. 비동기적 방법에 의한 값들의 반환

비동기적 방법은 PendingOperation 대상을 반환시키거나 또는 null 시킨다. 여기서

null 값이 반환된 경우 이는 callback 함수중의 하나가 비동기적 방법이 종료되기

이전에 이미 실행이 되었음을 의미한다.

PendingOperation 인터페이스는 "cancel" 방법을 제공하는 것으로서 즉 비동기적인

방법에 의한 call 을 취소시키는 역할을 한다. 그러나 null 값이 아닌

PendingOperation 결과를 반환시키는 비동기적 동작이 모든 경우에서 반드시

취소될 수 있다는 것을 보증하지는 않는다.

PendingOperation sendMessage(in MessageSendCallback

successCallback,


in Message message);


void onsuccess();


void onmessagesenderror(in Error e, in DOMString recipient);

};



};


365 TTAK.OT-10.0323

4.16. 에러 처리

WAC API 는 DOMError 기반의 DeviceAPIErro 인터페이스를 통해 에러정보를

개발자에게 제공하는 바, 이 DeviceAPIErro 인터페이스는 사전에 정의된 일련의

error code 들을 포함하고 있다.

WAC API 는 또한 어떤 새로운 error 인터페이스를 규정하지 않고서도

[Supplemental] 키워드를 사용하여 추가적인 error code 를 정의할 수 있도록 한다,

개발자에게 에러상황에 대한 정보를 통지하는 설계타입은 그 정보제공의 방법에

따라 여러 가지로 선택이 가능하다.

4.16.1. 동기적 방법

동기적 방법을 실행시킬 경우 에러 조건은 DeviceAPIError 와 연동된 예를 통해

표출된다. 여기서 말하는 에러조건이란 WebIDL 상에서 raise 조항

(DeviceAPIError)을 통해 설명되어 있다. error code 들은 exception

(DeviceAPIError) 예의 형태로 반환될 수 있으며 그 구체적인 내용이 방법을

설명하는 내용 중 Exceptions 절에 나타나 있다.

예를 들어 다음과 같은 IDL 은 동기적 함수를 선언하는 것이다.

동기적 방법으로의 에러 처리



다음은 HTML 형식으로 제공되는 error code 들의 예이다.

예외

• DeviceAPIError:

입력파라미터에 유효하지 않은 값이 포함되었을 경우 error code 는

INVALID_VALUES_ERR 임

입력 파라미터가 동 파라미터에 해당하는 타입과 연동되지 않을 경우의 error

code 는 TYPE_MISMATCH_ERR 임

4.16.2. 비동기적 방법

비동기적 방법이 실행될 경우 implementation 은 인수가 유효한 type 인지를

체크하고 그렇지 않을 경우 적절한 type 으로 coerce 시킨다. 어떤 전송된 인수가


366 TTAK.OT-10.0323

선언된 type 과 비교하여 만약 다른 type 일 경우 TYPE_MISMATCH_ERR 이라는

code 와 함께 동기적으로 DeviceAPIError 가 발생된다. 기타 다른 에러는 비동기

함수에 입력인수로서 전송된 ErrorCallback 으로 반환된다. 여기서 이 방법에 대한

표준화는 어떤 code 와 어떤 조건으로 에러를 ErrorCallback 으로 반환할 것인지를

규정하는 것이다. 만일 전송된 error callback 이 없을 경우 이 방법은 null 값으로

되거나 정의되지 않으며 따라서 추가적인 통지는 필요 없다.(즉 이 방법이

무효화됨)

제공된 인수와 선언된 IDL 인수 type 간에의 type 변환은 ECMAScript 와 웹 IDL

결합을 통해 이루어진다.

다음은 동기적 방법을 선언하는 웹 IDL 의 예이다.

비동기적 방법에서의 에러처리



in Message message)


The raises (DeviceAPIError)에 대한 raise 장은 비록 비동기적 방법이더라도 인수가

유효한 type 이 아닐 경우(TYPE_MISMATCH_ERR)에는 DeviceAPIError 가 발생할 수

있음을 설명하고 있다. 동 내용은 방법에 대한 exception list 에 설명되어 있다.

Exceptions

• DeviceAPIError:

입력파라미터가 동 파라미터에 해당하는 타입과 연동되지 않을 경우의 error

code 는 TYPE_MISMATCH_ERR 임

errorCallback 로 반환되는 error 들 또한 메소드를 설명하는 장에 정의되어 있다.

동작 수행이 종료되면(즉 implementation 이 모든 수신자들에 대해 전송된 동작

결과를 알게 되면) 여기서 만일 메시지가 모든 수신자들에게 성공적으로 전송이

되었다면 successCallback 의 onsuccess 가 동작하게 되고 만일 그렇지 못했을

경우에는 적절한 error code 와 함께 errorCallback 이 동작한다.

• NOT_SUPPORTED_ERR: 원하는 메시징이 이루어지지 못한 경우

• SECURITY_ERR: 동작이 되지 않는 경우

• UNKNOWN_ERR: 기타 다른 타입의 에러 시


367 TTAK.OT-10.0323

4.16.3. 사용 예시

가. Only 함수와 success callback 인터페이스 둘 다의 경우

sendMessage("notACallback",

checkError(e){alert("An error with code " + e.code + " occurred"},

msg);

successCallback 이 notACallback 이면, error callback 으로 반환되면서

TYPE_MISMATCH_ERR 라는 DeviceAPIError 가 발생된다.

sendMessage(null, checkError(e){alert("An error with code " + e.code +"curred"},

msg);

successCallback 이 null 되면, error callback 으로 반환이 되면서

INVALID_VALUES_ERR 라는 error code 가 발생된다.

나. Only 함수 callback인 경우

sendMessage(success(){alert("Message sent")}, "notACallback", msg);

"notACallback"이 인터페이스로 표출되지 못하므로 TYPE_MISMATCH_ERR 라는

code 를 갖는 DeviceAPIError 가 발생한다.

sendMessage(success(){alert("Message sent")}, null, msg);

AerrorCallback 이 null 값으로 될 때, 메소드가 실행이 되는데, 만일 이것이

성공적으로 완료가 되면 successCallback 이 동작하게 되며 만일 성공적으로

완료가 되지 못할 경우에는 silent 하게 fail 된다.

sendMessage(success(){alert("Message sent")},


msg);

메소드가 실행이 되어 만일 성공적으로 완료가 되면 successCallback 이 발생하고

그렇지 못할 경우에는 적절한 error code 와 함께 errorCallback 이 발생된다.


368 TTAK.OT-10.0323

다. callback 인터페이스인 경우

sendMessage ({onmessagesendsuccess: function(recipient) {"Message sent to " +

recipient}},

checkError(e){alert("An error with code " + e.code + " ccurred"},

msg);

메소드가 실행이 되면 메시지가 수신자에게 전달이 될 때마다

onmessagesendsuccess 함수가 동작이 된다. 사용되는 입력 인터페이스에 그 어떤

함수도 구성되어 있지 않으므로 개별 메시지의 전송이 실패하거나 또는 모든

동작이 다 성공적으로 전송이 되었더라도 별다른 통지는 이루어지지 않는다.

sendMessage({onmessagesenderror:function(error, recipient){alert("Message to"

+ recipient + " failed")}},


msg);

메소드가 실행이 된 상태에서 수신자에게 메시지 전달이 실패할 때마다

onmessagesenderror 함수가 동작이 된다. 첫 번째 인수로서 pass 가 된 입력

인터페이스에 그 어떤 함수도 구성되어 있지 않으므로 개별 메시지의 전송이

성공적으로 이루어졌거나 또는 모든 동작이 다 성공적으로 전송이 되었더라도

별다른 통지는 이루어지지 않는다.

sendMessage ({foo: function(error, recipient) {alert("foo")}},


msg);

메소드가 실행이 된 상태에서 첫 번째 인수에는 사전에 정의된 그 어떤

handler(onmessagesenderror, onmessagesendsuccess and onsuccess)도

포함되어 있지 않으므로 개발자에게 이벤트와 관련된 그 어떤 정보도 notify 되지

않는다.

4.16.4. Optional, Nullable 및 타당한 인수

웹 IDL 은 어떤 인수가 만일 optional 한 경우 이를 document 하는 메커니즘을

제공한다. 따라서 이처럼 optional 한 경우에는 인수 type 의 바로 앞에

선태가항(optional) 이라는 단어를 반드시 명시해 줘야 한다.

가령 다음에 예시로서 보이는 WebIDL 의 경우 2 번째와 3 번째의 입력인수들이

optional 한 것임을 알 수 있는 것이다.


369 TTAK.OT-10.0323

Optional 인수들의 예





Optional 한 인수들은 반드시 인수들이 표현된 list 상에서 가장 맨 뒤에 위치하도록

되어 있다. 따라서 optional 인수 뒤로 optional 하지 않은 인수들이 위치할 수는

없다. Optional 인수는 개발자에 의해 생략할 수 있다. 예를 들어 메소드

watchAcceleration 의 두 call 들이 유효한 경우 다음의 예시가 가능하다.

watchAcceleration(function(acc){alert("Operation completed")});

watchAcceleration(function(acc){alert("Operation completed")},

errorHandler(e){"Error occured";});


errorHandler(e){"Error occurred";},

{minNotificationInterval:10000});

만일 optional 인수가 적절한 type 이 아니거나 또는 coerce 될 수 없는 경우라면

TYPE_MISMATCH_ERR 라는 code 와 함께 error 를 발생시키도록 하여야 한다. 예를

들어


"invalidFunction");

여기서 2 번째 인수는 기대되는 type(함수)으로 coerce 할 수 없다.

optional 인수가 만일 유효하지 않은 인수를 포함하고 있을 경우에는, 설사 그

type 이 올바른 것이라 하더라도 별도의 방법을 적시해 주지 않는 한,

INVALID_VALUES_ERR 를 표출하도록 반환(또는 동기적 방법인 경우

fail 시킴)시켜야 한다.


errorHandler(e){"Error occurred";},

{foo:10000});

여기서 3 번째 인수는 적절한 타입(type)이기는 하지만 스펙 따른 유효한 값을

포함하고 있지는 않다. 그러나 스펙에서 "optional 한 인수가 유효하지 않거나 null


370 TTAK.OT-10.0323

또는 정의되지 않은 경우 implementation 은 동 인수를 무시하고

minNotificationInterval 없이 진행이 되어야 한다."라고 규정하고 있으므로,

따라서 implementation 은 3 번째 속성의 유효하지 않은 값으로 인한 error 로

반환되지 않고 마치 3 번째 인수가 사용되지 않는 것과 같은 상태로 진행을

시키도록 하고, 이 경우 다음과 같은 내용이 표출된다.


errorHandler(e){"Error occurred";});

nullable 한 입력인수는 Data Type 에 ‘?’문자를 첨미시킴으로써 구별을 하되,

Primitive ECMAScript Data Type 에만 사용이 되도록 할 수 있다. 웹 IDL 표준은

모든 개발된 인터페이스에 대해 null value 를 적절한 인터페이스 type 인 것으로

간주한다. 정의되지 않은 것은 null 로 coerce 되므로 이는 인터페이스 type 에 대한

입력인수에 대해서도 마찬가지로 해석할 수 있다.

primitive type 인 경우에는 다음과 같은 WebIDL 선언을 고려하도록 한다.

Optional 및 Nullable 한 primitive type 인수


[TreatUndefinedAs=Null] in optional DOMString? property)

다음에 보이는 call 예시는 맨 마지막의 인수를 생략할 수 있고(즉 optional) 또한

null 시킬 수도 있으므로(즉 nullable) valid 하며 equivalent 하다.

isSupported("Battery", null);

isSupported("Battery");

인터페이스 type 인 경우에는 다음과 같은 WebIDL 선언을 고려하도록 한다.

Optional 및 Nullable 한 인터페이스 type 인수





다음의 예시는 모두 valid 하며 equivalent 하다.


371 TTAK.OT-10.0323

watchOrientation(f(rotation){alert("Orientation Retrieved")});

watchOrientation(f(rotation){alert("Orientation Retrieved")}, null);

watchOrientation(f(rotation){alert("Orientation Retrieved")}, null, null);

상기의 모든 예의 경우 optional 한 인수가 함수에 pass 된 것은 없으며 그 어떤

error 정보도 개발자에게 통지되지 않는다.

다음의 invocation 예제들은 유효하지 않은 경우들이다:

watchOrientation()

watchOrientation(null)

watchOrientation(null, null)

watchOrientation(null, null, null)

두 경우에서 implementation 은 입력인수가 유효한 type 이 됨에 따라(가령 어떤

인터페이스 type 에서 null 은 유효한 예이다) silent 하게 fail 된다, implementation 은

ErrorCallback 에서 INVALID_VALUES_ERR 를 반환하여야 하지만 null 인 상태에서

이것이 불가능하다.

errorCallback 이 pass 된 경우,

watchOrientation(null, error(e){alert('An error occurred " + e.code);})

implementation 은 첫 번째 인수가 유효한 type 이므로 INVALID_VALUES_ERR 라는

에러를 pass 하는 errorCallback 을 launch 한다.

입력인수가 유효한 type 인지 아닌지를 확인하는 방법으로 coerce 하는 방법을

사용한다는 것을 이미 언급한 바 있다. ECMAScript 는 느슨한 형식의 언어이고

게다가 다른 프로그램 언어에서는 true 하다고 여겨지는 assumption 이

ECMAScript 에서는 유효하지 않은 경우도 있다. 또한 type 에 대해 WebIDL 에서

정의하는 rule 을 implementation 을 통해 로드해야 할 필요도 있다.

다음은 웹 IDL 선언에 대한 예시이다:

Coercion



call clearWatch("Foo")는 TYPE_MISMATCH_ERR 를 생성하지 않는데, 그 이유는

"Foo"가 long primitive type 에서 유효한 값인 0 으로 coerce 될 수 있기 때문이다..


372 TTAK.OT-10.0323

4.16.5. API 특징을 이용한 API로의 접근

WAC API 는 window JavaScript 객체인 window.deviceapis 내의 deviceapis 객체를

통해 표출되는데, 그 표출 정도는 deviceapis module 설명서에 자세히 나와 있다.

개발자는 이 객체에 접근하기 위해서는, http://wacapps.net/api/deviceapis 에 부합하는

feature 들을 widget configuration(config.xml) 형식으로 선언할 필요가 있다.

기타 module 들은 window.deviceapis 객체의 child interface(가령

window.deviceapis.orientation)로서 표출되어 있지만 예외가 되는 것이 pim

capability 의 sub-module 들로 이것들은 다른 수준의 체계를 갖고 있다

(window.deviceapis.pim.task, window.deviceapis.pim.calendar,

window.deviceapis.pim.contact).

일부 module 들은 둘 이상의 feature 들을 갖고 있지만 개발자들에 따라서는 가령

보안이나 실행상의 이유로 일부의 feature 만을 필요로 하기도 한다. 이처럼 하나의

module 에서 feature 들의 일부 기능들에 대한 정의는 해당 표준서의 “Features”절에

나와 있고 또한 이 feature 들이 성공적으로 config.xml 으로 request 가 가능한 경우

개발자에게 제공이 되기도 한다. 개발자가 동 module 에 링크된 하나 이상의 feature 를

configuration 사양에 포함을 시킬 경우 “Features”절에 명시해 주는 방법으로 동

module 의 top-level 객체를 deviceapis 트리 아래로 로드를 시킨다. 모든 module 에는

반드시 하나의 모듈 트리 아래에 존재하는 모든 하부 특징들에 접근할 수 있도록 하는

generic feature 가 포함되어 있으므로 개발자 입장에서는 module 의 전체적인

함수관계를 파악하고자 할 때 유용하게 사용할 수 있다.


373 TTAK.OT-10.0323

예제 1

만일 개발자가 configuration 상에 다음 feature 들을 포함시키고자 할 경우


http://wacapps.net/api/filesystem

http://wacapps.net/api/messaging

이 개발자는 다음과 같은 ECMAScript 체계를 사용할 수 있다:

window.deviceapis (includes all the deviceapis module functionality)

window.deviceapis.filesystem (includes all the filesystem module functionality)

window.deviceapis.messaging (includes all the messaging module functionality)

상기의 feature 들을 갖는 마찬가지의 방법으로 module 의 sub-feature 들을

포함시킬 수도 있다:


http://wacapps.net/api/filesystem.read

http://wacapps.net/api/filesystem.write

http://wacapps.net/api/messaging.find

http://wacapps.net/api/messaging.write

http://wacapps.net/api/messaging.subscribe


예제 2

만일 module 에서 단 하나의 sub-feature 만을 포함시킬 경우



개발자는 다음과 같은 ECMAScript 체계를 사용할 수 있다:


window.deviceapis.messaging (includes only the messaging send functionality)

만일 개발자가 send 기능(가령 window.deviceapis.messaging.onSMS())을

허용하지 않는 방법을 사용하고자 할 경우, implementation 은 error 객체의

SECURITY_ERR 코드를 errorCallback 으로 반환하여야 한다.


374 TTAK.OT-10.0323

한편 만일 개발자가 configuration(가령. filesystem) 상에 아무런 feature 를

선언하지 않은 채 하나의 module 에 링크된 어떤 기능을 사용하고자 할 경우에는

ReferenceError 가 생성된다.

예제 3

PIM Feature 들로는


http://wacapps.net/api/pim.contact

http://wacapps.net/api/pim.calendar

http://wacapps.net/api/pim.task

이 경우에 있어 개발자는 가령 다음과 같은 ECMAScript 체계를 사용할 수 있다.


window.deviceapis.pim.contact (includes all the contact module functionality)

window.deviceapis.pim.calendar (includes all the calendar module functionality)

window.deviceapis.pim.task (includes all the task module functionality)

여기서 pim module 을 보면 window.deviceapis.pim 인터페이스는 단지 모든 pim

module 들을 포함시키는 하나의 placeholder 이지만 그 자체로 그 어떤 기능성도

제공하지 않는다는 것을 알 수 있다.


375 TTAK.OT-10.0323

표준 작성 공헌자

표준 번호 : TTAK.OT-10.0323

이 표준의 제정·개정 및 발간을 위해 아래와 같이 여러분들이 공헌하였습니다.

구분 성명 위원회 및 직위 연락처

(E-mail 등) 소속사

과제 제안 이효석 - [email protected] MOIBA

표준 초안

제출 이효석 - [email protected] MOIBA

표준 초안

검토

이승윤 웹 프로젝트그룹

의장 [email protected] ETRI

외 프로젝트그룹 위원

표준안 심의

박승민 기반소프트웨어 기술위원회

의장 [email protected] ETRI

외 기술위원회 위원

사무국 담당

박정식 - [email protected] TTA

이혜진 - [email protected] TTA



(Korea Apps Device API)

발행인 : 한국정보통신기술협회 회장

발행처 : 한국정보통신기술협회

463-824, 경기도 성남시 분당구 서현동 267-2

Tel : 031-724-0114, Fax : 031-724-0109

발행일 : 2011.12.

정보통신단체표준(국문표준) i ttak.ot-10.0323 서 문 1. 표준의 목적 본 표준은...

Documents