위치 정보

Geolocation의 인스턴스는 아래 표의 내부 슬롯과 함께 생성됩니다:

getCurrentPosition(successCallback, errorCallback, options) 메서드 단계:

1. 만약 현재 설정 객체의 관련 전역 객체의 연결된 Document가 완전히 활성 상태가 아니라면: 만약 this의 관련 전역 객체의 연결된 Document가 완전히 활성 상태가 아니라면:
   1. 오류 콜백 호출 errorCallback 및 POSITION_UNAVAILABLE 전달.
   2. 이 알고리즘 종료.
2. 위치 요청 시 this, successCallback, errorCallback, options을 전달.

watchPosition(successCallback, errorCallback, options) 메서드 단계:

1. 만약 현재 설정 객체의 관련 전역 객체의 연결된 Document가 완전히 활성 상태가 아니라면: 만약 this의 관련 전역 객체의 연결된 Document가 완전히 활성 상태가 아니라면:
   1. 오류 콜백 호출 시 errorCallback 및 POSITION_UNAVAILABLE 전달.
   2. 0을 반환.
2. watchId를 0보다 큰 구현 정의 unsigned long 값으로 생성.
3. watchId를 리스트에 추가 (this의 [[watchIDs]]에).
4. 위치 요청 시 this, successCallback, errorCallback, options, watchId를 전달.
5. watchId를 반환.

clearWatch()가 호출되면, 사용자 에이전트는 반드시 다음을 수행해야 합니다:

1. watchId를 this의 [[watchIDs]]에서 제거합니다.

위치 요청을 하려면, Geolocation geolocation, PositionCallback successCallback, PositionErrorCallback? errorCallback, PositionOptions options, 그리고 선택적으로 watchId를 전달합니다:

1. watchIDs에 geolocation의 [[watchIDs]]를 할당합니다.
2. document에 geolocation의 관련 전역 객체의 연결된 Document를 할당합니다.
3. 만약 document가 "geolocation" 기능을 사용할 수 없음이라면:
   1. watchId가 전달된 경우, watchId를 watchIDs에서 제거합니다.
   2. 오류 콜백 호출 시 errorCallback 및 PERMISSION_DENIED를 전달합니다.
   3. 이 알고리즘을 종료합니다.
4. 만약 geolocation의 환경 설정 객체가 비보안 컨텍스트라면:
   1. watchId가 전달된 경우, watchId를 watchIDs에서 제거합니다.
   2. 오류 콜백 호출 시 errorCallback 및 PERMISSION_DENIED를 전달합니다.
   3. 이 알고리즘을 종료합니다.
5. 만약 document의 visibility state가 "hidden"이라면, 다음 페이지 가시성 변경 단계가 실행될 때까지 대기합니다:
   1. Assert: document의 visibility state가 "visible"임을 확인합니다.
   2. 아래의 다음 단계로 계속 진행합니다.
6. descriptor에 PermissionDescriptor의 새 인스턴스를 할당하며, name은 "geolocation"입니다.
7. 병렬로:
   1. permission에 request permission to use descriptor의 결과를 할당합니다.
   2. 만약 permission이 "denied"라면:
      1. watchId가 전달된 경우, watchId를 watchIDs에서 제거합니다.
      2. 오류 콜백 호출 시 errorCallback 및 PERMISSION_DENIED를 전달합니다.
      3. 이 알고리즘을 종료합니다.
   3. 위치 획득 시 successCallback, errorCallback, options, watchId를 전달하며 대기합니다.
   4. watchId가 전달되지 않았다면, 이 알고리즘을 종료합니다.
   5. watchIDs가 watchId를 포함하는 동안:
      1. 지리적 위치의 유의미한 변경을 대기합니다. 유의미한 변경이 무엇인지의 기준은 구현에 맡깁니다. 사용자 에이전트는 위치 변경 보고 빈도에 제한(rate limit)을 둘 수 있습니다. 사용자 에이전트는 반드시 set emulated position data 호출을 유의미한 변경으로 간주해야 합니다.
      2. 만약 document가 완전히 활성 상태가 아니거나 visibility state가 "visible"이 아니면, 이전 단계로 돌아가 다시 지리적 위치의 유의미한 변경을 대기합니다.
         참고: 위치 업데이트는 오직 완전히 활성화되고 visible한 문서에만 전달됨
      3. 위치 획득 시 successCallback, errorCallback, options, watchId를 전달하며 대기합니다.

위치 획득을 하려면, PositionCallback successCallback, PositionErrorCallback? errorCallback, PositionOptions options, 그리고 선택적으로 watchId를 전달합니다.

1. watchId가 전달되었고 this의 [[watchIDs]]가 watchId를 포함하지 않으면, 이 알고리즘을 종료합니다.
2. acquisitionTime에 현재 시점을 나타내는 새로운 EpochTimeStamp를 할당합니다.
3. timeoutTime에 acquisitionTime과 options.timeout을 더한 값을 할당합니다.
4. cachedPosition에 this의 [[cachedPosition]]를 할당합니다.
5. 구현 특화 timeout 태스크를 timeoutTime에 만료되도록 생성하며, 만료 전까지 장치의 위치를 획득하기 위해 다음 단계를 실행합니다:
   1. permission에 현재 권한 상태를 "geolocation"으로 조회한 결과를 할당합니다.
   2. permission이 "denied"라면:
      1. timeout을 중지합니다.
      2. 사용자 또는 시스템이 권한 거부 실패 케이스 단계를 수행합니다.
   3. permission이 "granted"라면:
      1. 에뮬레이션된 위치를 사용할지 확인하려면 다음 단계를 실행합니다:
         1. emulatedPositionData에 get emulated position data에 this를 전달한 결과를 할당합니다.
         2. emulatedPositionData가 null이 아니라면:
            1. emulatedPositionData가 GeolocationPositionError 타입이라면:
               1. 오류 콜백 호출 시 errorCallback 및 emulatedPositionData.code를 전달합니다.
               2. 이 알고리즘을 종료합니다.
            2. position에 새 GeolocationPosition을 emulatedPositionData, acquisitionTime 및 options.enableHighAccuracy를 전달하여 생성합니다.
            3. 태스크 큐에 등록하여 geolocation 태스크 소스에서 successCallback 콜백 호출 시 « position » 및 "report"를 전달합니다.
            4. 이 알고리즘을 종료합니다.
      2. position을 null로 설정합니다.
      3. cachedPosition이 null이 아니고 options.maximumAge가 0보다 크면:
         1. cacheTime에 acquisitionTime에서 options.maximumAge 값을 뺀 결과를 할당합니다.
         2. cachedPosition의 timestamp 값이 cacheTime보다 크고, cachedPosition.[[isHighAccuracy]]가 options.enableHighAccuracy와 같다면, position을 cachedPosition으로 설정. :
            1. 태스크 큐에 등록하여 geolocation 태스크 소스에서 successCallback 콜백 호출 시 « cachedPosition » 및 "report"를 전달합니다.
            2. 이 알고리즘을 종료합니다.
      4. 그 밖에 position이 cachedPosition이 아닌 경우, 시스템에서 위치 데이터를 획득하며 필요시 options.enableHighAccuracy 값을 고려합니다.
      5. 획득 중 timeout이 만료되거나 위치 획득에 실패하면:
         1. timeout을 중지합니다.
         2. 실패 처리로 이동합니다.
         3. 이 알고리즘을 종료합니다.
      6. 시스템에서 위치 데이터 획득에 성공하면:
         1. positionData에 획득한 위치 데이터를 기반으로 아래 name/value 쌍을 가진 map을 할당합니다:

            "longitude"

            double 타입이며, [WGS84] 좌표계 기준으로 지구 표면의 경도(도)를 나타냅니다. 경도는 본초자오선 기준 동/서 방향 거리를 측정합니다.

            "altitude"

            double? 타입이며, [WGS84] 기준 타원체 위의 고도(미터)를 나타내며, 제공되지 않을 경우 null입니다. 고도는 해수면 기준 높이를 측정합니다.

            "accuracy"

            음이 아닌 double 타입이며, 95% 신뢰 구간(미터)로 정확도를 나타냅니다. 정확도는 측정 좌표가 실제 위치와 얼마나 가까운지 나타냅니다.

            "altitudeAccuracy"

            음이 아닌 double? 타입이며, 제공되지 않을 경우 null이며, 95% 신뢰 구간(미터)로 고도 정확도를 나타냅니다.

            "speed"

            음이 아닌 double? 타입이며, 제공되지 않을 경우 null이며, 속도(초당 미터)를 나타냅니다.

            "heading"

            double? 타입이며, 제공되지 않거나 장치가 정지 상태일 경우 null이며, 방향(도, 진북 기준)을 나타냅니다.

         2. position에 새 GeolocationPosition을 positionData, acquisitionTime, options.enableHighAccuracy를 전달하여 생성합니다.
         3. this의 [[cachedPosition]]를 position으로 설정합니다.
         1. position에 새 GeolocationPosition을 acquisitionTime, options.enableHighAccuracy를 전달하여 생성합니다.
         2. this의 [[cachedPosition]]를 position으로 설정합니다.
      7. timeout을 중지합니다.
      8. 태스크 큐에 등록하여 geolocation 태스크 소스에서 successCallback 콜백 호출 시 « position » 및 "report"를 전달합니다.

   실패 처리:

   • 위치 획득에 실패하면, 조건에 따라 아래 중 하나를 수행합니다:

     사용자 또는 시스템이 권한 거부:

     오류 콜백 호출 시 errorCallback 및 PERMISSION_DENIED를 전달합니다.

     참고: 브라우저 권한 VS OS 권한

     타임아웃 만료:

     오류 콜백 호출 시 errorCallback 및 TIMEOUT를 전달합니다.

     데이터 획득 오류 또는 기타 이유:

     오류 콜백 호출 시 errorCallback 및 POSITION_UNAVAILABLE를 전달합니다.

오류 콜백 호출 지시를 받으면, PositionErrorCallback? callback과 unsigned short code가 주어집니다:

1. callback이 null이면, 리턴합니다.
2. error에 GeolocationPositionError의 새 인스턴스를 생성하여 code 속성을 code로 초기화합니다.
3. 태스크 큐 등록하여 geolocation 태스크 소스에서 callback을 « error » 및 "report"로 호출합니다.

enableHighAccuracy 멤버는 애플리케이션이 가장 정확한 위치 데이터를 받고 싶다는 힌트를 제공합니다. 이 멤버의 목적은 애플리케이션이 고정밀 위치 정보가 필요하지 않음을 구현에 알리고, 따라서 구현체가 많은 전력을 소모하는 위치 제공자(GPS 등) 사용을 피할 수 있음을 허용하는 것입니다.

timeout 멤버는 위치 획득이 만료되기 전까지 허용되는 최대 대기 시간을 밀리초 단위로 지정합니다.

maximumAge 멤버는 웹 애플리케이션이 지정한 시간(밀리초) 이내의 캐시된 위치를 허용할 수 있음을 나타냅니다.

coords 속성은 지리적 좌표를 포함합니다.

timestamp 속성은 장치의 지리적 위치가 획득된 시간을 나타냅니다.

toJSON() 메서드는 GeolocationPosition 객체의 JSON 표현을 반환합니다.

GeolocationPositionError의 인스턴스는 아래 표의 내부 슬롯과 함께 생성됩니다:

본 명세에서 아래의 태스크 소스를 정의합니다.

geolocation 태스크 소스

본 명세에서는 PositionCallback 및 PositionErrorCallback를 비동기로 큐잉할 때 사용합니다(위치 요청 수행 시).

The latitude and longitude attributes are geographic coordinates specified in decimal degrees. latitude 및 longitude 속성은 [WGS84] 기준 시스템의 실수(degree)로 위치를 나타냅니다. accuracy 속성은 위치의 정확도 반경을 미터 단위로 나타냅니다.

altitude 속성은 [WGS84] 타원체 기준 미터 단위의 위치 높이를 나타냅니다.

altitudeAccuracy 속성은 고도 정확도를 미터 단위(예: 10미터)로 나타냅니다.

heading 속성은 호스트 장치의 이동 방향을 나타내며, 0° ≤ heading < 360°로 진북 기준 시계 방향(도 단위)입니다.

speed 속성은 호스트 장치의 현재 수평 속도의 크기를 초당 미터 단위로 나타냅니다.

toJSON() 메서드는 GeolocationCoordinates 객체의 JSON 표현을 반환합니다.

PERMISSION_DENIED (숫자 값 1)

위치 요청이 사용자가 API 사용을 거부했거나 혹은 비보안 컨텍스트에서 요청이 이루어진 경우 실패했습니다.

POSITION_UNAVAILABLE (숫자 값 2)

위치 획득에 실패했습니다.

TIMEOUT (숫자 값 3)

timeout 멤버에 지정된 시간이 경과하여 사용자 에이전트가 성공적으로 위치를 획득하지 못했습니다.

code 속성은 초기화된 값을 반환합니다. (가능한 값은 10.1 상수를 참고하세요.)

message 속성은 code 속성에 대한 개발자 친화적 텍스트 설명입니다.