watchPosition method

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

 

Syntax

HRESULT retVal = object.watchPosition(successCallback, errorCallback, options, watchId);

Parameters

successCallback [in]

Type: IDispatch

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: IDispatch

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 VT_NULL value for the errorCallback parameter.

options [in, optional]

Type: IDispatch

A pointer to an object that implements IDispatchEx and contains one or more properties whose names correspond to one of the following supported attributes. Each property must specify a VARIANT value corresponding to the desired value.

enableHighAccuracy

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

timeout

A VT_I4 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. In this case, maximumAge is a VT_R8 value.

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

maximumAge

For finite values, a VT_I4 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), IWebGeolocation::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 IWebGeolocation::watchPositiononly tries to obtain an updated position if no cached position data exists. In this case, maximumAge is a VT_R8 value.

watchId [out, retval]

Type: long

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

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Standards information

• Geolocation API Specification, Section 5.1

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 IWebGeolocation::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 IWebGeolocation::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

IWebGeolocation::clearWatch