/* * Copyright (C) 2010 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 android.hardware.usb; import android.Manifest; import android.annotation.Nullable; import android.annotation.RequiresFeature; import android.annotation.RequiresPermission; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.annotation.SystemApi; import android.annotation.SystemService; import android.app.PendingIntent; import android.content.ComponentName; import android.content.Context; import android.content.pm.PackageManager; import android.content.pm.PackageManager.NameNotFoundException; import android.hardware.usb.gadget.V1_0.GadgetFunction; import android.os.Bundle; import android.os.ParcelFileDescriptor; import android.os.Process; import android.os.RemoteException; import android.util.Log; import com.android.internal.util.Preconditions; import java.util.HashMap; import java.util.Map; import java.util.StringJoiner; /** * This class allows you to access the state of USB and communicate with USB devices. * Currently only host mode is supported in the public API. * *
For more information about communicating with USB hardware, read the * USB developer guide.
*If data is read from the {@link java.io.InputStream} created from this file descriptor all * data of a USB transfer should be read at once. If only a partial request is read the rest of * the transfer is dropped. * * @param accessory the USB accessory to open * @return file descriptor, or null if the accessory could not be opened. */ @RequiresFeature(PackageManager.FEATURE_USB_ACCESSORY) public ParcelFileDescriptor openAccessory(UsbAccessory accessory) { try { return mService.openAccessory(accessory); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Gets the functionfs control file descriptor for the given function, with * the usb descriptors and strings already written. The file descriptor is used * by the function implementation to handle events and control requests. * * @param function to get control fd for. Currently {@link #FUNCTION_MTP} and * {@link #FUNCTION_PTP} are supported. * @return A ParcelFileDescriptor holding the valid fd, or null if the fd was not found. * * {@hide} */ public ParcelFileDescriptor getControlFd(long function) { try { return mService.getControlFd(function); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Returns true if the caller has permission to access the device. * Permission might have been granted temporarily via * {@link #requestPermission(UsbDevice, PendingIntent)} or * by the user choosing the caller as the default application for the device. * Permission for USB devices of class {@link UsbConstants#USB_CLASS_VIDEO} for clients that * target SDK {@link android.os.Build.VERSION_CODES#P} and above can be granted only if they * have additionally the {@link android.Manifest.permission#CAMERA} permission. * * @param device to check permissions for * @return true if caller has permission */ @RequiresFeature(PackageManager.FEATURE_USB_HOST) public boolean hasPermission(UsbDevice device) { if (mService == null) { return false; } try { return mService.hasDevicePermission(device, mContext.getPackageName()); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Returns true if the caller has permission to access the accessory. * Permission might have been granted temporarily via * {@link #requestPermission(UsbAccessory, PendingIntent)} or * by the user choosing the caller as the default application for the accessory. * * @param accessory to check permissions for * @return true if caller has permission */ @RequiresFeature(PackageManager.FEATURE_USB_ACCESSORY) public boolean hasPermission(UsbAccessory accessory) { if (mService == null) { return false; } try { return mService.hasAccessoryPermission(accessory); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Requests temporary permission for the given package to access the device. * This may result in a system dialog being displayed to the user * if permission had not already been granted. * Success or failure is returned via the {@link android.app.PendingIntent} pi. * If successful, this grants the caller permission to access the device only * until the device is disconnected. * * The following extras will be added to pi: *
* USB functions represent interfaces which are published to the host to access * services offered by the device. *
* * @deprecated use getCurrentFunctions() instead. * @param function name of the USB function * @return true if the USB function is enabled * * {@hide} */ @Deprecated public boolean isFunctionEnabled(String function) { try { return mService.isFunctionEnabled(function); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Sets the current USB functions when in device mode. ** USB functions represent interfaces which are published to the host to access * services offered by the device. *
* This method is intended to select among primary USB functions. The system may * automatically activate additional functions such as {@link #USB_FUNCTION_ADB} * or {@link #USB_FUNCTION_ACCESSORY} based on other settings and states. *
* An argument of 0 indicates that the device is charging, and can pick any * appropriate function for that purpose. *
* Note: This function is asynchronous and may fail silently without applying * the requested changes. *
* * @param functions the USB function(s) to set, as a bitwise mask. * Must satisfy {@link UsbManager#areSettableFunctions} * * {@hide} */ public void setCurrentFunctions(long functions) { try { mService.setCurrentFunctions(functions); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Sets the current USB functions when in device mode. * * @deprecated use setCurrentFunctions(long) instead. * @param functions the USB function(s) to set. * @param usbDataUnlocked unused * {@hide} */ @Deprecated public void setCurrentFunction(String functions, boolean usbDataUnlocked) { try { mService.setCurrentFunction(functions, usbDataUnlocked); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Returns the current USB functions in device mode. ** This function returns the state of primary USB functions and can return a * mask containing any usb function(s) except for ADB. *
* * @return The currently enabled functions, in a bitwise mask. * A zero mask indicates that the current function is the charging function. * * {@hide} */ public long getCurrentFunctions() { try { return mService.getCurrentFunctions(); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Sets the screen unlocked functions, which are persisted and set as the current functions * whenever the screen is unlocked. ** A zero mask has the effect of switching off this feature, so functions * no longer change on screen unlock. *
* Note: When the screen is on, this method will apply given functions as current functions, * which is asynchronous and may fail silently without applying the requested changes. *
* * @param functions functions to set, in a bitwise mask. * Must satisfy {@link UsbManager#areSettableFunctions} * * {@hide} */ public void setScreenUnlockedFunctions(long functions) { try { mService.setScreenUnlockedFunctions(functions); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Gets the current screen unlocked functions. * * @return The currently set screen enabled functions. * A zero mask indicates that the screen unlocked functions feature is not enabled. * * {@hide} */ public long getScreenUnlockedFunctions() { try { return mService.getScreenUnlockedFunctions(); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Returns a list of physical USB ports on the device. ** This list is guaranteed to contain all dual-role USB Type C ports but it might * be missing other ports depending on whether the kernel USB drivers have been * updated to publish all of the device's ports through the new "dual_role_usb" * device class (which supports all types of ports despite its name). *
* * @return The list of USB ports, or null if none. * * @hide */ public UsbPort[] getPorts() { if (mService == null) { return null; } try { return mService.getPorts(); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Gets the status of the specified USB port. * * @param port The port to query. * @return The status of the specified USB port, or null if unknown. * * @hide */ public UsbPortStatus getPortStatus(UsbPort port) { Preconditions.checkNotNull(port, "port must not be null"); try { return mService.getPortStatus(port.getId()); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Sets the desired role combination of the port. ** The supported role combinations depend on what is connected to the port and may be * determined by consulting * {@link UsbPortStatus#isRoleCombinationSupported UsbPortStatus.isRoleCombinationSupported}. *
* Note: This function is asynchronous and may fail silently without applying * the requested changes. If this function does cause a status change to occur then * a {@link #ACTION_USB_PORT_CHANGED} broadcast will be sent. *
* * @param powerRole The desired power role: {@link UsbPort#POWER_ROLE_SOURCE} * or {@link UsbPort#POWER_ROLE_SINK}, or 0 if no power role. * @param dataRole The desired data role: {@link UsbPort#DATA_ROLE_HOST} * or {@link UsbPort#DATA_ROLE_DEVICE}, or 0 if no data role. * * @hide */ public void setPortRoles(UsbPort port, int powerRole, int dataRole) { Preconditions.checkNotNull(port, "port must not be null"); UsbPort.checkRoles(powerRole, dataRole); Log.d(TAG, "setPortRoles Package:" + mContext.getPackageName()); try { mService.setPortRoles(port.getId(), powerRole, dataRole); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Sets the component that will handle USB device connection. ** Setting component allows to specify external USB host manager to handle use cases, where * selection dialog for an activity that will handle USB device is undesirable. * Only system components can call this function, as it requires the MANAGE_USB permission. * * @param usbDeviceConnectionHandler The component to handle usb connections, * {@code null} to unset. * * {@hide} */ public void setUsbDeviceConnectionHandler(@Nullable ComponentName usbDeviceConnectionHandler) { try { mService.setUsbDeviceConnectionHandler(usbDeviceConnectionHandler); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } } /** * Returns whether the given functions are valid inputs to UsbManager. * Currently the empty functions or any of MTP, PTP, RNDIS, MIDI are accepted. * * @return Whether the mask is settable. * * {@hide} */ public static boolean areSettableFunctions(long functions) { return functions == FUNCTION_NONE || ((~SETTABLE_FUNCTIONS & functions) == 0 && Long.bitCount(functions) == 1); } /** * Converts the given function mask to string. Maintains ordering with respect to init scripts. * * @return String representation of given mask * * {@hide} */ public static String usbFunctionsToString(long functions) { StringJoiner joiner = new StringJoiner(","); if ((functions & FUNCTION_MTP) != 0) { joiner.add(UsbManager.USB_FUNCTION_MTP); } if ((functions & FUNCTION_PTP) != 0) { joiner.add(UsbManager.USB_FUNCTION_PTP); } if ((functions & FUNCTION_RNDIS) != 0) { joiner.add(UsbManager.USB_FUNCTION_RNDIS); } if ((functions & FUNCTION_MIDI) != 0) { joiner.add(UsbManager.USB_FUNCTION_MIDI); } if ((functions & FUNCTION_ACCESSORY) != 0) { joiner.add(UsbManager.USB_FUNCTION_ACCESSORY); } if ((functions & FUNCTION_AUDIO_SOURCE) != 0) { joiner.add(UsbManager.USB_FUNCTION_AUDIO_SOURCE); } if ((functions & FUNCTION_ADB) != 0) { joiner.add(UsbManager.USB_FUNCTION_ADB); } return joiner.toString(); } /** * Parses a string of usb functions that are comma separated. * * @return A mask of all valid functions in the string * * {@hide} */ public static long usbFunctionsFromString(String functions) { if (functions == null || functions.equals(USB_FUNCTION_NONE)) { return FUNCTION_NONE; } long ret = 0; for (String function : functions.split(",")) { if (FUNCTION_NAME_TO_CODE.containsKey(function)) { ret |= FUNCTION_NAME_TO_CODE.get(function); } else if (function.length() > 0) { throw new IllegalArgumentException("Invalid usb function " + functions); } } return ret; } }