Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

watchPosition method

Begins listening for updates to the current geographical location of the device running the client.

Geolocation API Specification, Section 5.1Internet Explorer 9

Syntax

var watchId = geolocation.watchPosition(successCallback, errorCallback, options);

Parameters

successCallback [in]

Type: Object

The function to call when geographic position is successfully obtained. The function specified by the successCallback parameter takes one position parameter.

errorCallback [in, optional]

Type: Object

The function to call when the attempt to obtain geographic position fails. The function specified by the errorCallback parameter takes one positionError parameter. To use the options parameter without using the errorCallback parameter, specify a null value for the errorCallback parameter.

options [in, optional]

Type: Object

An object literal that uses JSON encoding to specify one or more of the following attributes and desired values.

enableHighAccuracy

Specify true to obtain the most accurate position possible, or false to optimize in favor of performance and power consumption.

timeout

An Integer value that indicates the time, in milliseconds, allowed for obtaining the position.

If timeout is Infinity, (the default value) the location request will not time out.

If timeout is zero (0) or negative, the results depend on the behavior of the location provider.

maximumAge

An Integer value indicating the maximum age, in milliseconds, of cached position information.

If maximumAge is non-zero, and a cached position that is no older than maximumAge is available, the cached position is used instead of obtaining an updated location.

If maximumAge is zero (0), watchPositionalways tries to obtain an updated position, even if a cached position is already available.

If maximumAge is Infinity, any cached position is used, regardless of its age, and watchPositiononly tries to obtain an updated position if no cached position data exists.

watchId [out, retval]

Type: Integer

An identifier representing the watch operation. This value is passed to the clearWatch function in order to stop listening for location updates.

Return value

Type: Integer

An identifier representing the watch operation. This value is passed to the clearWatch function in order to stop listening for location updates.

Standards information

Remarks

The function begins acquiring the geographic position and returns immediately. When the position is successfully obtained, the callback function provided in the successCallback parameter is called. The parameter to the successCallback function is a position object that contains the data on the current geographic location.

If the attempt to obtain the user's location fails, the callback function that can be provided as an optional second parameter is called. The error parameter to the errorCallback function is a positionError object that contains an error code indicating the reason for failure.

Note  The first time a document calls the watchPosition function, the client requests permission to access the geographic location of the browser, unless the user has previously chosen to always allow or always deny permission for the website to determine location. If the user denies permission, the function declared by the errorCallback is called and the code attribute of the error parameter of that function is set to PositionError.PERMISSION_DENIED.

Support for the attributes of the options parameter depends on the location provider available to the device running the client. There is no guarantee that changing the properties of these attributes will affect the results reported by the location provider.

Windows Internet Explorer 9. This property is supported only for webpages displayed in IE9 Standards mode. For more information, please see Defining Document Compatibility.

Examples

In the following example, when the user clicks the "Watch Latitude and Longitude" button, the listenForPosition function is called, which checks that the geolocation object is available before it calls the watchPosition method to start listening for location updates. When an update occurs, the success callback function updates the text boxes in the page by using the new latitude and longitude coordinates. The user clicks the "Clear Watch" button to stop listening for updates.


<!DOCTYPE html>  
<html>
<head>
<title>Location Test with Buttons</title>
<meta http-equiv="X-UA-Compatible" content="IE=9" />
<script type="text/javascript">
function setText(val, e) {
    document.getElementById(e).value = val;
}
function insertText(val, e) {
    document.getElementById(e).value += val;
}
var nav = null; 
var watchID;
function listenForPosition() {
  if (nav == null) {
      nav = window.navigator;
  }
  if (nav != null) {
      var geoloc = nav.geolocation;
      if (geoloc != null) {
          watchID = geoloc.watchPosition(successCallback, errorCallback);
      }
      else {
          console.log("Geolocation not supported");
      }
  }
  else {
      console.log("Navigator not found");
  }
}
function clearWatch(watchID) {
    window.navigator.geolocation.clearWatch(watchID);
}
function successCallback(position)
{
   setText(position.coords.latitude, "latitude");
   setText(position.coords.longitude, "longitude");
}
 
function errorCallback(error) {
    var message = "";   
    // Check for known errors
    switch (error.code) {
        case error.PERMISSION_DENIED:
            message = "This website does not have permission to use " + 
                      "the Geolocation API";
            break;
        case error.POSITION_UNAVAILABLE:
            message = "The current position could not be determined.";
            break;
        case error.PERMISSION_DENIED_TIMEOUT:
            message = "The current position could not be determined " + 
                      "within the specified timeout period.";            
            break;
    }
    // If it's an unknown error, build a message that includes 
    // information that helps identify the situation so that 
    // the error handler can be updated.
    if (message == "")
    {
        var strErrorCode = error.code.toString();
        message = "The position could not be determined due to " + 
                  "an unknown error (Code: " + strErrorCode + ").";
    }
    console.log(message);
}
</script>
</head>
<body>
<label for="latitude">Latitude: </label><input id="latitude" /> <br />
<label for="longitude">Longitude: </label><input id="longitude" /> <br />
<input type="button" onclick="listenForPosition ()" value="Watch Latitude and Longitude"  /> 
<input type="button" value="Clear watch" onclick="clearWatch()" />
</body>
</html>

See also

Reference
IWebGeolocation
geolocation
clearWatch

 

 

Show:
© 2014 Microsoft. All rights reserved.