Begins listening for updates to the current geographical location of the device running the client.
HRESULT watchPosition( IDispatch *successCallback, IDispatch *errorCallback, IDispatch *options, long *watchId );
- [in] The function to call when geographic position is successfully obtained. The function specified by the successCallback parameter takes one position parameter.
- [in] 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.
- [in] 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.
A VT_I4 value that indicates the time, in milliseconds, allowed for obtaining the position.
timeoutis Infinity, (the default value) the location request will not time out. In this case,
maximumAgeis a VT_R8 value.
timeoutis zero (
0) or negative, the results depend on the behavior of the location provider.
For finite values, a VT_I4 value indicating the maximum age, in milliseconds, of cached position information.
maximumAgeis non-zero, and a cached position that is no older than
maximumAgeis available, the cached position is used instead of obtaining an updated location.
maximumAgeis zero (
0), IWebGeolocation::watchPositionalways tries to obtain an updated position, even if a cached position is already available.
maximumAgeis 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,
maximumAgeis a VT_R8 value.
- [out, retval] An identifier representing the watch operation. This value is passed to the IWebGeolocation::clearWatch function in order to stop listening for location updates.
Returns S_OK if successful, or an error value otherwise.
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.
Internet Explorer 9. This property is supported only for webpages displayed in IE9 Standards mode. For more information, please see Defining Document Compatibility.