1 /* 2 * Copyright (C) 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 * http://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 // IWYU pragma: private, include "chre_api/chre.h" 18 // IWYU pragma: friend chre/.*\.h 19 20 #ifndef _CHRE_USER_SETTINGS_H_ 21 #define _CHRE_USER_SETTINGS_H_ 22 23 /** 24 * @file 25 * The API for requesting notifications on changes in the settings of the 26 * active user. If the device is set up with one or more secondary users 27 * (see https://source.android.com/devices/tech/admin/multi-user), the user 28 * settings in CHRE reflect that of the currently active user. 29 */ 30 31 #include <stdbool.h> 32 #include <stdint.h> 33 34 #include <chre/event.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * The user settings that nanoapps can request notifications for on a status 42 * change. 43 * 44 * NOTE: The WIFI available setting indicates the overall availability 45 * of WIFI related functionality. For example, if wifi is disabled for 46 * connectivity but enabled for location, the WIFI available setting is 47 * enabled. 48 * 49 * NOTE: The BLE available setting is the logical OR of the main Bluetooth 50 * setting and the Bluetooth scanning setting found under Location settings. 51 * Note that this indicates whether the user is allowing Bluetooth to be used, 52 * however the system may still fully power down the BLE chip in some scenarios 53 * if no request for it exists on the Android host side. See the 54 * chreBleStartScanAsync() API documentation for more information. 55 * 56 * @defgroup CHRE_USER_SETTINGS 57 * @{ 58 */ 59 #define CHRE_USER_SETTING_LOCATION UINT8_C(0) 60 #define CHRE_USER_SETTING_WIFI_AVAILABLE UINT8_C(1) 61 #define CHRE_USER_SETTING_AIRPLANE_MODE UINT8_C(2) 62 #define CHRE_USER_SETTING_MICROPHONE UINT8_C(3) 63 #define CHRE_USER_SETTING_BLE_AVAILABLE UINT8_C(4) 64 65 /** @} */ 66 67 /** 68 * Produce an event ID in the block of IDs reserved for settings notifications. 69 * 70 * @param offset Index into the event ID block, valid in the range [0,15] 71 */ 72 #define CHRE_SETTING_EVENT_ID(offset) (CHRE_EVENT_SETTING_CHANGED_FIRST_EVENT + (offset)) 73 74 /** 75 * nanoappHandleEvent argument: struct chreUserSettingChangedEvent 76 * 77 * Notify nanoapps of a change in the associated setting. Nanoapps must first 78 * register (via chreUserSettingConfigureEvents) for events before they are 79 * sent out. 80 */ 81 #define CHRE_EVENT_SETTING_CHANGED_LOCATION CHRE_SETTING_EVENT_ID(0) 82 #define CHRE_EVENT_SETTING_CHANGED_WIFI_AVAILABLE CHRE_SETTING_EVENT_ID(1) 83 #define CHRE_EVENT_SETTING_CHANGED_AIRPLANE_MODE CHRE_SETTING_EVENT_ID(2) 84 #define CHRE_EVENT_SETTING_CHANGED_MICROPHONE CHRE_SETTING_EVENT_ID(3) 85 #define CHRE_EVENT_SETTING_CHANGED_BLE_AVAILABLE CHRE_SETTING_EVENT_ID(4) 86 87 #if CHRE_EVENT_SETTING_CHANGED_BLE_AVAILABLE > CHRE_EVENT_SETTING_CHANGED_LAST_EVENT 88 #error Too many setting changed events. 89 #endif 90 91 /** 92 * Indicates the current state of a setting. 93 * The setting state is 'unknown' only in the following scenarios: 94 * - CHRE hasn't received the initial state yet on a restart. 95 * - The nanoapp is running on CHRE v1.4 or older 96 * - Nanoapp provided in invalid setting ID to chreUserSettingGetStatus. 97 */ 98 enum chreUserSettingState { 99 CHRE_USER_SETTING_STATE_UNKNOWN = -1, 100 CHRE_USER_SETTING_STATE_DISABLED = 0, 101 CHRE_USER_SETTING_STATE_ENABLED = 1 102 }; 103 104 /** 105 * The nanoappHandleEvent argument for CHRE settings changed notifications. 106 */ 107 struct chreUserSettingChangedEvent { 108 //! Indicates the setting whose state has changed. 109 uint8_t setting; 110 111 //! A value that corresponds to a member in enum chreUserSettingState, 112 // indicating the latest value of the setting. 113 int8_t settingState; 114 }; 115 116 /** 117 * Get the current state of a given setting. 118 * 119 * @param setting The setting to get the current status of. 120 * 121 * @return The current state of the requested setting. The state is returned 122 * as an int8_t to be consistent with the associated event data, but is 123 * guaranteed to be a valid enum chreUserSettingState member. 124 * 125 * @since v1.5 126 */ 127 int8_t chreUserSettingGetState(uint8_t setting); 128 129 /** 130 * Register or deregister for a notification on a status change for a given 131 * setting. Note that registration does not produce an event with the initial 132 * (or current) state, though nanoapps can use chreUserSettingGetState() for 133 * this purpose. 134 * 135 * @param setting The setting on whose change a notification is desired. 136 * @param enable The nanoapp is registered to receive notifications on a 137 * change in the user settings if this parameter is true, otherwise the 138 * nanoapp receives no further notifications for this setting. 139 * 140 * @since v1.5 141 */ 142 void chreUserSettingConfigureEvents(uint8_t setting, bool enable); 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #endif /* _CHRE_USER_SETTINGS_H_ */ 149