ジオロケーションAPI

Geolocationのインスタンスは、下記表の内部スロットを用いて作成されます。

getCurrentPosition(successCallback、errorCallback、 options)メソッドのステップは次の通りです。

1. 現在の設定オブジェクトの関連するグローバル・オブジェクトの関連付けられたDocumentが完全にアクティブでなければ、
   1. errorCallbackとPOSITION_UNAVAILABLEのエラーでコールバックします。
   2. このアルゴリズムを終了します。
2. 並行して、successCallback、errorCallback、optionsを渡して位置のリクエストを行います。

watchPosition(successCallback、errorCallback、options)メソッドのステップは次の通りです。

1. 現在の設定オブジェクトの関連するグローバル・オブジェクトの関連付けられたDocumentが完全にアクティブでなければ、
   1. errorCallbackとPOSITION_UNAVAILABLEを渡してエラーでコールバックします。
   2. 0を返します。
2. watchIdを0より大きい実装に依存したunsigned longとします。
3. watchIdをこれの[[watchIDs]]に追加します。
4. 並行して、successCallback、errorCallback、options、watchIdを渡して位置のリクエストを行います。
5. watchIdを返します。

clearWatch()が呼び出された場合、ユーザ・エージェントは、次のことを行わなければなりません(MUST)。

1. watchIdをこれの[[watchIDs]]から削除します。

位置のリクエストを行うには、PositionCallback successCallback、PositionErrorCallback? errorCallback、PositionOptions options、オプションのwatchIdを渡します。

1. watchIDsをこれの[[watchIDs]]とします。
2. documentを、現在の設定オブジェクトの関連するグローバル・オブジェクトの関連付けられたDocumentとします。
3. documentが「geolocation」機能の使用を許可されていなければ、
   1. watchIdが渡された場合、watchIdをwatchIDsから削除します。
   2. errorCallbackとPERMISSION_DENIEDを渡してエラーでコールバックします。
   3. このアルゴリズムを終了します。
4. documentの可視性の状態が「hidden」(不可視)であれば、下記のページの可視性変更ステップの実行を待ちます。
   1. 言明: documentの可視性状態は「visible」(可視)である。
   2. 下記の次のステップに進みます。
5. descriptorを、name が"geolocation"である新しいPermissionDescriptorとします。
6. permissionを設定してdescriptorの使用許可をリクエストします。
7. permissionが「denied」(拒否)であれば、
   1. watchIdが渡された場合、watchIdをwatchIDsから削除します。
   2. errorCallbackとPERMISSION_DENIEDを渡してエラーでコールバックします。
   3. このアルゴリズムを終了します。
8. successCallback、errorCallback、options、watchIdを渡して位置の取得を待ちます。
9. watchIdが渡されなければ、このアルゴリズムを終了します。
10. watchIDsにwatchIdが含まれている間に、
    1. 地理的な位置の大きな変化を待ちます。何をもって地理的な位置の大きな変化とするかは、実装に委ねられます。ユーザ・エージ���ントは、位置の変化が報告される頻度に制限を課すことができます(MAY)。
    2. documentが完全にアクティブでない、または可視性の状態が「visible」(可視)でない場合は、 前のステップに戻り、再び地理的な位置の大きな変化を待ちます。
       注: 位置の更新は、完全にアクティブな可視ドキュメントに対してのみ行われる。
    3. successCallback、errorCallback、options、watchIdを渡して位置の取得を待ちます。

位置の取得を行うには、PositionCallback successCallback、PositionErrorCallback? errorCallback、PositionOptions options、オプションのwatchIdを渡します。

1. watchIdが渡され、これの[[watchIDs]]にwatchIdが含まれていなければ、このアルゴリズムを終了します。
2. acquisitionTimeを、現在を表す新しいEpochTimeStampとします。
3. timeoutTimeをacquisitionTimeとoptions.timeoutの和とします。
4. cachedPositionをこれの[[cachedPosition]]とします。
5. timeoutTimeで時間が経過する実装固有のtimeoutタスクを作成し、その間に次のステップを実行してデバイスの位置の取得を試みます。
   1. permissionを"geolocation"の現在の許可状態を取得するとします。
   2. permissionが「denied」(拒否)であれば、
      1. timeoutを停止します。
      2. ユーザまたはシステムによる許可の拒否に失敗したケースのステップを行います。
   3. permissionが「granted」(許可)であれば、
      1. positionをヌル(null)とします。
      2. cachedPositionがヌル(null)でなく、options.maximumAgeが0よりも大きければ、
         1. cacheTimeをacquisitionTimeからoptions.maximumAgeメンバーの値を引いた値とします。
         2. cachedPositionのtimestampの値がcacheTimeより大きく、かつccachedPosition.[[isHighAccuracy]]がoptions.enableHighAccuracyと等しければ、positionをcachedPositionに設定します。
      3. そうでない場合、positionがcachedPositionでなければ、オプションとして取得中にoptions.enableHighAccuracyの値を考慮して、基盤となるシステムからの位置データの取得を試みます。
      4. 取得中にtimeoutの時間が経過した場合、またはデバイスの位置の取得に失敗した場合は、
         1. timeoutを停止します。
         2. 失敗の処理に進みます。
         3. このアルゴリズムを終了します。
      5. システムからの位置データ取得に成功した場合は、
         1. acquisitionTimeとoptions.enableHighAccuracyを渡して、positionを新しいGeolocationPositionに設定します。
         2. これの[[cachedPosition]]をpositionに設定します。
      6. timeoutを停止します。
      7. successCallbackをpositionで呼び出すステップを用いて、ジオロケーション・タスク源でタスクをキューに入れます。

   失敗の処理:

   • 位置の取得に失敗した場合、失敗と一致する条件に基づき、次のいずれかを行います。

     ユーザまたはシステムによる許可の拒否:

     errorCallbackとPERMISSION_DENIEDを渡してエラーでコールバックします。

     注: ブラウザの許可とOSの許可

     タイムアウトの発生:

     errorCallbackとTIMEOUTを用いてエラーでコールバックします。

     データ取得エラーまたはその他の理由:

     errorCallbackとPOSITION_UNAVAILABLEを渡してエラーでコールバックします。

エラーでコールバックするように指示された場合、PositionErrorCallback? callbackとunsigned short codeを仮定すると、

1. callbackがヌル(null)の場合、戻ります。
2. errorを、code属性がcodeに初期化された、新しく作成されたGeolocationPositionErrorインスタンスとします。
3. callbackをerrorで呼び出すステップを用いて、ジオロケーション・タスク源でタスクをキューに入れます。

enableHighAccuracyメンバーは、アプリケーションが最も正確な位置データの受信を望んでいることを示すヒントを提供します。このメンバーの目的は、アプリケーションが高精度なジオロケーションのfix解を求めないことを実装に通知できるようにすることです。したがって、実装では、大量の電力を消費するジオロケーション・プロバイダー(例えば、GPS)を避けることができます(MAY)。

timeoutメンバーは、位置の取得が期限切れになるまでの最長時間をミリ秒単位で示します。

maximumAgeメンバーは、ウェブ・アプリケーションが、経過時間がミリ秒単位で指定時間以下である、キャッシュされた位置を受け入れることを示します。

coords属性には、地理的な座標が含まれます。

timestamp属性は、デバイスの地理的な位置を取得した時刻を表します。

GeolocationPositionErrorのインスタンスは、次の表の内部スロットを用いて生成されます。

この仕様では、次のタスク源を定義しています。

ジオロケーション・タスク源

この仕様では、位置のリクエストを行う際に、ノンブロッキングのPositionCallbackとPositionErrorCallbackをキューに入れるために用います。

latitudeとlongitudeの属性は、10進数の度数で指定される地理的な座標です。

accuracy属性は、緯度と経度の座標の精度レベルをメートルで表します(例えば、65メートル)。

altitude属性は、位置の高さを示し、[WGS84]楕円体からの高さをメートルで指定します。

altitudeAccuracy属性は、高度の精度をメートルで表します(例えば、10メートル)。

heading属性は、ホスティング・デバイスの移動方向を表し、真北に対して時計回りに、0° ≤ 方向 < 360°の範囲で、度数で指定します。

speed属性は、ホスティング・デバイスの現在の速度の水平成分の大きさをメートル毎秒で表します。

新しいGeolocationPositionは、EpochTimeStamp timestampとブールのisHighAccuracyを用いて、次のステップを実行することで構築されます。

1. coordsを新しく作成されたGeolocationCoordinatesのインスタンスとします。
   1. coordのlatitude属性を10進数の度数で地理座標に初期化します。
   2. coordのlongitude属性を10進数の度数で地理座標に初期化します。
   3. coordのaccuracy属性を負でない実数に初期化します。この値は、経度と緯度の値に対して95%の信頼度に対応しているべきです(SHOULD)。
   4. coordのaltitude属性を[WGS84]楕円体からの高度で初期化するか、実装が高度の情報を提供できない場合はヌル(null)にします。
   5. coordのaltitudeAccuracy属性を負でない実数で初期化するか、実装が高度の情報を提供できない場合はヌル(null)にします。高度の精度情報が提供される場合は、95%の信頼度に対応しているべきです(SHOULD)。
   6. coordのspeed属性を負でない実数で初期化するか、実装が速度の情報を提供できない場合はヌル(null)にします。
   7. coordのheading属性を度数で初期化するか、実装が方向の情報を提供できない場合はヌル(null)にします。ホスティング・デバイスが静止している場合は(つまり、speed属性の値が0)、headingをNaNに初期化します。
2. coords属性をcoordsに、timestamp属性をtimestampに初期化し、その[[isHighAccuracy]]内部スロットをisHighAccuracyに設定して新しく作成されたGeolocationPositionインスタンスを返します。

PERMISSION_DENIED (数値1)

ユーザがAPIの使用許可を拒否したため、位置のリクエストに失敗した。

POSITION_UNAVAILABLE (数値2)

位置の取得に失敗した。

TIMEOUT (数値3)

ユーザ・エージェントが位置の取得に成功する前にtimeoutメンバーで指定された時間が経過した。

code属性は、初期化された値を返します(取り得る値については、10.1 定数を参照)。

message属性は、code属性を開発者が使いやすいようにテキストで記述したものです。