新@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

根据this commit，@SystemApi是旧@PrivateApi的重命名。标记为@hide的API不一定是@SystemApi，但@SystemApi需要@hide。

有关@hide javadoc注释的详细信息，this post给出了一个很好的答案。

根据我自己的实验，一个（非系统应用程序）仍然可以使用Java反射（来自this post）访问@hide 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);

但是尝试使用Java反射来访问@SystemApi内容 是不可能的（以下代码会触发invocationTargetException）：

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

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

P.S。

在WifiManager java code中，setWifiApEnabled和getPrivilegedConfiguredNetworks API定义为：

/**
 * 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方法以获得更好的未来兼容性。