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 indicates the overall availability of 47 * BLE related functionality. For example, if BLE is disabled for connectivity, 48 * but enabled for location, the BLE available setting is enabled. 49 * 50 * @defgroup CHRE_USER_SETTINGS 51 * @{ 52 */ 53 #define CHRE_USER_SETTING_LOCATION UINT8_C(0) 54 #define CHRE_USER_SETTING_WIFI_AVAILABLE UINT8_C(1) 55 #define CHRE_USER_SETTING_AIRPLANE_MODE UINT8_C(2) 56 #define CHRE_USER_SETTING_MICROPHONE UINT8_C(3) 57 #define CHRE_USER_SETTING_BLE_AVAILABLE UINT8_C(4) 58 59 /** @} */ 60 61 /** 62 * Produce an event ID in the block of IDs reserved for settings notifications. 63 * 64 * @param offset Index into the event ID block, valid in the range [0,15] 65 */ 66 #define CHRE_SETTING_EVENT_ID(offset) (CHRE_EVENT_SETTING_CHANGED_FIRST_EVENT + (offset)) 67 68 /** 69 * nanoappHandleEvent argument: struct chreUserSettingChangedEvent 70 * 71 * Notify nanoapps of a change in the associated setting. Nanoapps must first 72 * register (via chreUserSettingConfigureEvents) for events before they are 73 * sent out. 74 */ 75 #define CHRE_EVENT_SETTING_CHANGED_LOCATION CHRE_SETTING_EVENT_ID(0) 76 #define CHRE_EVENT_SETTING_CHANGED_WIFI_AVAILABLE CHRE_SETTING_EVENT_ID(1) 77 #define CHRE_EVENT_SETTING_CHANGED_AIRPLANE_MODE CHRE_SETTING_EVENT_ID(2) 78 #define CHRE_EVENT_SETTING_CHANGED_MICROPHONE CHRE_SETTING_EVENT_ID(3) 79 #define CHRE_EVENT_SETTING_CHANGED_BLE_AVAILABLE CHRE_SETTING_EVENT_ID(4) 80 81 #if CHRE_EVENT_SETTING_CHANGED_BLE_AVAILABLE > CHRE_EVENT_SETTING_CHANGED_LAST_EVENT 82 #error Too many setting changed events. 83 #endif 84 85 /** 86 * Indicates the current state of a setting. 87 * The setting state is 'unknown' only in the following scenarios: 88 * - CHRE hasn't received the initial state yet on a restart. 89 * - The nanoapp is running on CHRE v1.4 or older 90 * - Nanoapp provided in invalid setting ID to chreUserSettingGetStatus. 91 */ 92 enum chreUserSettingState { 93 CHRE_USER_SETTING_STATE_UNKNOWN = -1, 94 CHRE_USER_SETTING_STATE_DISABLED = 0, 95 CHRE_USER_SETTING_STATE_ENABLED = 1 96 }; 97 98 /** 99 * The nanoappHandleEvent argument for CHRE settings changed notifications. 100 */ 101 struct chreUserSettingChangedEvent { 102 //! Indicates the setting whose state has changed. 103 uint8_t setting; 104 105 //! A value that corresponds to a member in enum chreUserSettingState, 106 // indicating the latest value of the setting. 107 int8_t settingState; 108 }; 109 110 /** 111 * Get the current state of a given setting. 112 * 113 * @param setting The setting to get the current status of. 114 * 115 * @return The current state of the requested setting. The state is returned 116 * as an int8_t to be consistent with the associated event data, but is 117 * guaranteed to be a valid enum chreUserSettingState member. 118 * 119 * @since v1.5 120 */ 121 int8_t chreUserSettingGetState(uint8_t setting); 122 123 /** 124 * Register or deregister for a notification on a status change for a given 125 * setting. Note that registration does not produce an event with the initial 126 * (or current) state, though nanoapps can use chreUserSettingGetState() for 127 * this purpose. 128 * 129 * @param setting The setting on whose change a notification is desired. 130 * @param enable The nanoapp is registered to receive notifications on a 131 * change in the user settings if this parameter is true, otherwise the 132 * nanoapp receives no further notifications for this setting. 133 * 134 * @since v1.5 135 */ 136 void chreUserSettingConfigureEvents(uint8_t setting, bool enable); 137 138 #ifdef __cplusplus 139 } 140 #endif 141 142 #endif /* _CHRE_USER_SETTINGS_H_ */ 143