# androidx.datastore

*** ** * ** ***

## Top-level functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<T>>` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/package-summary#dataStore(kotlin.String,androidx.datastore.core.Serializer,androidx.datastore.core.handlers.ReplaceFileCorruptionHandler,kotlin.Function1,kotlinx.coroutines.CoroutineScope)( fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, serializer: https://developer.android.com/reference/kotlin/androidx/datastore/core/Serializer<T>, corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<T>?, produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<T>>, scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html )` Creates a property delegate for a single process DataStore. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<T>>` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 24) <T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/package-summary#deviceProtectedDataStore(kotlin.String,androidx.datastore.core.Serializer,androidx.datastore.core.handlers.ReplaceFileCorruptionHandler,kotlin.Function1,kotlinx.coroutines.CoroutineScope)( fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, serializer: https://developer.android.com/reference/kotlin/androidx/datastore/core/Serializer<T>, corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<T>?, produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<T>>, scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html )` Creates a property delegate for a single process DataStore to be used in direct boot. |

## Extension functions summary

|---|---|
| `https://developer.android.com/reference/java/io/File.html` | `https://developer.android.com/reference/android/content/Context.html.https://developer.android.com/reference/kotlin/androidx/datastore/package-summary#(android.content.Context).dataStoreFile(kotlin.String)(fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Generate the File object for DataStore based on the provided context and name. |

## Top-level functions

### dataStore

Artifact: [androidx.datastore:datastore](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/DataStoreDelegate.android.kt+function:dataStore)

```
fun <T : Any?> dataStore(
    fileName: String,
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    produceMigrations: (Context) -> List<DataMigration<T>> = { listOf() },
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
): ReadOnlyProperty<Context, DataStore<T>>
```

Creates a property delegate for a single process DataStore. This should only be called once in a file (at the top level), and all usages of the DataStore should use a reference the same Instance. The receiver type for the property delegate must be an instance of `https://developer.android.com/reference/android/content/Context.html`.

This should only be used from a single application in a single classloader in a single process.

Example usage:

```kotlin
val Context.myDataStore by dataStore("filename", serializer)

class SomeClass(val context: Context) {
   suspend fun update() = context.myDataStore.updateData {...}
}
```

| Parameters |
|---|---|
| `fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the filename relative to Context.applicationContext.filesDir that DataStore acts on. The File is obtained from `https://developer.android.com/reference/kotlin/androidx/datastore/package-summary#(android.content.Context).dataStoreFile(kotlin.String)`. It is created in the "/datastore" subdirectory, in the user encrypted storage. |
| `serializer: https://developer.android.com/reference/kotlin/androidx/datastore/core/Serializer<T>` | The serializer for `T`. |
| `corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<T>? = null` | The corruptionHandler is invoked if DataStore encounters a `https://developer.android.com/reference/kotlin/androidx/datastore/core/CorruptionException` when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized. |
| `produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<T>> = { listOf() }` | produce the migrations. The ApplicationContext is passed in to these callbacks as a parameter. DataMigrations are run before any access to data can occur. Each producer and migration may be run more than once whether or not it already succeeded (potentially because another migration failed or a write to disk failed.) |
| `scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html = CoroutineScope(Dispatchers.IO + SupervisorJob())` | The scope in which IO operations and transform functions will execute. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<T>>` | a property delegate that manages a datastore as a singleton. |

### deviceProtectedDataStore

Artifact: [androidx.datastore:datastore](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/DataStoreDelegate.android.kt+function:deviceProtectedDataStore)

```
@RequiresApi(value = 24)
fun <T : Any?> deviceProtectedDataStore(
    fileName: String,
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    produceMigrations: (Context) -> List<DataMigration<T>> = { listOf() },
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
): ReadOnlyProperty<Context, DataStore<T>>
```

Creates a property delegate for a single process DataStore to be used in direct boot.

| Parameters |
|---|---|
| `fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the filename relative to Context.applicationContext.filesDir that DataStore acts on. The File is obtained from `https://developer.android.com/reference/kotlin/androidx/datastore/package-summary#(android.content.Context).dataStoreFile(kotlin.String)`. It is created in the "/datastore" subdirectory, in the user encrypted storage. |
| `serializer: https://developer.android.com/reference/kotlin/androidx/datastore/core/Serializer<T>` | The serializer for `T`. |
| `corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<T>? = null` | The corruptionHandler is invoked if DataStore encounters a `https://developer.android.com/reference/kotlin/androidx/datastore/core/CorruptionException` when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized. |
| `produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<T>> = { listOf() }` | produce the migrations. The ApplicationContext is passed in to these callbacks as a parameter. DataMigrations are run before any access to data can occur. Each producer and migration may be run more than once whether or not it already succeeded (potentially because another migration failed or a write to disk failed.) |
| `scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html = CoroutineScope(Dispatchers.IO + SupervisorJob())` | The scope in which IO operations and transform functions will execute. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<T>>` | a property delegate that manages a datastore as a singleton. |

## Extension functions

### Context.dataStoreFile

Artifact: [androidx.datastore:datastore](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/DataStoreFile.android.kt+function:dataStoreFile) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
fun Context.dataStoreFile(fileName: String): File
```

Generate the File object for DataStore based on the provided context and name. The file is generated by calling `File(context.applicationContext.filesDir, "datastore/$fileName")`. This is public to allow for testing and backwards compatibility (e.g. if moving from the `dataStore` delegate or context.createDataStore to DataStoreFactory).

Do NOT use the file outside of DataStore.

The context of the application used to get the files directory @fileName the file name