1 /*
2 * Copyright 2021 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.accompanist.permissions
18
19 import androidx.compose.runtime.Composable
20 import androidx.compose.runtime.Stable
21
22 /**
23 * Creates a [PermissionState] that is remembered across compositions.
24 *
25 * It's recommended that apps exercise the permissions workflow as described in the
26 * [documentation](https://developer.android.com/training/permissions/requesting#workflow_for_requesting_permissions).
27 *
28 * @param permission the permission to control and observe.
29 * @param onPermissionResult will be called with whether or not the user granted the permission
30 * after [PermissionState.launchPermissionRequest] is called.
31 */
32 @ExperimentalPermissionsApi
33 @Composable
rememberPermissionStatenull34 public fun rememberPermissionState(
35 permission: String,
36 onPermissionResult: (Boolean) -> Unit = {}
37 ): PermissionState {
38 return rememberMutablePermissionState(permission, onPermissionResult)
39 }
40
41 /**
42 * A state object that can be hoisted to control and observe [permission] status changes.
43 *
44 * In most cases, this will be created via [rememberPermissionState].
45 *
46 * It's recommended that apps exercise the permissions workflow as described in the
47 * [documentation](https://developer.android.com/training/permissions/requesting#workflow_for_requesting_permissions).
48 */
49 @ExperimentalPermissionsApi
50 @Stable
51 public interface PermissionState {
52
53 /**
54 * The permission to control and observe.
55 */
56 public val permission: String
57
58 /**
59 * [permission]'s status
60 */
61 public val status: PermissionStatus
62
63 /**
64 * Request the [permission] to the user.
65 *
66 * This should always be triggered from non-composable scope, for example, from a side-effect
67 * or a non-composable callback. Otherwise, this will result in an IllegalStateException.
68 *
69 * This triggers a system dialog that asks the user to grant or revoke the permission.
70 * Note that this dialog might not appear on the screen if the user doesn't want to be asked
71 * again or has denied the permission multiple times.
72 * This behavior varies depending on the Android level API.
73 */
launchPermissionRequestnull74 public fun launchPermissionRequest(): Unit
75 }
76