GeolocationProvider Class

Definition

Namespace:

Windows.Devices.Geolocation.Provider

Provides the ability to override the user's location from a remote source.

Note

To call location-override APIs, an app must declare the runFullTrust restricted capability.

Important

The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

public ref class GeolocationProvider sealed

/// [Windows.Foundation.Metadata.Activatable(983040, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 983040)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class GeolocationProvider final

[Windows.Foundation.Metadata.Activatable(983040, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 983040)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class GeolocationProvider

function GeolocationProvider()

Public NotInheritable Class GeolocationProvider

Inheritance

Object Platform::Object IInspectable GeolocationProvider

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 11 Insider Preview (introduced in 10.0.23504.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v15.0)
App capabilities	runFullTrust

Examples

The scenario in this code example involves a server-side app for a remote access client using these APIs to override the location of the machine. In the scenario, client apps run on diverse operating systems (OSes) (such as Windows, MacOS, iOS, or Linux), and post positions periodically (by calling these APIs) to a component that acts as a proxy on the host machine.

using Windows.Devices.Geolocation;
using Windows.Devices.Geolocation.Provider;

...

public class OverrideLocation
{
    public struct ClientPositionInfo
    {
        public BasicGeoposition geoposition;
        public PositionSource positionSource;
        public double accuracy;
    };

    private GeolocationProvider geolocationProvide = null;

    // When remote desktop connection is established,
    // call this API to initialize.
    public void Initialize()
    {
        geolocationProvider = new GeolocationProvider();
        geolocationProvider.IsOverriddenChanged +=
            new EventHandler<object>(OnIsOverriddenChanged);
    }

    // Uninitialize when remote desktop connection is stopped.
    public void DeInitialize()
    {
        geolocationProvider.IsOverriddenChanged -= OnIsOverriddenChanged;
        geolocationProvide.ClearOverridePosition();
    }

    private void OnIsOverriddenChanged(object sender, object args)
    {
        if (!geolocationProvider.IsOverridden)
        {
            SetPosition();
        }
    }

    // When remote desktop connection established,
    // call this API to set override position.
    public bool SetPosition()
    {
        // Get client location information from client side.
        ClientPositionInfo clientPositionInfo = GetClientLocationInformation();

        LocationOverrideStatus status = geolocationProvider.SetOverridePosition(
            clientPositionInfo.geoposition,
            clientPositionInfo.positionSource,
            clientPositionInfo.accuracy);

        if (status == LocationOverrideStatus.AlreadyStarted)
        {
            // Failed to get override session.
            return false;
        }
        else if (status == LocationOverrideStatus.AccessDenied)
        {
            // Do not have access to override.
            return false;
        }
        else if (status == LocationOverrideStatus.Other)
        {
            // something else caused the failure.
            return false;
        }
        return true;

    }
    public bool UpdatePosition()
    {
        // Update position.
        return SetPosition();
    }
}

Remarks

You should access a GeolocationProvider object from the context of the user for whom location is to be overridden and provided to location-aware apps. The length of a location override session is bound by calls to SetOverridePosition and ClearOverridePosition. Once a session starts successfully, other entities can't obtain override functionality until the original object is cleared.

Constructors

GeolocationProvider()

Constructs a new instance of GeolocationProvider. Note To call location-override APIs, an app must declare the runFullTrust restricted capability. Important The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

Properties

IsOverridden

Gets a value indicating whether the owning GeolocationProvider is currently overridden or not. You can access this property's value in your handler for the GeolocationProvider.IsOverriddenChanged event. Note To call location-override APIs, an app must declare the runFullTrust restricted capability. Important The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

Methods

ClearOverridePosition()

Clears (or resets) an override position that was set previously by a call to GeolocationProvider.SetOverridePosition. Note To call location-override APIs, an app must declare the runFullTrust restricted capability. Important The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

SetOverridePosition(BasicGeoposition, PositionSource, Double)

Sets an override position for the user's location. You can clear the override position by calling GeolocationProvider.ClearOverridePosition Note To call location-override APIs, an app must declare the runFullTrust restricted capability. Important The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

Events

IsOverriddenChanged

An event that's raised when the value of the GeolocationProvider.IsOverridden property changes. You can register to handle this event, and access the current value of GeolocationProvider.IsOverridden in response. Note To call location-override APIs, an app must declare the runFullTrust restricted capability. Important The Windows.Devices.Geolocation.Provider APIs are part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.