1 /* 2 * Copyright (C) 2011 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 _RECOVERY_DEVICE_H 18 #define _RECOVERY_DEVICE_H 19 20 #include <stddef.h> 21 22 #include <memory> 23 #include <string> 24 #include <vector> 25 26 // Forward declaration to avoid including "ui.h". 27 class RecoveryUI; 28 29 class Device { 30 public: 31 static constexpr const int kNoAction = -1; 32 static constexpr const int kHighlightUp = -2; 33 static constexpr const int kHighlightDown = -3; 34 static constexpr const int kInvokeItem = -4; 35 36 // ENTER vs REBOOT: The latter will trigger a reboot that goes through bootloader, which allows 37 // using a new bootloader / recovery image if applicable. For example, REBOOT_RESCUE goes from 38 // rescue -> bootloader -> rescue, whereas ENTER_RESCUE switches from recovery -> rescue 39 // directly. 40 enum BuiltinAction { 41 NO_ACTION = 0, 42 REBOOT = 1, 43 APPLY_SDCARD = 2, 44 // APPLY_CACHE was 3. 45 APPLY_ADB_SIDELOAD = 4, 46 WIPE_DATA = 5, 47 WIPE_CACHE = 6, 48 REBOOT_BOOTLOADER = 7, 49 SHUTDOWN = 8, 50 VIEW_RECOVERY_LOGS = 9, 51 MOUNT_SYSTEM = 10, 52 RUN_GRAPHICS_TEST = 11, 53 RUN_LOCALE_TEST = 12, 54 KEY_INTERRUPTED = 13, 55 ENTER_FASTBOOT = 14, 56 ENTER_RECOVERY = 15, 57 ENTER_RESCUE = 16, 58 REBOOT_FASTBOOT = 17, 59 REBOOT_RECOVERY = 18, 60 REBOOT_RESCUE = 19, 61 }; 62 63 explicit Device(RecoveryUI* ui); ~Device()64 virtual ~Device() {} 65 66 // Returns a raw pointer to the RecoveryUI object. GetUI()67 virtual RecoveryUI* GetUI() { 68 return ui_.get(); 69 } 70 71 // Resets the UI object to the given UI. Used to override the default UI in case initialization 72 // failed, or we want a different UI for some reason. The device object will take the ownership. ResetUI(RecoveryUI * ui)73 virtual void ResetUI(RecoveryUI* ui) { 74 ui_.reset(ui); 75 } 76 77 // Called when recovery starts up (after the UI has been obtained and initialized and after the 78 // arguments have been parsed, but before anything else). StartRecovery()79 virtual void StartRecovery() {} 80 81 // Called from the main thread when recovery is at the main menu and waiting for input, and a key 82 // is pressed. (Note that "at" the main menu does not necessarily mean the menu is visible; 83 // recovery will be at the main menu with it invisible after an unsuccessful operation, such as 84 // failed to install an OTA package, or if recovery is started with no command.) 85 // 86 // 'key' is the code of the key just pressed. (You can call IsKeyPressed() on the RecoveryUI 87 // object you returned from GetUI() if you want to find out if other keys are held down.) 88 // 89 // 'visible' is true if the menu is visible. 90 // 91 // Returns one of the defined constants below in order to: 92 // - move the menu highlight (kHighlight{Up,Down}: negative value) 93 // - invoke the highlighted item (kInvokeItem: negative value) 94 // - do nothing (kNoAction: negative value) 95 // - invoke a specific action (a menu position: non-negative value) 96 virtual int HandleMenuKey(int key, bool visible); 97 98 // Returns the list of menu items (a vector of strings). The menu_position passed to 99 // InvokeMenuItem() will correspond to the indexes into this array. 100 virtual const std::vector<std::string>& GetMenuItems(); 101 102 // Performs a recovery action selected from the menu. 'menu_position' will be the index of the 103 // selected menu item, or a non-negative value returned from HandleMenuKey(). The menu will be 104 // hidden when this is called; implementations can call GetUI()->Print() to print information to 105 // the screen. If the menu position is one of the builtin actions, you can just return the 106 // corresponding enum value. If it is an action specific to your device, you actually perform it 107 // here and return NO_ACTION. 108 virtual BuiltinAction InvokeMenuItem(size_t menu_position); 109 110 // Removes the menu item for the given action. This allows tailoring the menu based on the 111 // runtime info, such as the availability of /cache or /sdcard. 112 virtual void RemoveMenuItemForAction(Device::BuiltinAction action); 113 114 // Called before and after we do a wipe data/factory reset operation, either via a reboot from the 115 // main system with the --wipe_data flag, or when the user boots into recovery image manually and 116 // selects the option from the menu, to perform whatever device-specific wiping actions as needed. 117 // Returns true on success; returning false from PreWipeData will prevent the regular wipe, and 118 // returning false from PostWipeData will cause the wipe to be considered a failure. PreWipeData()119 virtual bool PreWipeData() { 120 return true; 121 } 122 PostWipeData()123 virtual bool PostWipeData() { 124 return true; 125 } 126 127 private: 128 // The RecoveryUI object that should be used to display the user interface for this device. 129 std::unique_ptr<RecoveryUI> ui_; 130 }; 131 132 // Disable name mangling, as this function will be loaded via dlsym(3). 133 extern "C" { 134 135 // The device-specific library must define this function (or the default one will be used, if there 136 // is no device-specific library). It returns the Device object that recovery should use. 137 Device* make_device(); 138 } 139 140 #endif // _DEVICE_H 141