content: /*
   * Copyright (C) 2018 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.annotation;
  
  import static java.lang.annotation.ElementType.CONSTRUCTOR;
  import static java.lang.annotation.ElementType.FIELD;
  import static java.lang.annotation.ElementType.METHOD;
  import static java.lang.annotation.ElementType.TYPE;
  import static java.lang.annotation.RetentionPolicy.CLASS;
  
  import java.lang.annotation.Repeatable;
  import java.lang.annotation.Retention;
  import java.lang.annotation.Target;
  
  /**
   * Indicates that this non-SDK interface is used by apps. A non-SDK interface is a
   * class member (field or method) that is not part of the public SDK. Since the
   * member is not part of the SDK, usage by apps is not supported.
   *
   * <h2>If you are an Android App developer</h2>
   *
   * This annotation indicates that you may be able to access the member, but that
   * this access is discouraged and not supported by Android. If there is a value
   * for {@link #maxTargetSdk()} on the annotation, access will be restricted based
   * on the {@code targetSdkVersion} value set in your manifest.
   *
   * <p>Fields and methods annotated with this are likely to be restricted, changed
   * or removed in future Android releases. If you rely on these members for
   * functionality that is not otherwise supported by Android, consider filing a
   * <a href="http://g.co/dev/appcompat">feature request</a>.
   *
   * <h2>If you are an Android OS developer</h2>
   *
   * This annotation acts as a heads up that changing a given method or field
   * may affect apps, potentially breaking them when the next Android version is
   * released. In some cases, for members that are heavily used, this annotation
   * may imply restrictions on changes to the member.
   *
   * <p>This annotation also results in access to the member being permitted by the
   * runtime, with a warning being generated in debug builds. Which apps can access
   * the member is determined by the value of {@link #maxTargetSdk()}.
   *
   * <p>For more details, see go/UnsupportedAppUsage.
   *
   * {@hide}
   */
  @Retention(CLASS)
  @Target({CONSTRUCTOR, METHOD, FIELD, TYPE})
  @Repeatable(UnsupportedAppUsage.Container.class)
  public @interface UnsupportedAppUsage {
  
      /**
       * Associates a bug tracking the work to add a public alternative to this API. Optional.
       *
       * @return ID of the associated tracking bug
       */
      long trackingBug() default 0;
  
      /**
       * Indicates that usage of this API is limited to apps based on their target SDK version.
       *
       * <p>Access to the API is allowed if the targetSdkVersion in the apps manifest is no greater
       * than this value. Access checks are performed at runtime.
       *
       * <p>This is used to give app developers a grace period to migrate off a non-SDK interface.
       * When making Android version N, existing APIs can have a maxTargetSdk of N-1 added to them.
       * Developers must then migrate off the API when their app is updated in future, but it will
       * continue working in the meantime.
       *
       * <p>Possible values are:
       * <ul>
       *     <li>
       *         {@link android.os.Build.VERSION_CODES#O} or {@link android.os.Build.VERSION_CODES#P},
       *         to limit access to apps targeting these SDKs (or earlier).
       *     </li>
       *     <li>
       *         absent (default value) - All apps can access this API, but doing so may result in
       *         warnings in the log, UI warnings (on developer builds) and/or strictmode violations.
       *         The API is likely to be further restricted in future.
       *     </li>
       *
       * </ul>
       *
       * Note, if this is set to {@link android.os.Build.VERSION_CODES#O}, apps targeting O
       * maintenance releases will also be allowed to use the API, and similarly for any future
       * maintenance releases of P.
       *
       * @return The maximum value for an apps targetSdkVersion in order to access this API.
       */
      int maxTargetSdk() default Integer.MAX_VALUE;
  
      /**
       * For debug use only. The expected dex signature to be generated for this API, used to verify
       * parts of the build process.
       *
       * @return A dex API signature.
       */
      String expectedSignature() default "";
  
      /**
       * The signature of an implicit (not present in the source) member that forms part of the
       * hiddenapi.
       *
       * <p>Allows access to non-SDK API elements that are not represented in the input source to be
       * managed.
       *
       * <p>This must only be used when applying the annotation to a type, using it in any other
       * situation is an error.
       *
       * @return A dex API signature.
       */
      String implicitMember() default "";
  
      /**
       * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types.
       */
      @Retention(CLASS)
      @Target(TYPE)
      @interface Container {
          UnsupportedAppUsage[] value();
      }
  }
  