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