ddms/libs/ddmlib/src/com/android/ddmlib/IDevice.java

   1 /*
   2  * Copyright (C) 2008 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 package com.android.ddmlib;
  18
  19 import com.android.ddmlib.log.LogReceiver;
  20
  21 import java.io.IOException;
  22 import java.util.Map;
  23
  24
  25 /**
  26  *  A Device. It can be a physical device or an emulator.
  27  */
  28 public interface IDevice {
  29
  30     public final static String PROP_BUILD_VERSION = "ro.build.version.release";
  31     public final static String PROP_BUILD_API_LEVEL = "ro.build.version.sdk";
  32     public final static String PROP_BUILD_CODENAME = "ro.build.version.codename";
  33
  34     public final static String PROP_DEBUGGABLE = "ro.debuggable";
  35
  36     /** Serial number of the first connected emulator. */
  37     public final static String FIRST_EMULATOR_SN = "emulator-5554"; //$NON-NLS-1$
  38     /** Device change bit mask: {@link DeviceState} change. */
  39     public static final int CHANGE_STATE = 0x0001;
  40     /** Device change bit mask: {@link Client} list change. */
  41     public static final int CHANGE_CLIENT_LIST = 0x0002;
  42     /** Device change bit mask: build info change. */
  43     public static final int CHANGE_BUILD_INFO = 0x0004;
  44
  45     /** @deprecated Use {@link #PROP_BUILD_API_LEVEL}. */
  46     public final static String PROP_BUILD_VERSION_NUMBER = PROP_BUILD_API_LEVEL;
  47
  48     public final static String MNT_EXTERNAL_STORAGE = "EXTERNAL_STORAGE"; //$NON-NLS-1$
  49     public final static String MNT_ROOT = "ANDROID_ROOT"; //$NON-NLS-1$
  50     public final static String MNT_DATA = "ANDROID_DATA"; //$NON-NLS-1$
  51
  52     /**
  53      * The state of a device.
  54      */
  55     public static enum DeviceState {
  56         BOOTLOADER("bootloader"), //$NON-NLS-1$
  57         OFFLINE("offline"), //$NON-NLS-1$
  58         ONLINE("device"); //$NON-NLS-1$
  59
  60         private String mState;
  61
  62         DeviceState(String state) {
  63             mState = state;
  64         }
  65
  66         /**
  67          * Returns a {@link DeviceState} from the string returned by <code>adb devices</code>.
  68          * @param state the device state.
  69          * @return a {@link DeviceState} object or <code>null</code> if the state is unknown.
  70          */
  71         public static DeviceState getState(String state) {
  72             for (DeviceState deviceState : values()) {
  73                 if (deviceState.mState.equals(state)) {
  74                     return deviceState;
  75                 }
  76             }
  77             return null;
  78         }
  79     }
  80
  81     /**
  82      * Returns the serial number of the device.
  83      */
  84     public String getSerialNumber();
  85
  86     /**
  87      * Returns the name of the AVD the emulator is running.
  88      * <p/>This is only valid if {@link #isEmulator()} returns true.
  89      * <p/>If the emulator is not running any AVD (for instance it's running from an Android source
  90      * tree build), this method will return "<code>&lt;build&gt;</code>".
  91      * @return the name of the AVD or <code>null</code> if there isn't any.
  92      */
  93     public String getAvdName();
  94
  95     /**
  96      * Returns the state of the device.
  97      */
  98     public DeviceState getState();
  99
 100     /**
 101      * Returns the device properties. It contains the whole output of 'getprop'
 102      */
 103     public Map<String, String> getProperties();
 104
 105     /**
 106      * Returns the number of property for this device.
 107      */
 108     public int getPropertyCount();
 109
 110     /**
 111      * Returns a property value.
 112      * @param name the name of the value to return.
 113      * @return the value or <code>null</code> if the property does not exist.
 114      */
 115     public String getProperty(String name);
 116
 117     /**
 118      * Returns a mount point.
 119      * @param name the name of the mount point to return
 120      *
 121      * @see #MNT_EXTERNAL_STORAGE
 122      * @see #MNT_ROOT
 123      * @see #MNT_DATA
 124      */
 125     public String getMountPoint(String name);
 126
 127     /**
 128      * Returns if the device is ready.
 129      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#ONLINE}.
 130      */
 131     public boolean isOnline();
 132
 133     /**
 134      * Returns <code>true</code> if the device is an emulator.
 135      */
 136     public boolean isEmulator();
 137
 138     /**
 139      * Returns if the device is offline.
 140      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#OFFLINE}.
 141      */
 142     public boolean isOffline();
 143
 144     /**
 145      * Returns if the device is in bootloader mode.
 146      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#BOOTLOADER}.
 147      */
 148     public boolean isBootLoader();
 149
 150     /**
 151      * Returns whether the {@link Device} has {@link Client}s.
 152      */
 153     public boolean hasClients();
 154
 155     /**
 156      * Returns the array of clients.
 157      */
 158     public Client[] getClients();
 159
 160     /**
 161      * Returns a {@link Client} by its application name.
 162      * @param applicationName the name of the application
 163      * @return the <code>Client</code> object or <code>null</code> if no match was found.
 164      */
 165     public Client getClient(String applicationName);
 166
 167     /**
 168      * Returns a {@link SyncService} object to push / pull files to and from the device.
 169      * @return <code>null</code> if the SyncService couldn't be created. This can happen if adb
 170      * refuse to open the connection because the {@link IDevice} is invalid (or got disconnected).
 171      * @throws IOException if the connection with adb failed.
 172      */
 173     public SyncService getSyncService() throws IOException;
 174
 175     /**
 176      * Returns a {@link FileListingService} for this device.
 177      */
 178     public FileListingService getFileListingService();
 179
 180     /**
 181      * Takes a screen shot of the device and returns it as a {@link RawImage}.
 182      * @return the screenshot as a <code>RawImage</code> or <code>null</code> if
 183      * something went wrong.
 184      * @throws IOException
 185      */
 186     public RawImage getScreenshot() throws IOException;
 187
 188     /**
 189      * Executes a shell command on the device, and sends the result to a receiver.
 190      * @param command The command to execute
 191      * @param receiver The receiver object getting the result from the command.
 192      * @throws IOException
 193      */
 194     public void executeShellCommand(String command,
 195             IShellOutputReceiver receiver) throws IOException;
 196
 197     /**
 198      * Runs the event log service and outputs the event log to the {@link LogReceiver}.
 199      * @param receiver the receiver to receive the event log entries.
 200      * @throws IOException
 201      */
 202     public void runEventLogService(LogReceiver receiver) throws IOException;
 203
 204     /**
 205      * Runs the log service for the given log and outputs the log to the {@link LogReceiver}.
 206      * @param logname the logname of the log to read from.
 207      * @param receiver the receiver to receive the event log entries.
 208      * @throws IOException
 209      */
 210     public void runLogService(String logname, LogReceiver receiver) throws IOException;
 211
 212     /**
 213      * Creates a port forwarding between a local and a remote port.
 214      * @param localPort the local port to forward
 215      * @param remotePort the remote port.
 216      * @return <code>true</code> if success.
 217      */
 218     public boolean createForward(int localPort, int remotePort);
 219
 220     /**
 221      * Removes a port forwarding between a local and a remote port.
 222      * @param localPort the local port to forward
 223      * @param remotePort the remote port.
 224      * @return <code>true</code> if success.
 225      */
 226     public boolean removeForward(int localPort, int remotePort);
 227
 228     /**
 229      * Returns the name of the client by pid or <code>null</code> if pid is unknown
 230      * @param pid the pid of the client.
 231      */
 232     public String getClientName(int pid);
 233
 234     /**
 235      * Installs an Android application on device.
 236      * This is a helper method that combines the syncPackageToDevice, installRemotePackage,
 237      * and removePackage steps
 238      * @param packageFilePath the absolute file system path to file on local host to install
 239      * @param reinstall set to <code>true</code> if re-install of app should be performed
 240      * @return a {@link String} with an error code, or <code>null</code> if success.
 241      * @throws IOException
 242      */
 243     public String installPackage(String packageFilePath, boolean reinstall)  throws IOException;
 244
 245     /**
 246      * Pushes a file to device
 247      * @param localFilePath the absolute path to file on local host
 248      * @return {@link String} destination path on device for file
 249      * @throws IOException if fatal error occurred when pushing file
 250      */
 251     public String syncPackageToDevice(String localFilePath)
 252             throws IOException;
 253
 254     /**
 255      * Installs the application package that was pushed to a temporary location on the device.
 256      * @param remoteFilePath absolute file path to package file on device
 257      * @param reinstall set to <code>true</code> if re-install of app should be performed
 258      * @throws InstallException if installation failed
 259      */
 260     public String installRemotePackage(String remoteFilePath, boolean reinstall)
 261             throws IOException;
 262
 263     /**
 264      * Remove a file from device
 265      * @param remoteFilePath path on device of file to remove
 266      * @throws IOException if file removal failed
 267      */
 268     public void removeRemotePackage(String remoteFilePath) throws IOException;
 269
 270     /**
 271      * Uninstall an package from the device.
 272      * @param packageName the Android application package name to uninstall
 273      * @return a {@link String} with an error code, or <code>null</code> if success.
 274      * @throws IOException
 275      */
 276     public String uninstallPackage(String packageName) throws IOException;
 277
 278 }