# GARSession(CloudAnchors)

Category adding Cloud Anchor functionality to `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session`.

## Summary

| ### Public methods ||
|---|---|
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#estimatefeaturemapqualityforhosting:error:` | `https://developers.google.com/ar/reference/ios/group/GARFeatureMapQuality#garfeaturemapquality` Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform. |
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#hostcloudanchor:ttldays:completionhandler:error:` | `nullable https://developers.google.com/ar/reference/ios/interface/GARHostCloudAnchorFuture#interface_g_a_r_host_cloud_anchor_future *` Uses the transform and other data from `anchor` to host a new Cloud Anchor. |
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#hostcloudanchor:ttldays:error:` | `nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *` This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor. |
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#hostcloudanchor:error:` | `nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *` Hosts a new Cloud Anchor based on an `ARAnchor`. |
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#resolvecloudanchorwithidentifier:completionhandler:error:` | `nullable https://developers.google.com/ar/reference/ios/interface/GARResolveCloudAnchorFuture#interface_g_a_r_resolve_cloud_anchor_future *` Attempts to resolve a Cloud Anchor using the provided `identifier`. |
| `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#resolvecloudanchorwithidentifier:error:` | `nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *` Resolves a Cloud Anchor with a given identifier. |

## Public methods

### estimateFeatureMapQualityForHosting:error:

```
- (https://developers.google.com/ar/reference/ios/group/GARFeatureMapQuality#garfeaturemapquality)estimateFeatureMapQualityForHosting:(simd_float4x4) transformerror:(NSError **) error
```
Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.

Cloud Anchors hosted using higher quality features will generally result in easier and more accurately resolved Cloud Anchor transforms.


Details Parameters `transform` The camera transform to use in estimating the quality. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodenottracking` - bad current `ARTrackingState`.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current cloud anchor mode is disabled.
**Returns** The estimated quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform. Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1a461f02d5d9f29e0c5449a39df0dfa767`.

### hostCloudAnchor:TTLDays:completionHandler:error:

```
- (nullable https://developers.google.com/ar/reference/ios/interface/GARHostCloudAnchorFuture#interface_g_a_r_host_cloud_anchor_future *)hostCloudAnchor:(ARAnchor *) anchorTTLDays:(NSInteger) TTLDayscompletionHandler:(void(^)(NSString *_Nullable cloudIdentifier, https://developers.google.com/ar/reference/ios/group/GARCloudAnchorState#garcloudanchorstate cloudState)) completionHandlererror:(NSError **) error
```
Uses the transform and other data from `anchor` to host a new Cloud Anchor.

A Cloud Anchor is assigned an identifier that can be used to create an `https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor` in the same position in subsequent sessions across devices using `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#resolvecloudanchorwithidentifier:completionhandler:error:`. See the [Cloud Anchors developer guide](https://developers.google.com/ar/develop/ios/cloud-anchors/developer-guide) for more information.

The duration that a Cloud Anchor can be resolved for is specified by `TTLDays`. When using [Token authorization](https://developers.google.com/ar/develop/ios/cloud-anchors/developer-guide#token-authorization), the maximum allowed value is 365 days. When using an [API Key](https://developers.google.com/ar/develop/ios/cloud-anchors/developer-guide#api-key-authorization) to authenticate with the ARCore API, the maximum allowed value is 1 day.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future` for information on obtaining results and cancelling the operation.

Cloud Anchors requires a `https://developers.google.com/ar/reference/ios/interface/GARSessionConfiguration#interface_g_a_r_session_configuration` with `https://developers.google.com/ar/reference/ios/group/GARCloudAnchorMode#garcloudanchormodeenabled` set on this session. Use `https://developers.google.com/ar/reference/ios/category/GARSessionConfiguration(CloudAnchors)#cloudanchormode` to set the Cloud Anchor API mode and `https://developers.google.com/ar/reference/ios/interface/GARSession#setconfiguration:error:` to configure the session.

Hosting a Cloud Anchor works best when ARCore is able to create a good feature map around the `ARAnchor`. Use `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#estimatefeaturemapqualityforhosting:error:` to determine the quality of visual features seen by ARCore in the preceding few seconds. Cloud Anchors hosted using higher quality features will generally result in quicker and more accurately resolved Cloud Anchor transforms.

ARCore can have up to 40 simultaneous Cloud Anchor operations, including resolved anchors and active hosting operations.


Details Parameters `anchor` The `ARAnchor` with the desired transform to be used to create a hosted Cloud Anchor. `TTLDays` The lifetime of the anchor in days. Must be positive. `completionHandler` The completion block to execute on the Main thread when the operation is complete, unless the operation is cancelled. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeinvalidargument` - invalid (`nil`) anchor or invalid TTL.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodenottracking` - bad current `ARTrackingState`.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcoderesourceexhausted` - tried to create too many Cloud Anchors.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current `GARCloudAnchorMode` is disabled.
**Returns** A handle to the async operation that can be [polled](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#polling-a-future) or [cancelled](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#cancelling-a-future). Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1ac95b92ad1325c601d58530ddedb1e7cd`.

### hostCloudAnchor:TTLDays:error:

```
- (nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *)hostCloudAnchor:(ARAnchor *) anchorTTLDays:(NSInteger) TTLDayserror:(NSError **) error
```
This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor.

The cloud state of the returned anchor will be set to `https://developers.google.com/ar/reference/ios/group/GARCloudAnchorState#garcloudanchorstatetaskinprogress` and the initial transform will be set to the transform of the provided anchor. However, the returned anchor is completely independent of the original anchor, and the two transforms might diverge over time.

Hosting requires an active session for which the tracking state is `ARTrackingStateNormal`, as well as a working internet connection. ARCore will continue to retry silently in the background if it is unable to establish a connection to the ARCore API service.


Details Parameters `anchor` The `ARAnchor` with the desired transform to be used to create a hosted Cloud Anchor. `TTLDays` The lifetime of the anchor in days. Must be positive. The maximum allowed value is 1 if using an API Key to authenticate with the ARCore API service, otherwise the maximum allowed value is 365. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeinvalidargument` - invalid (`nil`) anchor or invalid TTL.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodenottracking` - bad current `ARTrackingState`.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcoderesourceexhausted` - tried to create too many Cloud Anchors.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current cloud anchor mode is disabled.
**Returns** The new `https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor`, or `nil` if there is an error. Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1a398fd05cd3fe9948d6345fce4d2fb42d`.

### hostCloudAnchor:error:

```
- (nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *)hostCloudAnchor:(ARAnchor *) anchorerror:(NSError **) error
```
Hosts a new Cloud Anchor based on an `ARAnchor`.

The new anchor will have a cloud state of `https://developers.google.com/ar/reference/ios/group/GARCloudAnchorState#garcloudanchorstatetaskinprogress` and its initial transform will be set to that of the passed-in anchor. However, the two transforms may differ over time.


Details Parameters `anchor` The `ARAnchor` to host. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeinvalidargument` - invalid (`nil`) anchor.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodenottracking` - bad current `ARTrackingState`.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcoderesourceexhausted` - tried to create too many Cloud Anchors.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current cloud anchor mode is disabled.
**Returns** The new `https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor`, or `nil` if there is an error. Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1ad54c2dbe2f79fc0d24cd3dc85a46a510`.

### resolveCloudAnchorWithIdentifier:completionHandler:error:

```
- (nullable https://developers.google.com/ar/reference/ios/interface/GARResolveCloudAnchorFuture#interface_g_a_r_resolve_cloud_anchor_future *)resolveCloudAnchorWithIdentifier:(NSString *) identifiercompletionHandler:(void(^)(https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *_Nullable anchor, https://developers.google.com/ar/reference/ios/group/GARCloudAnchorState#garcloudanchorstate cloudState)) completionHandlererror:(NSError **) error
```
Attempts to resolve a Cloud Anchor using the provided `identifier`.

The Cloud Anchor must previously have been hosted by `https://developers.google.com/ar/reference/ios/category/GARSession(CloudAnchors)#hostcloudanchor:ttldays:completionhandler:error:` or another Cloud Anchor hosting method within the allotted `TTLDays`. See the [Cloud Anchors developer guide](https://developers.google.com/ar/develop/ios/cloud-anchors/developer-guide) for more information.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future` for information on obtaining results and cancelling the operation.

When resolving a Cloud Anchor, the ARCore API periodically compares visual features from the scene against the anchor's 3D feature map to pinpoint the user's position and orientation relative to the anchor. When it finds a match, the task completes.

Cloud Anchors requires a `https://developers.google.com/ar/reference/ios/interface/GARSessionConfiguration#interface_g_a_r_session_configuration` with `https://developers.google.com/ar/reference/ios/group/GARCloudAnchorMode#garcloudanchormodeenabled` set on this session. Use `https://developers.google.com/ar/reference/ios/category/GARSessionConfiguration(CloudAnchors)#cloudanchormode` to set the Cloud Anchor API mode and `https://developers.google.com/ar/reference/ios/interface/GARSession#setconfiguration:error:` to configure the session.

ARCore can have up to 40 simultaneous Cloud Anchor operations, including resolved anchors and active hosting operations.


Details Parameters `identifier` The Cloud Anchor identifier for the anchor. `completionHandler` [Completion handler](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#using-a-completion-handler-to-obtain-future-results) to be invoked on the Main thread, if not `nil`. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeinvalidargument` - invalid (`nil` or empty) identifier.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcoderesourceexhausted` - tried to create too many Cloud Anchors.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current `GARCloudAnchorMode` is disabled.
**Returns** A handle to the async operation that can be [polled](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#polling-a-future) or [cancelled](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#cancelling-a-future). Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1a1710748b3c6b9915d5c27c834c382fb9`.

### resolveCloudAnchorWithIdentifier:error:

```
- (nullable https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor *)resolveCloudAnchorWithIdentifier:(NSString *) identifiererror:(NSError **) error
```
Resolves a Cloud Anchor with a given identifier.

The new anchor is immediately added to the session and returned, but without a valid transform. You don't need to wait for a call to resolve a Cloud Anchor to complete before initiating another call. A session can be resolving up to 40 Cloud Anchors at a given time. If resolving fails, the anchor will be automatically removed from the session.


Details Parameters `identifier` The Cloud Anchor identifier for the anchor. `error` Out parameter for an `NSError`. Possible errors:

- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeinvalidargument` - invalid (`nil` or empty) identifier.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcoderesourceexhausted` - tried to create too many Cloud Anchors.
- `https://developers.google.com/ar/reference/ios/group/GARSessionErrorCode#garsessionerrorcodeillegalstate` - current cloud anchor mode is disabled.
**Returns** The new `https://developers.google.com/ar/reference/ios/interface/GARAnchor#interface_g_a_r_anchor`, or `nil` if there is an error. Extends class `https://developers.google.com/ar/reference/ios/interface/GARSession#interface_g_a_r_session_1a14cf03b41b679f3c06b8c2ac812cfcb3`.