android.annotation.SystemApi Java Examples

/**
 * Request an immediate backup, providing an observer to which results of the backup operation
 * will be published. The Android backup system will decide for each package whether it will
 * be full app data backup or key/value-pair-based backup.
 *
 * <p>If this method returns {@link BackupManager#SUCCESS}, the OS will attempt to backup all
 * provided packages using the remote transport.
 *
 * @param packages List of package names to backup.
 * @param observer The {@link BackupObserver} to receive callbacks during the backup
 *                 operation. Could be {@code null}.
 * @param monitor  The {@link BackupManagerMonitorWrapper} to receive callbacks of important
 *                 events during the backup operation. Could be {@code null}.
 * @param flags    {@link #FLAG_NON_INCREMENTAL_BACKUP}.
 * @return {@link BackupManager#SUCCESS} on success; nonzero on error.
 * @throws IllegalArgumentException on null or empty {@code packages} param.
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BACKUP)
public int requestBackup(String[] packages, BackupObserver observer,
        BackupManagerMonitor monitor, int flags) {
    checkServiceBinder();
    if (sService != null) {
        try {
            BackupObserverWrapper observerWrapper = observer == null
                    ? null
                    : new BackupObserverWrapper(mContext, observer);
            BackupManagerMonitorWrapper monitorWrapper = monitor == null
                    ? null
                    : new BackupManagerMonitorWrapper(monitor);
            return sService.requestBackup(packages, observerWrapper, monitorWrapper, flags);
        } catch (RemoteException e) {
            Log.e(TAG, "requestBackup() couldn't connect");
        }
    }
    return -1;
}
 

/**
 * Checks the byte array of timer record source.
 * @param sourcetype
 * @param recordSource
 * @hide
 */
@SystemApi
public static boolean checkTimerRecordSource(int sourcetype, byte[] recordSource) {
    int recordSourceSize = recordSource.length - TimerInfo.BASIC_INFO_SIZE;
    switch (sourcetype) {
        case TIMER_RECORDING_TYPE_DIGITAL:
            return DigitalServiceSource.EXTRA_DATA_SIZE == recordSourceSize;
        case TIMER_RECORDING_TYPE_ANALOGUE:
            return AnalogueServiceSource.EXTRA_DATA_SIZE == recordSourceSize;
        case TIMER_RECORDING_TYPE_EXTERNAL:
            int specifier = recordSource[TimerInfo.BASIC_INFO_SIZE];
            if (specifier == EXTERNAL_SOURCE_SPECIFIER_EXTERNAL_PLUG) {
                // One byte for specifier.
                return ExternalPlugData.EXTRA_DATA_SIZE + 1 == recordSourceSize;
            } else if (specifier == EXTERNAL_SOURCE_SPECIFIER_EXTERNAL_PHYSICAL_ADDRESS) {
                // One byte for specifier.
                return ExternalPhysicalAddress.EXTRA_DATA_SIZE + 1 == recordSourceSize;
            } else {
                // Invalid specifier.
                return false;
            }
        default:
            return false;
    }
}
 

/**
 * Gets the list of print services, but does not register for updates. The user has to register
 * for updates by itself, or use {@link PrintServicesLoader}.
 *
 * @param selectionFlags flags selecting which services to get. Either
 *                       {@link #ENABLED_SERVICES},{@link #DISABLED_SERVICES}, or both.
 *
 * @return The print service list or an empty list.
 *
 * @see #addPrintServicesChangeListener(PrintServicesChangeListener, Handler)
 * @see #removePrintServicesChangeListener(PrintServicesChangeListener)
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.READ_PRINT_SERVICES)
public @NonNull List<PrintServiceInfo> getPrintServices(int selectionFlags) {
    Preconditions.checkFlagsArgument(selectionFlags, ALL_SERVICES);

    try {
        List<PrintServiceInfo> services = mService.getPrintServices(selectionFlags, mUserId);
        if (services != null) {
            return services;
        }
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
    return Collections.emptyList();
}
 

/**
 * Begin the process of restoring data from backup.  See the
 * {@link android.app.backup.RestoreSession} class for documentation on that process.
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BACKUP)
public RestoreSession beginRestoreSession() {
    RestoreSession session = null;
    checkServiceBinder();
    if (sService != null) {
        try {
            // All packages, current transport
            IRestoreSession binder = sService.beginRestoreSession(null, null);
            if (binder != null) {
                session = new RestoreSession(mContext, binder);
            }
        } catch (RemoteException e) {
            Log.e(TAG, "beginRestoreSession() couldn't connect");
        }
    }
    return session;
}
 

/**
 * {@hide}
 * Returns the current standby bucket of every app that has a bucket assigned to it.
 * The caller must hold the permission android.permission.PACKAGE_USAGE_STATS. The key of the
 * returned Map is the package name and the value is the bucket assigned to the package.
 * @see #getAppStandbyBucket()
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.PACKAGE_USAGE_STATS)
public Map<String, Integer> getAppStandbyBuckets() {
    try {
        final ParceledListSlice<AppStandbyInfo> slice = mService.getAppStandbyBuckets(
                mContext.getOpPackageName(), mContext.getUserId());
        final List<AppStandbyInfo> bucketList = slice.getList();
        final ArrayMap<String, Integer> bucketMap = new ArrayMap<>();
        final int n = bucketList.size();
        for (int i = 0; i < n; i++) {
            final AppStandbyInfo bucketInfo = bucketList.get(i);
            bucketMap.put(bucketInfo.mPackageName, bucketInfo.mStandbyBucket);
        }
        return bucketMap;
    } catch (RemoteException e) {
        throw e.rethrowFromSystemServer();
    }
}
 

/**
 * Set priority of the profile
 *
 * <p> The device should already be paired.
 * Priority can be one of {@link BluetoothProfile#PRIORITY_ON} or
 * {@link BluetoothProfile#PRIORITY_OFF},
 *
 * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
 * permission.
 *
 * @param device Paired bluetooth device
 * @param priority
 * @return true if priority is set, false on error
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BLUETOOTH_ADMIN)
public boolean setPriority(BluetoothDevice device, int priority) {
    if (DBG) log("setPriority(" + device + ", " + priority + ")");
    final IBluetoothHeadset service = mService;
    if (service != null && isEnabled() && isValidDevice(device)) {
        if (priority != BluetoothProfile.PRIORITY_OFF
                && priority != BluetoothProfile.PRIORITY_ON) {
            return false;
        }
        try {
            return service.setPriority(device, priority);
        } catch (RemoteException e) {
            Log.e(TAG, Log.getStackTraceString(new Throwable()));
            return false;
        }
    }
    if (service == null) Log.w(TAG, "Proxy not attached to service");
    return false;
}
 

/**
 * Report whether the backup mechanism is currently active.
 * When it is inactive, the device will not perform any backup operations, nor will it
 * deliver data for restore, although clients can still safely call BackupManager methods.
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BACKUP)
public boolean isBackupServiceActive(UserHandle user) {
    mContext.enforceCallingOrSelfPermission(android.Manifest.permission.BACKUP,
            "isBackupServiceActive");
    checkServiceBinder();
    if (sService != null) {
        try {
            return sService.isBackupServiceActive(user.getIdentifier());
        } catch (RemoteException e) {
            Log.e(TAG, "isBackupEnabled() couldn't connect");
        }
    }
    return false;
}
 

/**
 * Remove an importance listener that was previously registered with
 * {@link #addOnUidImportanceListener}.
 *
 * @throws IllegalArgumentException If the listener is not registered.
 * @hide
 */
@SystemApi @TestApi
@RequiresPermission(Manifest.permission.PACKAGE_USAGE_STATS)
public void removeOnUidImportanceListener(OnUidImportanceListener listener) {
    synchronized (this) {
        UidObserver observer = mImportanceListeners.remove(listener);
        if (observer == null) {
            throw new IllegalArgumentException("Listener not registered: " + listener);
        }
        try {
            getService().unregisterUidObserver(observer);
        } catch (RemoteException e) {
            throw e.rethrowFromSystemServer();
        }
    }
}
 

/**
 * Gets the global display brightness configuration or the default curve if one hasn't been set.
 *
 * @hide
 */
@SystemApi
@TestApi
@RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS)
public BrightnessConfiguration getBrightnessConfiguration() {
    return getBrightnessConfigurationForUser(mContext.getUserId());
}
 

/**
 * Listen for changes to the print service recommendations.
 *
 * @param listener the listener to add
 * @param handler the handler the listener is called back on
 *
 * @see android.print.PrintManager#getPrintServiceRecommendations
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.READ_PRINT_SERVICE_RECOMMENDATIONS)
public void addPrintServiceRecommendationsChangeListener(
        @NonNull PrintServiceRecommendationsChangeListener listener,
        @Nullable Handler handler) {
    Preconditions.checkNotNull(listener);

    if (handler == null) {
        handler = mHandler;
    }

    if (mService == null) {
        Log.w(LOG_TAG, "Feature android.software.print not available");
        return;
    }
    if (mPrintServiceRecommendationsChangeListeners == null) {
        mPrintServiceRecommendationsChangeListeners = new ArrayMap<>();
    }
    PrintServiceRecommendationsChangeListenerWrapper wrappedListener =
            new PrintServiceRecommendationsChangeListenerWrapper(listener, handler);
    try {
        mService.addPrintServiceRecommendationsChangeListener(wrappedListener, mUserId);
        mPrintServiceRecommendationsChangeListeners.put(listener, wrappedListener);
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
}
 

@SystemApi
public static String stateToString(int state) {
    if (state == STATE_FALSE) return "STATE_FALSE";
    if (state == STATE_TRUE) return "STATE_TRUE";
    if (state == STATE_UNKNOWN) return "STATE_UNKNOWN";
    if (state == STATE_ERROR) return "STATE_ERROR";
    throw new IllegalArgumentException("state is invalid: " + state);
}
 

/**
 * Listen for changes to the installed and enabled print services.
 *
 * @param listener the listener to add
 * @param handler the handler the listener is called back on
 *
 * @see android.print.PrintManager#getPrintServices
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.READ_PRINT_SERVICES)
public void addPrintServicesChangeListener(@NonNull PrintServicesChangeListener listener,
        @Nullable Handler handler) {
    Preconditions.checkNotNull(listener);

    if (handler == null) {
        handler = mHandler;
    }

    if (mService == null) {
        Log.w(LOG_TAG, "Feature android.software.print not available");
        return;
    }
    if (mPrintServicesChangeListeners == null) {
        mPrintServicesChangeListeners = new ArrayMap<>();
    }
    PrintServicesChangeListenerWrapper wrappedListener =
            new PrintServicesChangeListenerWrapper(listener, handler);
    try {
        mService.addPrintServicesChangeListener(wrappedListener, mUserId);
        mPrintServicesChangeListeners.put(listener, wrappedListener);
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
}
 

/**
 * The internal version of the constructor that doesn't perform arguments checks.
 * @hide
 */
@SystemApi
public WebResourceResponse(boolean immutable, String mimeType, String encoding, int statusCode,
        String reasonPhrase, Map<String, String> responseHeaders, InputStream data) {
    mImmutable = immutable;
    mMimeType = mimeType;
    mEncoding = encoding;
    mStatusCode = statusCode;
    mReasonPhrase = reasonPhrase;
    mResponseHeaders = responseHeaders;
    mInputStream = data;
}
 

/**
 * Enable/disable data restore at application install time.  When enabled, app
 * installation will include an attempt to fetch the app's historical data from
 * the archival restore dataset (if any).  When disabled, no such attempt will
 * be made.
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BACKUP)
public void setAutoRestore(boolean isEnabled) {
    checkServiceBinder();
    if (sService != null) {
        try {
            sService.setAutoRestore(isEnabled);
        } catch (RemoteException e) {
            Log.e(TAG, "setAutoRestore() couldn't connect");
        }
    }
}
 

/**
 * Returns whether the caller is running as restricted profile. Restricted profile may have
 * a reduced number of available apps, app restrictions and account restrictions.
 * @return whether the user making this call is a linked user
 * @hide
 */
@SystemApi
public boolean isRestrictedProfile() {
    try {
        return mService.isRestricted();
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
}
 

/**
 * Stop listening for changes to the print service recommendations.
 *
 * @param listener the listener to remove
 *
 * @see android.print.PrintManager#getPrintServiceRecommendations
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.READ_PRINT_SERVICE_RECOMMENDATIONS)
public void removePrintServiceRecommendationsChangeListener(
        @NonNull PrintServiceRecommendationsChangeListener listener) {
    Preconditions.checkNotNull(listener);

    if (mService == null) {
        Log.w(LOG_TAG, "Feature android.software.print not available");
        return;
    }
    if (mPrintServiceRecommendationsChangeListeners == null) {
        return;
    }
    PrintServiceRecommendationsChangeListenerWrapper wrappedListener =
            mPrintServiceRecommendationsChangeListeners.remove(listener);
    if (wrappedListener == null) {
        return;
    }
    if (mPrintServiceRecommendationsChangeListeners.isEmpty()) {
        mPrintServiceRecommendationsChangeListeners = null;
    }
    wrappedListener.destroy();
    try {
        mService.removePrintServiceRecommendationsChangeListener(wrappedListener, mUserId);
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
}
 

/**
 * Return the importance of a given uid, based on the processes that are
 * currently running.  The return value is one of the importance constants defined
 * in {@link RunningAppProcessInfo}, giving you the highest importance of all the
 * processes that this uid has running.  If there are no processes
 * running its code, {@link RunningAppProcessInfo#IMPORTANCE_GONE} is returned.
 * @hide
 */
@SystemApi @TestApi
@RequiresPermission(Manifest.permission.PACKAGE_USAGE_STATS)
public @RunningAppProcessInfo.Importance int getUidImportance(int uid) {
    try {
        int procState = getService().getUidProcessState(uid,
                mContext.getOpPackageName());
        return RunningAppProcessInfo.procStateToImportanceForClient(procState, mContext);
    } catch (RemoteException e) {
        throw e.rethrowFromSystemServer();
    }
}
 

/**
 * Disable NFC hardware.
 * @hide
*/
@SystemApi
@RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS)
public boolean disable(boolean persist) {
    try {
        return sService.disable(persist);
    } catch (RemoteException e) {
        attemptDeadServiceRecovery(e);
        return false;
    }
}
 

/**
 * Runs tether provisioning for the given type if needed and then starts tethering if
 * the check succeeds. If no carrier provisioning is required for tethering, tethering is
 * enabled immediately. If provisioning fails, tethering will not be enabled. It also
 * schedules tether provisioning re-checks if appropriate.
 *
 * @param type The type of tethering to start. Must be one of
 *         {@link ConnectivityManager.TETHERING_WIFI},
 *         {@link ConnectivityManager.TETHERING_USB}, or
 *         {@link ConnectivityManager.TETHERING_BLUETOOTH}.
 * @param showProvisioningUi a boolean indicating to show the provisioning app UI if there
 *         is one. This should be true the first time this function is called and also any time
 *         the user can see this UI. It gives users information from their carrier about the
 *         check failing and how they can sign up for tethering if possible.
 * @param callback an {@link OnStartTetheringCallback} which will be called to notify the caller
 *         of the result of trying to tether.
 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked.
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED)
public void startTethering(int type, boolean showProvisioningUi,
        final OnStartTetheringCallback callback, Handler handler) {
    Preconditions.checkNotNull(callback, "OnStartTetheringCallback cannot be null.");

    ResultReceiver wrappedCallback = new ResultReceiver(handler) {
        @Override
        protected void onReceiveResult(int resultCode, Bundle resultData) {
            if (resultCode == TETHER_ERROR_NO_ERROR) {
                callback.onTetheringStarted();
            } else {
                callback.onTetheringFailed();
            }
        }
    };

    try {
        String pkgName = mContext.getOpPackageName();
        Log.i(TAG, "startTethering caller:" + pkgName);
        mService.startTethering(type, wrappedCallback, showProvisioningUi, pkgName);
    } catch (RemoteException e) {
        Log.e(TAG, "Exception trying to start tethering.", e);
        wrappedCallback.send(TETHER_ERROR_SERVICE_UNAVAIL, null);
    }
}
 

/** @hide */
@SystemApi
public BackupDataInput(FileDescriptor fd) {
    if (fd == null) throw new NullPointerException();
    mBackupReader = ctor(fd);
    if (mBackupReader == 0) {
        throw new RuntimeException("Native initialization failed with fd=" + fd);
    }
}
 

/**
 * Request one or more notifications by key. Useful if you have been keeping track of
 * notifications but didn't want to retain the bits, and now need to go back and extract
 * more data out of those notifications.
 *
 * @hide
 * @removed
 *
 * @param keys the keys of the notifications to request
 * @param trim trim of the notifications to be returned. See <code>TRIM_*</code> constants.
 * @return An array of notifications corresponding to the requested keys, in the
 * same order as the key list.
 */
@SystemApi
public StatusBarNotification[] getActiveNotifications(String[] keys, int trim) {
    if (!isBound())
        return null;
    try {
        ParceledListSlice<StatusBarNotification> parceledList = getNotificationInterface()
                .getActiveNotificationsFromListener(mWrapper, keys, trim);
        return cleanUpNotificationList(parceledList);
    } catch (android.os.RemoteException ex) {
        Log.v(TAG, "Unable to contact notification manager", ex);
    }
    return null;
}
 

/** @hide */
@SystemApi
@RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS)
public void set(@AlarmType int type, long triggerAtMillis, long windowMillis,
        long intervalMillis, PendingIntent operation, WorkSource workSource) {
    setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, operation, null, null,
            null, workSource, null);
}
 

/**
 * Report whether the backup mechanism is currently enabled.
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.BACKUP)
public boolean isBackupEnabled() {
    checkServiceBinder();
    if (sService != null) {
        try {
            return sService.isBackupEnabled();
        } catch (RemoteException e) {
            Log.e(TAG, "isBackupEnabled() couldn't connect");
        }
    }
    return false;
}
 

/**
 * Create a new {@code WorkChain} associated with this WorkSource and return it.
 *
 * @hide
 */
@SystemApi
public WorkChain createWorkChain() {
    if (mChains == null) {
        mChains = new ArrayList<>(4);
    }

    final WorkChain wc = new WorkChain();
    mChains.add(wc);

    return wc;
}
 

/**
 * Gets the URL that should be used for resolving whether a captive portal is present.
 * 1. This URL should respond with a 204 response to a GET request to indicate no captive
 *    portal is present.
 * 2. This URL must be HTTP as redirect responses are used to find captive portal
 *    sign-in pages. Captive portals cannot respond to HTTPS requests with redirects.
 *
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.LOCAL_MAC_ADDRESS)
public String getCaptivePortalServerUrl() {
    try {
        return mService.getCaptivePortalServerUrl();
    } catch (RemoteException e) {
        throw e.rethrowFromSystemServer();
    }
}
 

/**
 * Stops tethering for the given type. Also cancels any provisioning rechecks for that type if
 * applicable.
 *
 * @param type The type of tethering to stop. Must be one of
 *         {@link ConnectivityManager.TETHERING_WIFI},
 *         {@link ConnectivityManager.TETHERING_USB}, or
 *         {@link ConnectivityManager.TETHERING_BLUETOOTH}.
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED)
public void stopTethering(int type) {
    try {
        String pkgName = mContext.getOpPackageName();
        Log.i(TAG, "stopTethering caller:" + pkgName);
        mService.stopTethering(type, pkgName);
    } catch (RemoteException e) {
        throw e.rethrowFromSystemServer();
    }
}
 

/**
 * Returns serial numbers of all users on this device.
 *
 * @param excludeDying specify if the list should exclude users being removed.
 * @return the list of serial numbers of users that exist on the device.
 * @hide
 */
@SystemApi
@RequiresPermission(android.Manifest.permission.MANAGE_USERS)
public long[] getSerialNumbersOfUsers(boolean excludeDying) {
    try {
        List<UserInfo> users = mService.getUsers(excludeDying);
        long[] result = new long[users.size()];
        for (int i = 0; i < result.length; i++) {
            result[i] = users.get(i).serialNumber;
        }
        return result;
    } catch (RemoteException re) {
        throw re.rethrowFromSystemServer();
    }
}
 

/** {@hide}
 */
@SystemApi
public abstract void bulkRequestIconForPageUrl(ContentResolver cr, String where,
        IconListener listener);
 

/**
 * Equivalent to {@code bind(callback, null)}.
 */
@SystemApi
public boolean bind(final UpdateEngineCallback callback) {
    return bind(callback, null);
}
 

/**
 * @return true if this UserHandle refers to the system user; false otherwise.
 * @hide
 */
@SystemApi
public boolean isSystem() {
    return this.equals(SYSTEM);
}