/*
* Copyright (C) 2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.android.ddmlib;
import com.android.ddmlib.log.LogReceiver;
import java.io.IOException;
import java.util.Map;
/**
* A Device. It can be a physical device or an emulator.
*/
public interface IDevice {
public final static String PROP_BUILD_VERSION = "ro.build.version.release";
public final static String PROP_BUILD_API_LEVEL = "ro.build.version.sdk";
public final static String PROP_BUILD_CODENAME = "ro.build.version.codename";
public final static String PROP_DEBUGGABLE = "ro.debuggable";
/** Serial number of the first connected emulator. */
public final static String FIRST_EMULATOR_SN = "emulator-5554"; //$NON-NLS-1$
/** Device change bit mask: {@link DeviceState} change. */
public static final int CHANGE_STATE = 0x0001;
/** Device change bit mask: {@link Client} list change. */
public static final int CHANGE_CLIENT_LIST = 0x0002;
/** Device change bit mask: build info change. */
public static final int CHANGE_BUILD_INFO = 0x0004;
/** @deprecated Use {@link #PROP_BUILD_API_LEVEL}. */
public final static String PROP_BUILD_VERSION_NUMBER = PROP_BUILD_API_LEVEL;
public final static String MNT_EXTERNAL_STORAGE = "EXTERNAL_STORAGE"; //$NON-NLS-1$
public final static String MNT_ROOT = "ANDROID_ROOT"; //$NON-NLS-1$
public final static String MNT_DATA = "ANDROID_DATA"; //$NON-NLS-1$
/**
* The state of a device.
*/
public static enum DeviceState {
BOOTLOADER("bootloader"), //$NON-NLS-1$
OFFLINE("offline"), //$NON-NLS-1$
ONLINE("device"), //$NON-NLS-1$
RECOVERY("recovery"); //$NON-NLS-1$
private String mState;
DeviceState(String state) {
mState = state;
}
/**
* Returns a {@link DeviceState} from the string returned by <code>adb devices</code>.
*
* @param state the device state.
* @return a {@link DeviceState} object or <code>null</code> if the state is unknown.
*/
public static DeviceState getState(String state) {
for (DeviceState deviceState : values()) {
if (deviceState.mState.equals(state)) {
return deviceState;
}
}
return null;
}
}
/**
* Returns the serial number of the device.
*/
public String getSerialNumber();
/**
* Returns the name of the AVD the emulator is running.
* <p/>This is only valid if {@link #isEmulator()} returns true.
* <p/>If the emulator is not running any AVD (for instance it's running from an Android source
* tree build), this method will return "<code><build></code>".
*
* @return the name of the AVD or <code>null</code> if there isn't any.
*/
public String getAvdName();
/**
* Returns the state of the device.
*/
public DeviceState getState();
/**
* Returns the device properties. It contains the whole output of 'getprop'
*/
public Map<String, String> getProperties();
/**
* Returns the number of property for this device.
*/
public int getPropertyCount();
/**
* Returns a property value.
*
* @param name the name of the value to return.
* @return the value or <code>null</code> if the property does not exist.
*/
public String getProperty(String name);
/**
* Returns a mount point.
*
* @param name the name of the mount point to return
*
* @see #MNT_EXTERNAL_STORAGE
* @see #MNT_ROOT
* @see #MNT_DATA
*/
public String getMountPoint(String name);
/**
* Returns if the device is ready.
*
* @return <code>true</code> if {@link #getState()} returns {@link DeviceState#ONLINE}.
*/
public boolean isOnline();
/**
* Returns <code>true</code> if the device is an emulator.
*/
public boolean isEmulator();
/**
* Returns if the device is offline.
*
* @return <code>true</code> if {@link #getState()} returns {@link DeviceState#OFFLINE}.
*/
public boolean isOffline();
/**
* Returns if the device is in bootloader mode.
*
* @return <code>true</code> if {@link #getState()} returns {@link DeviceState#BOOTLOADER}.
*/
public boolean isBootLoader();
/**
* Returns whether the {@link Device} has {@link Client}s.
*/
public boolean hasClients();
/**
* Returns the array of clients.
*/
public Client[] getClients();
/**
* Returns a {@link Client} by its application name.
*
* @param applicationName the name of the application
* @return the <code>Client</code> object or <code>null</code> if no match was found.
*/
public Client getClient(String applicationName);
/**
* Returns a {@link SyncService} object to push / pull files to and from the device.
*
* @return <code>null</code> if the SyncService couldn't be created. This can happen if adb
* refuse to open the connection because the {@link IDevice} is invalid
* (or got disconnected).
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException if the connection with adb failed.
*/
public SyncService getSyncService()
throws TimeoutException, AdbCommandRejectedException, IOException;
/**
* Returns a {@link FileListingService} for this device.
*/
public FileListingService getFileListingService();
/**
* Takes a screen shot of the device and returns it as a {@link RawImage}.
*
* @return the screenshot as a <code>RawImage</code> or <code>null</code> if something
* went wrong.
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
*/
public RawImage getScreenshot() throws TimeoutException, AdbCommandRejectedException,
IOException;
/**
* Executes a shell command on the device, and sends the result to a <var>receiver</var>
* <p/>This is similar to calling
* <code>executeShellCommand(command, receiver, DdmPreferences.getTimeOut())</code>.
*
* @param command the shell command to execute
* @param receiver the {@link IShellOutputReceiver} that will receives the output of the shell
* command
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws ShellCommandUnresponsiveException in case the shell command doesn't send output
* for a given time.
* @throws IOException in case of I/O error on the connection.
*
* @see #executeShellCommand(String, IShellOutputReceiver, int)
* @see DdmPreferences#getTimeOut()
*/
public void executeShellCommand(String command, IShellOutputReceiver receiver)
throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
IOException;
/**
* Executes a shell command on the device, and sends the result to a <var>receiver</var>.
* <p/><var>maxTimeToOutputResponse</var> is used as a maximum waiting time when expecting the
* command output from the device.<br>
* At any time, if the shell command does not output anything for a period longer than
* <var>maxTimeToOutputResponse</var>, then the method will throw
* {@link ShellCommandUnresponsiveException}.
* <p/>For commands like log output, a <var>maxTimeToOutputResponse</var> value of 0, meaning
* that the method will never throw and will block until the receiver's
* {@link IShellOutputReceiver#isCancelled()} returns <code>true</code>, should be
* used.
*
* @param command the shell command to execute
* @param receiver the {@link IShellOutputReceiver} that will receives the output of the shell
* command
* @param maxTimeToOutputResponse the maximum amount of time during which the command is allowed
* to not output any response. A value of 0 means the method will wait forever
* (until the <var>receiver</var> cancels the execution) for command output and
* never throw.
* @throws TimeoutException in case of timeout on the connection when sending the command.
* @throws AdbCommandRejectedException if adb rejects the command.
* @throws ShellCommandUnresponsiveException in case the shell command doesn't send any output
* for a period longer than <var>maxTimeToOutputResponse</var>.
* @throws IOException in case of I/O error on the connection.
*
* @see DdmPreferences#getTimeOut()
*/
public void executeShellCommand(String command, IShellOutputReceiver receiver,
int maxTimeToOutputResponse)
throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
IOException;
/**
* Runs the event log service and outputs the event log to the {@link LogReceiver}.
* <p/>This call is blocking until {@link LogReceiver#isCancelled()} returns true.
* @param receiver the receiver to receive the event log entries.
* @throws TimeoutException in case of timeout on the connection. This can only be thrown if the
* timeout happens during setup. Once logs start being received, no timeout will occur as it's
* not possible to detect a difference between no log and timeout.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
*/
public void runEventLogService(LogReceiver receiver)
throws TimeoutException, AdbCommandRejectedException, IOException;
/**
* Runs the log service for the given log and outputs the log to the {@link LogReceiver}.
* <p/>This call is blocking until {@link LogReceiver#isCancelled()} returns true.
*
* @param logname the logname of the log to read from.
* @param receiver the receiver to receive the event log entries.
* @throws TimeoutException in case of timeout on the connection. This can only be thrown if the
* timeout happens during setup. Once logs start being received, no timeout will
* occur as it's not possible to detect a difference between no log and timeout.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
*/
public void runLogService(String logname, LogReceiver receiver)
throws TimeoutException, AdbCommandRejectedException, IOException;
/**
* Creates a port forwarding between a local and a remote port.
*
* @param localPort the local port to forward
* @param remotePort the remote port.
* @return <code>true</code> if success.
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
*/
public void createForward(int localPort, int remotePort)
throws TimeoutException, AdbCommandRejectedException, IOException;
/**
* Removes a port forwarding between a local and a remote port.
*
* @param localPort the local port to forward
* @param remotePort the remote port.
* @return <code>true</code> if success.
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
*/
public void removeForward(int localPort, int remotePort)
throws TimeoutException, AdbCommandRejectedException, IOException;
/**
* Returns the name of the client by pid or <code>null</code> if pid is unknown
* @param pid the pid of the client.
*/
public String getClientName(int pid);
/**
* Installs an Android application on device.
* This is a helper method that combines the syncPackageToDevice, installRemotePackage,
* and removePackage steps
*
* @param packageFilePath the absolute file system path to file on local host to install
* @param reinstall set to <code>true</code> if re-install of app should be performed
* @return a {@link String} with an error code, or <code>null</code> if success.
* @throws InstallException if the installation fails.
*/
public String installPackage(String packageFilePath, boolean reinstall)
throws InstallException;
/**
* Pushes a file to device
*
* @param localFilePath the absolute path to file on local host
* @return {@link String} destination path on device for file
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException in case of I/O error on the connection.
* @throws SyncException if an error happens during the push of the package on the device.
*/
public String syncPackageToDevice(String localFilePath)
throws TimeoutException, AdbCommandRejectedException, IOException, SyncException;
/**
* Installs the application package that was pushed to a temporary location on the device.
*
* @param remoteFilePath absolute file path to package file on device
* @param reinstall set to <code>true</code> if re-install of app should be performed
* @throws InstallException if the installation fails.
*/
public String installRemotePackage(String remoteFilePath, boolean reinstall)
throws InstallException;
/**
* Removes a file from device.
*
* @param remoteFilePath path on device of file to remove
* @throws InstallException if the installation fails.
*/
public void removeRemotePackage(String remoteFilePath) throws InstallException;
/**
* Uninstalls an package from the device.
*
* @param packageName the Android application package name to uninstall
* @return a {@link String} with an error code, or <code>null</code> if success.
* @throws InstallException if the uninstallation fails.
*/
public String uninstallPackage(String packageName) throws InstallException;
/**
* Reboot the device.
*
* @param into the bootloader name to reboot into, or null to just reboot the device.
* @throws TimeoutException in case of timeout on the connection.
* @throws AdbCommandRejectedException if adb rejects the command
* @throws IOException
*/
public void reboot(String into)
throws TimeoutException, AdbCommandRejectedException, IOException;
}