Class CloudSpatialAnchorSession

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

class Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSession final : public std::enable_shared_from_this<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSession>

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.

auto CreateAnchorAsync(std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> const& anchor, std::function<void(Status)> callback) -> void;

Parameters

Name	Type	Description
anchor	CloudSpatialAnchor	Anchor to be persisted.

• callback - A task that represents the asynchronous creation operation.

Returns

Type	Description
void	A task that represents the asynchronous creation operation.

CreateWatcher

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

auto CreateWatcher(std::shared_ptr<Microsoft::Azure::SpatialAnchors::AnchorLocateCriteria> const& criteria) -> std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher>;

Parameters

Name	Type	Description
criteria	AnchorLocateCriteria	Criteria for anchors to watch for.

Returns

Type	Description
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.

auto DeleteAnchorAsync(std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> const& anchor, std::function<void(Status)> callback) -> void;

Parameters

Name	Type	Description
anchor	CloudSpatialAnchor	The anchor to be deleted.

• callback - A task that represents the asynchronous delete operation.

Returns

Type	Description
void	A task that represents the asynchronous delete operation.

Dispose

Stops this session and releases all associated resources.

auto Dispose() -> void;

GetAccessTokenWithAccountKeyAsync

Gets the Azure Spatial Anchors access token from account key.

auto GetAccessTokenWithAccountKeyAsync(std::string const& accountKey, std::function<void(Status, std::string)> callback) -> void;

Parameters

Name	Type	Description
accountKey	string	Account key.

• callback - The access token string.

Returns

Type	Description
void	The access token string.

GetAccessTokenWithAuthenticationTokenAsync

Gets the Azure Spatial Anchors access token from authentication token.

auto GetAccessTokenWithAuthenticationTokenAsync(std::string const& authenticationToken, std::function<void(Status, std::string)> callback) -> void;

Parameters

Name	Type	Description
authenticationToken	string	Authentication token.

• callback - The access token string.

Returns

Type	Description
void	The access token string.

GetActiveWatchers

Gets a list of active watchers.

auto GetActiveWatchers() -> std::vector<std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorWatcher>>;

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<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.

auto GetAnchorPropertiesAsync(std::string const& identifier, std::function<void(Status, std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor>)> callback) -> void;

Parameters

Name	Type	Description
identifier	string	The identifier to look for.

• callback - A task that represents the asynchronous retrieval operation. The anchor retrieved will have property values but may not have a local anchor available.

Returns

Type	Description
void	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.

auto GetNearbyAnchorIdsAsync(std::shared_ptr<Microsoft::Azure::SpatialAnchors::NearDeviceCriteria> const& criteria, std::function<void(Status, std::shared_ptr<IVector<std::string>>)> callback) -> void;

Parameters

Name	Type	Description
criteria	NearDeviceCriteria	The search criteria.

• callback - A task that represents the asynchronous retrieval operation.

Returns

Type	Description
void	A task that represents the asynchronous retrieval operation.

GetSessionStatusAsync

Gets an object describing the status of the session.

auto GetSessionStatusAsync(std::function<void(Status, std::shared_ptr<Microsoft::Azure::SpatialAnchors::SessionStatus>)> callback) -> void;

Parameters

Name	Type	Description

• callback - A task that represents the session status retrieval.

Returns

Type	Description
void	A task that represents the session status retrieval.

ProcessFrame

Applications must call this method on platforms where per-frame processing is required.

This method is not available on the HoloLens platform.

auto ProcessFrame(ArFrame* const& frame) -> void;

Parameters

Name	Type	Description
frame	ArFrame	AR frame to process.

RefreshAnchorPropertiesAsync

Refreshes properties for the specified spatial anchor.

auto RefreshAnchorPropertiesAsync(std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> const& anchor, std::function<void(Status)> callback) -> void;

Parameters

Name	Type	Description
anchor	CloudSpatialAnchor	The anchor to refresh.

• callback - A task that represents the asynchronous refresh operation.

Returns

Type	Description
void	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.

auto Reset() -> void;

Start

Begins capturing environment data for the session.

auto Start() -> void;

Stop

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

auto Stop() -> void;

UpdateAnchorPropertiesAsync

Updates the specified spatial anchor.

auto UpdateAnchorPropertiesAsync(std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchor> const& anchor, std::function<void(Status)> callback) -> void;

Parameters

Name	Type	Description
anchor	CloudSpatialAnchor	The anchor to be updated.

• callback - A task that represents the asynchronous update operation.

Returns

Type	Description
void	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.

auto Configuration() const -> std::shared_ptr<Microsoft::Azure::SpatialAnchors::SessionConfiguration>;

Diagnostics

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

auto Diagnostics() const -> std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSessionDiagnostics>;

LocationProvider

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

auto LocationProvider() const -> std::shared_ptr<Microsoft::Azure::SpatialAnchors::PlatformLocationProvider>;
auto LocationProvider(std::shared_ptr<Microsoft::Azure::SpatialAnchors::PlatformLocationProvider> const& value) -> void;

LogLevel

Logging level for the session log events.

auto LogLevel() const -> Microsoft::Azure::SpatialAnchors::SessionLogLevel;
auto LogLevel(Microsoft::Azure::SpatialAnchors::SessionLogLevel value) -> void;

Session

The tracking session used to help locate anchors.

This property is not available on the HoloLens platform.

auto Session() const -> ArSession*;
auto Session(ArSession* const& value) -> void;

SessionId

The unique identifier for the session.

auto SessionId() const -> std::string;

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.

auto TelemetryEnabled() const -> bool;
auto TelemetryEnabled(bool value) -> void;

Events

AnchorLocated

Occurs when an anchor's location is determined.

auto AnchorLocated(AnchorLocatedDelegate const& handler) -> event_token;
auto AnchorLocated(event_token& token) -> void;

Error

Occurs when the session is unable to continue processing.

auto Error(SessionErrorDelegate const& handler) -> event_token;
auto Error(event_token& token) -> void;

LocateAnchorsCompleted

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

auto LocateAnchorsCompleted(LocateAnchorsCompletedDelegate const& handler) -> event_token;
auto LocateAnchorsCompleted(event_token& token) -> void;

OnLogDebug

Occurs when a debug log message is generated.

auto OnLogDebug(OnLogDebugDelegate const& handler) -> event_token;
auto OnLogDebug(event_token& token) -> void;

SessionUpdated

Occurs when all the session state is updated.

auto SessionUpdated(SessionUpdatedDelegate const& handler) -> event_token;
auto SessionUpdated(event_token& token) -> void;

TokenRequired

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

auto TokenRequired(TokenRequiredDelegate const& handler) -> event_token;
auto TokenRequired(event_token& token) -> void;

UpdatedSensorFingerprintRequired

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

auto UpdatedSensorFingerprintRequired(UpdatedSensorFingerprintRequiredDelegate const& handler) -> event_token;
auto UpdatedSensorFingerprintRequired(event_token& token) -> void;