getCurrentPosition method
Obtains the geographic position, in terms of latitude and longitude coordinates, of the device running Windows Internet Explorer.
.png){kind=icon} .png){kind=icon} |
Syntax
HRESULT retVal = object.getCurrentPosition(successCallback, errorCallback, options);
Parameters
successCallback [in]
Type: IDispatch
The handler 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 handler 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, set the errorCallback parameter to VT_NULL.
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 will be used instead of requiring that IWebGeolocation::getCurrentPositionobtain an updated location.
If maximumAge is zero (0), IWebGeolocation::getCurrentPosition will always try to obtain an updated position, even if a cached position is already available.
If maximumAge is Infinity, any cached position will be used regardless of its age, and IWebGeolocation::getCurrentPosition will only try to obtain an updated position if no cached position data exists. In this case, maximumAge is a VT_R8 value.
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
Windows Internet Explorer 9. This property is supported only for webpages displayed in IE9 Standards mode. For more information, see Defining Document Compatibility.
When the IWebGeolocation::getCurrentPosition function is called, it initiates a request to acquire the geographic position, and then returns immediately. If the geographic position is successfully obtained, the callback function defined in the successCallback parameter is called. Te position parameter of that function contains the data describing the current geographic location of the device running Internet Explorer.
If the geographic location cannot be obtained and a callback function is specified as the errorCallback parameter, that function is called. The error parameter of the errorCallback function contains an error code indicating the reason for failure.
Note The first time a web application calls the IWebGeolocation::getCurrentPosition function, Internet Explorer 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 Internet Explorer. There is no guarantee that changing the properties of these attributes will affect the results reported by the location provider.
See also
Reference