Home | History | Annotate | Download | only in recovery
      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 "ui.h"
     21 
     22 class Device {
     23   public:
     24     virtual ~Device() { }
     25 
     26     // Called to obtain the UI object that should be used to display
     27     // the recovery user interface for this device.  You should not
     28     // have called Init() on the UI object already, the caller will do
     29     // that after this method returns.
     30     virtual RecoveryUI* GetUI() = 0;
     31 
     32     // Called when recovery starts up (after the UI has been obtained
     33     // and initialized and after the arguments have been parsed, but
     34     // before anything else).
     35     virtual void StartRecovery() { };
     36 
     37     // enum KeyAction { NONE, TOGGLE, REBOOT };
     38 
     39     // // Called in the input thread when a new key (key_code) is
     40     // // pressed.  *key_pressed is an array of KEY_MAX+1 bytes
     41     // // indicating which other keys are already pressed.  Return a
     42     // // KeyAction to indicate action should be taken immediately.
     43     // // These actions happen when recovery is not waiting for input
     44     // // (eg, in the midst of installing a package).
     45     // virtual KeyAction CheckImmediateKeyAction(volatile char* key_pressed, int key_code) = 0;
     46 
     47     // Called from the main thread when recovery is at the main menu
     48     // and waiting for input, and a key is pressed.  (Note that "at"
     49     // the main menu does not necessarily mean the menu is visible;
     50     // recovery will be at the main menu with it invisible after an
     51     // unsuccessful operation [ie OTA package failure], or if recovery
     52     // is started with no command.)
     53     //
     54     // key is the code of the key just pressed.  (You can call
     55     // IsKeyPressed() on the RecoveryUI object you returned from GetUI
     56     // if you want to find out if other keys are held down.)
     57     //
     58     // visible is true if the menu is visible.
     59     //
     60     // Return one of the defined constants below in order to:
     61     //
     62     //   - move the menu highlight (kHighlight{Up,Down})
     63     //   - invoke the highlighted item (kInvokeItem)
     64     //   - do nothing (kNoAction)
     65     //   - invoke a specific action (a menu position: any non-negative number)
     66     virtual int HandleMenuKey(int key, int visible) = 0;
     67 
     68     enum BuiltinAction { NO_ACTION, REBOOT, APPLY_EXT, APPLY_CACHE,
     69                          APPLY_ADB_SIDELOAD, WIPE_DATA, WIPE_CACHE };
     70 
     71     // Perform a recovery action selected from the menu.
     72     // 'menu_position' will be the item number of the selected menu
     73     // item, or a non-negative number returned from
     74     // device_handle_key().  The menu will be hidden when this is
     75     // called; implementations can call ui_print() to print
     76     // information to the screen.  If the menu position is one of the
     77     // builtin actions, you can just return the corresponding enum
     78     // value.  If it is an action specific to your device, you
     79     // actually perform it here and return NO_ACTION.
     80     virtual BuiltinAction InvokeMenuItem(int menu_position) = 0;
     81 
     82     static const int kNoAction = -1;
     83     static const int kHighlightUp = -2;
     84     static const int kHighlightDown = -3;
     85     static const int kInvokeItem = -4;
     86 
     87     // Called when we do a wipe data/factory reset operation (either via a
     88     // reboot from the main system with the --wipe_data flag, or when the
     89     // user boots into recovery manually and selects the option from the
     90     // menu.)  Can perform whatever device-specific wiping actions are
     91     // needed.  Return 0 on success.  The userdata and cache partitions
     92     // are erased AFTER this returns (whether it returns success or not).
     93     virtual int WipeData() { return 0; }
     94 
     95     // Return the headers (an array of strings, one per line,
     96     // NULL-terminated) for the main menu.  Typically these tell users
     97     // what to push to move the selection and invoke the selected
     98     // item.
     99     virtual const char* const* GetMenuHeaders() = 0;
    100 
    101     // Return the list of menu items (an array of strings,
    102     // NULL-terminated).  The menu_position passed to InvokeMenuItem
    103     // will correspond to the indexes into this array.
    104     virtual const char* const* GetMenuItems() = 0;
    105 };
    106 
    107 // The device-specific library must define this function (or the
    108 // default one will be used, if there is no device-specific library).
    109 // It returns the Device object that recovery should use.
    110 Device* make_device();
    111 
    112 #endif  // _DEVICE_H
    113