# BackupDeviceActionResult

Artifact: [androidx.test.backup:backup](https://developer.android.com/jetpack/androidx/releases/test-backup) [View Source](https://cs.android.com/search?q=file:androidx/test/backup/BackupDeviceAction.kt+class:androidx.test.backup.BackupDeviceActionResult) Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

*** ** * ** ***


```
class BackupDeviceActionResult
```

<br />

*** ** * ** ***

Results returned from a `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` back to the host orchestrator.

`https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys` documents every key the actions bundled with this library produce. Actions built with `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#success(kotlin.collections.Map)` and `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)` always report `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()`, and report `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()` only alongside a failure. Additional keys may be returned to carry data back to the host, which forwards the whole payload to the caller.

## Summary

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)(errorMessage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, payload: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>)` Returns a result reporting `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionValues#STATUS_FAILURE()` together with `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult.Companion#failure(kotlin.String,kotlin.collections.Map)`. |
| `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#success(kotlin.collections.Map)(payload: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>)` Returns a result reporting `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionValues#STATUS_SUCCESS()`. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#BackupDeviceActionResult(kotlin.collections.Map)(payload: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>)` |

| ### Public functions |
|---|---|
| `open operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#equals(kotlin.Any)(other: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` |
| `operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)(key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Returns the result stored under `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)`, or `null` when the action did not produce it. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#hashCode()()` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#toString()()` |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#errorMessage()` The reported `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()`, or `null` when the action did not fail. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#isSuccess()` Whether the action completed its work. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#payload()` key-value results produced by the action, keyed by `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys` |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?` | `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#status()` The reported `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()`, or `null` for an action that does not report one. |

## Public companion functions

### failure

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
fun failure(errorMessage: String, payload: Map<String, String> = emptyMap()): BackupDeviceActionResult
```

Returns a result reporting `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionValues#STATUS_FAILURE()` together with `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult.Companion#failure(kotlin.String,kotlin.collections.Map)`.

| Parameters |
|---|---|
| `errorMessage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | human-readable description of the failure, surfaced to the host as `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()` |
| `payload: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = emptyMap()` | additional data to return to the host; `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()` and `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()` entries it contains are overwritten |

### success

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
fun success(payload: Map<String, String> = emptyMap()): BackupDeviceActionResult
```

Returns a result reporting `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionValues#STATUS_SUCCESS()`.

| Parameters |
|---|---|
| `payload: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = emptyMap()` | additional data to return to the host; a `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()` entry it contains is overwritten |

## Public constructors

### BackupDeviceActionResult

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
BackupDeviceActionResult(payload: Map<String, String> = emptyMap())
```

## Public functions

### equals

```
open operator fun equals(other: Any?): Boolean
```

### get

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
operator fun get(key: String): String?
```

Returns the result stored under `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)`, or `null` when the action did not produce it.

Any key may be read, so a custom `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceAction` can return keys of its own alongside the `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys` constants.

### hashCode

```
open fun hashCode(): Int
```

### toString

```
open fun toString(): String
```

## Public properties

### errorMessage

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
val errorMessage: String?
```

The reported `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()`, or `null` when the action did not fail.

Reported only for a result that `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#isSuccess()` rejects. A successful action may legitimately carry a `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()` entry of its own --- an empty string, or a diagnostic unrelated to the outcome --- and surfacing that as a failure message would be misleading. This mirrors the host, which reads the key under exactly the same conditions.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#isSuccess()` |   |

### isSuccess

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
val isSuccess: Boolean
```

Whether the action completed its work.

Resolved in two steps:

- A reported `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()` decides on its own. Only `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionValues#STATUS_FAILURE()`, compared without regard to case, means failure; `status` is a generic key that custom actions also use to publish their own vocabulary, so an unrecognized value is reported as successful rather than being guessed at.

- With no `status` at all, a non-empty `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#ERROR()` means failure. An action that reports only an error would otherwise be read as passing.

Use `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)` to report a failure that callers and the host will honor.

### payload

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
val payload: Map<String, String>
```

key-value results produced by the action, keyed by `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys`

### status

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
val status: String?
```

The reported `https://developer.android.com/reference/kotlin/androidx/test/backup/BackupActionOutputKeys#STATUS()`, or `null` for an action that does not report one.