Class CloudSpatialAnchorSession

Declaration

struct winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSession

Description

Use this class to create, locate and manage spatial anchors.

Methods

CreateAnchorAsync

Creates a new persisted spatial anchor from the specified local anchor and string properties.

The local anchor passed into this method must have a valid transform. Note some platforms supported by Azure Spatial Anchors such as iOS allow transforms with scale component != 1.0. Azure Spatial Anchors SDK does not support such transforms and it will fail to create the spatial anchor with error code InvalidAnchorTransformRigidity. Any scale handling for anchors must be done at the app level.

Windows::Foundation::IAsyncAction CreateAnchorAsync(winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor const& anchor);

Parameters

  • anchor - Anchor to be persisted.

Returns

  • Windows::Foundation::IAsyncAction - A task that represents the asynchronous creation operation.

CreateWatcher

Creates a new object that watches for anchors that meet the specified criteria.

winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher CreateWatcher(winrt::Microsoft::Azure::SpatialAnchors::AnchorLocateCriteria const& criteria);

Parameters

  • criteria - Criteria for anchors to watch for.

Returns

  • winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher - A new watcher object that continuously looks for anchors until the criteria is fully satisfied or the watcher is stopped. There can only be one active watcher at a time.

DeleteAnchorAsync

Deletes a persisted spatial anchor.

Windows::Foundation::IAsyncAction DeleteAnchorAsync(winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor const& anchor);

Parameters

  • anchor - The anchor to be deleted.

Returns

  • Windows::Foundation::IAsyncAction - A task that represents the asynchronous delete operation.

Dispose

Stops this session and releases all associated resources.

void Dispose();

GetAccessTokenWithAccountKeyAsync

Gets the Azure Spatial Anchors access token from account key.

Windows::Foundation::IAsyncOperation<hstring> GetAccessTokenWithAccountKeyAsync(hstring const& accountKey);

Parameters

  • accountKey - Account key.

Returns

  • Windows::Foundation::IAsyncOperation<hstring> - The access token string.

GetAccessTokenWithAuthenticationTokenAsync

Gets the Azure Spatial Anchors access token from authentication token.

Windows::Foundation::IAsyncOperation<hstring> GetAccessTokenWithAuthenticationTokenAsync(hstring const& authenticationToken);

Parameters

  • authenticationToken - Authentication token.

Returns

  • Windows::Foundation::IAsyncOperation<hstring> - The access token string.

GetActiveWatchers

Gets a list of active watchers.

Windows::Foundation::Collections::IVectorView<winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher> GetActiveWatchers();

Returns

  • Windows::Foundation::Collections::IVectorView<winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher> - A list of active watchers.

GetAnchorPropertiesAsync

Gets a cloud spatial anchor for the given identifier, even if it hasn't been located yet.

Windows::Foundation::IAsyncOperation<winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> GetAnchorPropertiesAsync(hstring const& identifier);

Parameters

  • identifier - The identifier to look for.

Returns

  • Windows::Foundation::IAsyncOperation<winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> - A task that represents the asynchronous retrieval operation. The anchor retrieved will have property values but may not have a local anchor available.

GetNearbyAnchorIdsAsync

Gets a list of all nearby cloud spatial anchor ids corresponding to a given criteria.

Windows::Foundation::IAsyncOperation<Windows::Foundation::Collections::IVector<hstring>> GetNearbyAnchorIdsAsync(winrt::Microsoft::Azure::SpatialAnchors::NearDeviceCriteria const& criteria);

Parameters

  • criteria - The search criteria.

Returns

  • Windows::Foundation::IAsyncOperation<Windows::Foundation::Collections::IVector<hstring>> - A task that represents the asynchronous retrieval operation.

GetSessionStatusAsync

Gets an object describing the status of the session.

Windows::Foundation::IAsyncOperation<winrt::Microsoft::Azure::SpatialAnchors::SessionStatus> GetSessionStatusAsync();

Parameters

Returns

  • Windows::Foundation::IAsyncOperation<winrt::Microsoft::Azure::SpatialAnchors::SessionStatus> - A task that represents the session status retrieval.

RefreshAnchorPropertiesAsync

Refreshes properties for the specified spatial anchor.

Windows::Foundation::IAsyncAction RefreshAnchorPropertiesAsync(winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor const& anchor);

Parameters

  • anchor - The anchor to refresh.

Returns

  • Windows::Foundation::IAsyncAction - A task that represents the asynchronous refresh operation.

Reset

Resets environment data that has been captured in this session; applications must call this method when tracking is lost.

On any platform, calling the method will clean all internal cached state.

void Reset();

Start

Begins capturing environment data for the session.

void Start();

Stop

Stops capturing environment data for the session and cancels any outstanding locate operations. Environment data is maintained.

void Stop();

UpdateAnchorPropertiesAsync

Updates the specified spatial anchor.

Windows::Foundation::IAsyncAction UpdateAnchorPropertiesAsync(winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor const& anchor);

Parameters

  • anchor - The anchor to be updated.

Returns

  • Windows::Foundation::IAsyncAction - A task that represents the asynchronous update operation.

Properties

Configuration

The configuration information for the session. Configuration settings take effect when the session is started.

winrt::Microsoft::Azure::SpatialAnchors::SessionConfiguration Configuration();

Diagnostics

The diagnostics settings for the session, which can be used to collect and submit data for troubleshooting and improvements.

winrt::Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSessionDiagnostics Diagnostics();

LocationProvider

Location provider used to create and locate anchors using Coarse Relocalization.

winrt::Microsoft::Azure::SpatialAnchors::PlatformLocationProvider LocationProvider();
void LocationProvider(winrt::Microsoft::Azure::SpatialAnchors::PlatformLocationProvider const& value);

LogLevel

Logging level for the session log events.

winrt::Microsoft::Azure::SpatialAnchors::SessionLogLevel LogLevel();
void LogLevel(winrt::Microsoft::Azure::SpatialAnchors::SessionLogLevel const& value);

SessionId

The unique identifier for the session.

hstring SessionId();

TelemetryEnabled

This API can be used to enable or disable Azure Spatial Anchors SDK telemetry. ASA SDK telemetry is enabled by default. If disabled, ASA SDK will not log any telemetry event for this session. Applications that need to disable ASA SDK telemetry completely can use this API before calling CloudSpatialAnchorSession::Start, which would result in no telemetry event being sent for that CloudSpatialAnchorSession instance.

bool TelemetryEnabled();
void TelemetryEnabled(bool const& value);

Events

AnchorLocated

Occurs when an anchor's location is determined.

event_token AnchorLocated(winrt::Microsoft::Azure::SpatialAnchors::AnchorLocatedDelegate const& handler);
void AnchorLocated(event_token const& token);

Error

Occurs when the session is unable to continue processing.

event_token Error(winrt::Microsoft::Azure::SpatialAnchors::SessionErrorDelegate const& handler);
void Error(event_token const& token);

LocateAnchorsCompleted

Occurs when all the results from a watcher that is locating anchors are processed.

event_token LocateAnchorsCompleted(winrt::Microsoft::Azure::SpatialAnchors::LocateAnchorsCompletedDelegate const& handler);
void LocateAnchorsCompleted(event_token const& token);

OnLogDebug

Occurs when a debug log message is generated.

event_token OnLogDebug(winrt::Microsoft::Azure::SpatialAnchors::OnLogDebugDelegate const& handler);
void OnLogDebug(event_token const& token);

SessionUpdated

Occurs when all the session state is updated.

event_token SessionUpdated(winrt::Microsoft::Azure::SpatialAnchors::SessionUpdatedDelegate const& handler);
void SessionUpdated(event_token const& token);

TokenRequired

Occurs when the session requires an updated access token or authentication token.

event_token TokenRequired(winrt::Microsoft::Azure::SpatialAnchors::TokenRequiredDelegate const& handler);
void TokenRequired(event_token const& token);

UpdatedSensorFingerprintRequired

Occurs when the session requests an updated sensor fingerprint from the application.

event_token UpdatedSensorFingerprintRequired(winrt::Microsoft::Azure::SpatialAnchors::UpdatedSensorFingerprintRequiredDelegate const& handler);
void UpdatedSensorFingerprintRequired(event_token const& token);