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