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 PlatformFrame 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 GetConfiguration() 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 GetDiagnostics() const -> std::shared_ptr<Microsoft::Azure::SpatialAnchors::CloudSpatialAnchorSessionDiagnostics>;

LocationProvider

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

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

LogLevel

Logging level for the session log events.

auto GetLogLevel() const -> Microsoft::Azure::SpatialAnchors::SessionLogLevel;
auto SetLogLevel(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 GetSession() const -> ArSession*;
auto SetSession(ArSession* const& value) -> void;

SessionId

The unique identifier for the session.

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

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;