지리 위치

geolocation 속성은 Geolocation API에 접근하기 위한 진입점을 제공합니다.

Geolocation 인스턴스는 다음 표에 나열된 내부 슬롯으로 생성됩니다:

getCurrentPosition(successCallback, errorCallback, options) 메서드의 절차는 다음과 같습니다:

1. If this's relevant global object's associated Document is not fully active:
   1. 오류와 함께 콜백 호출 errorCallback 및 POSITION_UNAVAILABLE를 전달합니다.
   2. 이 알고리듬을 종료합니다.
2. 위치 요청을 수행하여 this, successCallback, errorCallback, 및 options을 전달합니다.

watchPosition(successCallback, errorCallback, options) 메서드의 절차는 다음과 같습니다:

1. If this's relevant global object's associated Document is not fully active:
   1. 오류와 함께 콜백 호출하여 errorCallback 및 POSITION_UNAVAILABLE를 전달합니다.
   2. 0을 반환합니다.
2. 양의 값인 구현 정의 watchId를 정의합니다.
3. 추가하여 watchId를 this의 [[watchIDs]]에 넣습니다.
4. 위치 요청을 수행하여 this, successCallback, errorCallback, options, 및 watchId를 전달합니다.
5. watchId를 반환합니다.

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

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

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

1. Let watchIDs be geolocation's [[watchIDs]].
2. Let document be the geolocation's 관련 전역 객체(relevant global object)'s 연관된 Document.
3. If document is not 사용이 허용(allowed to use)된 "geolocation" 기능:
   1. If watchId was passed, 제거(remove) watchId 를 watchIDs에서.
   2. 오류와 함께 콜백 호출하여 errorCallback 및 PERMISSION_DENIED를 전달합니다.
   3. 이 알고리즘을 종료합니다.
4. If geolocation's 환경 설정 객체(environment settings object)가 비보안 컨텍스트(non-secure context)인 경우:
   1. If watchId was passed, 제거(remove) watchId 를 watchIDs에서.
   2. 오류와 함께 콜백 호출하여 errorCallback 및 PERMISSION_DENIED를 전달합니다.
   3. 이 알고리즘을 종료합니다.
5. If document's visibility state가 "hidden"인 경우, 다음의 페이지 가시성 변경 단계(page visibility change steps)가 실행될 때까지 대기합니다:
   1. 단언(Assert): document의 visibility state가 "visible"임을 단언합니다.
   2. 아래의 다음 단계로 계속합니다.
6. Let descriptor be a new PermissionDescriptor이며, 그 name은 "geolocation"입니다.
7. 병렬로(In parallel):
   1. Set permission to 권한 사용 요청(request permission to use) descriptor로 설정합니다.
   2. If permission is "denied", then:
      1. If watchId was passed, 제거(remove) watchId 를 watchIDs에서.
      2. 오류와 함께 콜백 호출하여 errorCallback 및 PERMISSION_DENIED를 전달합니다.
      3. 이 알고리즘을 종료합니다.
   3. 다음으로 위치 획득(acquire a position)을 대기하며, successCallback, errorCallback, options, 및 watchId를 전달합니다.
   4. If watchId was not passed, terminate this algorithm.
   5. While watchIDs contains watchId:
      1. 지리적 위치의 유의미한 변화(Wait for a significant change of geographic position)를 대기합니다. 무엇이 유의미한 위치 변화인지는 구현에 맡깁니다. 사용자 에이전트는 위치 변화가 보고되는 빈도를 제한할 수 있으며(User agents MAY), 사용자 에이전트는 에뮬레이션된 위치 데이터 설정(set emulated position data)를 유의미한 변화로 간주해야 합니다(User agents MUST 고려).
      2. If document is not 완전히 활성화(fully active)이거나 visibility state가 "visible"이 아니면, 이전 단계로 돌아가 다시 지리적 위치의 유의미한 변화 대기를 수행합니다.
         참고: 위치 업데이트는 완전히 활성화된 가시적 문서에만 전달됩니다
      3. 다음으로 위치 획득(acquire a position)을 대기하며 successCallback, errorCallback, options, 및 watchId를 전달합니다.

위치 획득을 수행하려면, PositionCallback인 successCallback, PositionErrorCallback? errorCallback, PositionOptions인 options, 및 선택적 watchId를 전달합니다.

1. If watchId was passed and this's [[watchIDs]]가 포함(contain)하지 않는 watchId인 경우, 이 알고리즘을 종료합니다.
2. Let acquisitionTime be a new EpochTimeStamp 현재 시각을 나타내도록 합니다.
3. Let timeoutTime be the sum of acquisitionTime and options.timeout.
4. Let cachedPosition be this's [[cachedPosition]].
5. 구현 특유의 timeout 작업을 생성하여 timeoutTime에 만료되도록 하며, 그 기간 동안 장치의 위치를 획득하기 위해 다음 단계를 실행합니다:
   1. Let permission be 현재 권한 상태 가져오기(get the current permission state)로 "geolocation"의 상태를 얻습니다.
   2. If permission is "denied":
      1. timeout을 중지합니다.
      2. 사용자 또는 시스템 권한 거부 실패 처리 단계를 수행합니다.
   3. If permission is "granted":
      1. 에뮬레이션된 위치를 사용해야 하는지 다음 단계를 실행하여 확인합니다:
         1. Let emulatedPositionData be 에뮬레이션된 위치 데이터 가져오기(get emulated position data)를 실행하여 this를 전달합니다.
         2. If emulatedPositionData is not null:
            1. If emulatedPositionData is a GeolocationPositionError인 경우:
               1. 오류와 함께 콜백 호출하여 errorCallback 및 emulatedPositionData.code를 전달합니다.
               2. 이 알고리즘을 종료합니다.
            2. Let position be 새로운 GeolocationPosition를 생성하여 emulatedPositionData, acquisitionTime 및 options.enableHighAccuracy를 전달합니다.
            3. 작업을 대기열에 추가(Queue a task)하고, geolocation 작업 소스에서 호출(invokes)하여 successCallback를 « position » 및 "report"와 함께 호출합니다.
            4. 이 알고리즘을 종료합니다.
      2. position을 null로 둡니다.
      3. If cachedPosition is not null, and options.maximumAge가 0보다 큰 경우:
         1. Let cacheTime be acquisitionTime에서 options.maximumAge 값을 뺀 값으로 설정합니다.
         2. If cachedPosition's timestamp 값이 cacheTime보다 크고, cachedPosition의 [[isHighAccuracy]]가 options의 enableHighAccuracy와 동일하면:
            1. 작업을 대기열에 추가(Queue a task)하고, geolocation 작업 소스에서 호출(invokes)하여 successCallback를 « cachedPosition » 및 "report"와 함께 호출합니다.
            2. 이 알고리즘을 종료합니다.
      4. 그렇지 않고, position이 cachedPosition이 아닌 경우, 기본 시스템으로부터 위치 데이터를 획득하려 시도합니다. 이때 획득 중에 options의 값을 선택적으로 고려합니다(enableHighAccuracy).
      5. If the timeout elapses during acquisition, or acquiring the device's position results in failure:
         1. timeout을 중지합니다.
         2. 실패 처리(dealing with failures)로 이동합니다.
         3. 이 알고리즘을 종료합니다.
      6. 시스템에서 위치 데이터를 성공적으로 획득하면:
         1. Let positionData be a 맵(map)으로서 획득된 위치 데이터에 기반한 다음 이름/값 쌍을 포함합니다:

            "accuracy"

            95% 신뢰구간을 미터 단위로 나타내는 비음수 double 값입니다. 정확도는 측정된 좌표가 실제 위치에 얼마나 근접한지를 나타냅니다.

            "altitude"

            [WGS84] 타원체에 대한 해발 미터 단위의 고도를 나타내는 double? 또는 사용 불가 시 null입니다. 고도는 해수면 위의 높이를 측정합니다.

            "altitudeAccuracy"

            고도 정확도를 나타내는 비음수 double? 또는 사용 불가 시 null로, 미터 단위의 95% 신뢰구간을 나타냅니다. 고도 정확도는 측정된 고도가 실제 고도에 얼마나 근접한지를 측정합니다.

            "heading"

            장치가 이동하는 방향을 진북(true north)에 대한 각도로 나타내는 double? 또는 사용 불가하거나 장치가 정지해 있을 경우 null입니다. 헤딩은 장치가 이동하는 방향을 측정합니다.

            "latitude"

            [WGS84] 좌표계를 사용하여 지구 표면의 위도를 도 단위로 나타내는 double입니다. 위도는 적도로부터 어느 정도 북쪽 또는 남쪽인지 측정합니다.

            "longitude"

            [WGS84] 좌표계를 사용하여 지구 표면의 경도를 도 단위로 나타내는 double입니다. 경도는 본초 자오선으로부터 동서 방향으로 얼마나 떨어져 있는지 측정합니다.

            "speed"

            초당 미터 단위의 속도를 나타내는 비음수 double? 또는 사용 불가 시 null입니다. 속도는 장치가 얼마나 빠르게 이동하는지를 측정합니다.

         2. position을 새로운 GeolocationPosition으로 설정하며, positionData, acquisitionTime 및 options.enableHighAccuracy를 전달합니다.
         3. this의 [[cachedPosition]]를 position으로 설정합니다.
      7. timeout을 중지합니다.
      8. 작업을 대기열에 추가(Queue a task)하고, geolocation 작업 소스에서 호출(invokes)하여 successCallback를 « position » 및 "report"와 함께 호출합니다.

   실패 처리(Dealing with failures):

   • 위치 획득이 실패하면, 실패에 해당하는 조건에 따라 다음 중 하나를 수행합니다:

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

     오류와 함께 콜백 호출하여 errorCallback 및 PERMISSION_DENIED를 전달합니다.

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

     시간 초과(Timeout elapsed):

     오류와 함께 콜백 호출하여 errorCallback 및 TIMEOUT를 전달합니다.

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

     오류와 함께 콜백 호출하여 errorCallback 및 POSITION_UNAVAILABLE를 전달합니다.

오류와 함께 콜백 호출하라는 지시를 받았을 때, 주어진 PositionErrorCallback? callback 및 unsigned short인 code가 주어지면:

1. If callback is null, return.
2. Let error be 새로 생성된 GeolocationPositionError 인스턴스이며, 그 code 속성은 code로 초기화됩니다.
3. 작업을 대기열에 추가(Queue a task)하고, geolocation 작업 소스에서 다음 단계를 포함하는 작업을 대기열에 추가하여 호출(invokes)하여 callback을 « error » 및 "report"와 함께 호출합니다.

The enableHighAccuracy 멤버는 애플리케이션이 가능한 한 정확한 위치 데이터를 수신하기를 원한다는 힌트를 제공합니다. 이 멤버의 의도된 목적은 애플리케이션이 고정밀 지오로케이션(fixes)을 필요로 하지 않음을 구현부에 알릴 수 있게 하여, 구현부가 전력을 많이 소비하는 지오로케이션 제공자(예: GPS)를 사용하지 않도록 MAY 허용하는 것입니다.

The timeout 멤버는 위치를 획득하는 과정이 만료되기까지의 최대 시간을 밀리초 단위로 나타냅니다.

The maximumAge 멤버는 웹 애플리케이션이 캐시된 위치를 허용할 수 있음을 나타내며, 해당 위치의 연령(age)이 지정된 밀리초 시간보다 크지 않아야 합니다.

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

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

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

GeolocationPosition 인스턴스는 다음 표에 나열된 내부 슬롯과 함께 생성됩니다:

이 명세서에 의해 다음 task source가 정의됩니다.

The geolocation task source

이 명세서는 위치 요청을 수행할 때 비차단식의 PositionCallback 및 PositionErrorCallback을 대기열에 추가하는 데 이 task source를 사용합니다.

The latitude 및 longitude 속성은 위치를 도 단위의 실수로 지정하며, [WGS84] 좌표계를 사용합니다.

The accuracy 속성은 위치 정확도 반경을 미터 단위로 나타냅니다.

The altitude 속성은 위치의 높이를 나타내며, 이는 [WGS84] 타원체에 대한 해발 미터 단위로 지정됩니다.

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

The heading 속성은 호스팅 장치의 주행 방향을 나타내며, 단위는 도(degrees)이고 0° ≤ heading < 360° 범위에서 진북(true north)을 기준으로 시계 방향으로 측정됩니다.

The speed 속성은 호스팅 장치의 현재 속도의 수평 성분의 크기를 초당 미터(meters per second) 단위로 나타냅니다.

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

새로운 GeolocationPosition은 map positionData, EpochTimeStamp timestamp 및 불리언 isHighAccuracy로 구성되며, 다음 단계를 수행합니다:

1. Let coords be 새로 생성된 GeolocationCoordinates 인스턴스입니다.
2. For each key → value in positionData:
   1. coords의 이름이 key인 속성을 value로 설정합니다.
3. 새로 생성된 GeolocationPosition 인스턴스를 반환하며, 그 coords 속성은 coords로 초기화되고, timestamp 속성은 timestamp로 초기화되며, 내부 슬롯 [[isHighAccuracy]]는 isHighAccuracy로 설정됩니다.

PERMISSION_DENIED (숫자 값 1)

위치 요청이 실패한 이유는 사용자가 API 사용 권한을 거부했거나 요청이 비보안 컨텍스트에서 이루어졌기 때문입니다.

POSITION_UNAVAILABLE (숫자 값 2)

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

TIMEOUT (숫자 값 3)

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

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

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