新@SystemApi注释的含义是什么,与@hide的区别是什么？

Question

Android最近在其SDK源代码中引入了@SystemApi.看起来像之前的@hide注释一样有效,因为它们也被从SDK jar类中剥离.

应用程序是否有可能以与旧的@hide API不同的方式调用它们.

/**
 * Indicates an API is exposed for use by bundled system applications.
 * <p>
 * These APIs are not guaranteed to remain consistent release-to-release,
 * and are not for use by apps linking against the Android SDK.
 * </p><p>
 * This annotation should only appear on API that is already marked <pre>@hide</pre>.
 * </p>
 *
 * @hide
 */

Answer 1

@SystemApi,@PrivateApi和@hide

根据这个提交,@SystemApi是旧的重命名@PrivateApi.标记@hide的API 不一定@SystemApi,但@SystemApi需要@hide.

有关@hidejavadoc注释的更多信息,这篇文章给出了一个很好的答案.

基于我自己的实验,一个(非系统应用程序)仍然可以@hide使用Java反射来访问API和字段(来自这篇文章):

WifiManager manager = (WifiManager) getSystemService(Context.WIFI_SERVICE);

WifiConfiguration config = new WifiConfiguration();
config.SSID = "AccessPointSSID";

Method method = manager.getClass().getMethod("setWifiApEnabled", WifiConfiguration.class, boolean.class);
method.invoke(manager, config, true);

但是尝试@SystemApi使用Java反射来访问内容是不可能的(以下代码将触发invocationTargetException):

WifiManager manager = (WifiManager) getSystemService(Context.WIFI_SERVICE);

Method method = manager.getClass().getMethod("getPrivilegedConfiguredNetworks");
List<WifiConfiguration> configs = (List<WifiConfiguration>)method.invoke(manager);

PS

在WifiManagerjava代码中,setWifiApEnabled和getPrivilegedConfiguredNetworksAPI定义为:

/**
 * Start AccessPoint mode with the specified
 * configuration. If the radio is already running in
 * AP mode, update the new configuration
 * Note that starting in access point mode disables station
 * mode operation
 * @param wifiConfig SSID, security and channel details as
 *        part of WifiConfiguration
 * @return {@code true} if the operation succeeds, {@code false} otherwise
 *
 * @hide Dont open up yet
 */
public boolean setWifiApEnabled(WifiConfiguration wifiConfig, boolean enabled) {
    try {
        mService.setWifiApEnabled(wifiConfig, enabled);
        return true;
    } catch (RemoteException e) {
        return false;
    }
}

和

/** @hide */
@SystemApi
public List<WifiConfiguration> getPrivilegedConfiguredNetworks() {
    try {
        return mService.getPrivilegedConfiguredNetworks();
    } catch (RemoteException e) {
        return null;
    }
}

Answer 2

用@SystemApi注释的方法是用@hide注释的方法的子集。这显然是内部团队（也许还有合作伙伴）的一个指标，表明这些方法是实际的 API，但不适合公共开发人员。

这样一来，@SystemApi方法将比@hide方法更加稳定，以后可以随时更改，无需考虑兼容性，并且任何OEM都可以随意更改它们。

如果您尝试通过反射调用内部 API，请始终首选 @SystemApi 方法，以获得更好的未来兼容性。