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