android-35/android/content/ContextParams.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * Copyright (C) 2021 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.content;

 import static android.permission.flags.Flags.FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE;

 import android.Manifest;
 import android.annotation.FlaggedApi;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
 import android.annotation.SystemApi;
 import android.app.ActivityThread;
 import android.content.pm.PackageManager;

 import java.util.Collections;
 import java.util.Objects;
 import java.util.Set;

 /**
  * This class represents rules around how a context being created via
  * {@link Context#createContext} should behave.
  *
  * <p>One of the dimensions to customize is how permissions should behave.
  * For example, you can specify how permission accesses from a context should
  * be attributed in the platform's permission tracking system.
  *
  * <p>The two main types of attribution are: against an attribution tag which
  * is an arbitrary string your app specifies for the purposes of tracking permission
  * accesses from a given portion of your app; against another package and optionally
  * its attribution tag if you are accessing the data on behalf of another app and
  * you will be passing that data to this app, recursively. Both attributions are
  * not mutually exclusive.
  *
  * @see Context#createContext(ContextParams)
  * @see AttributionSource
  */
 public final class ContextParams {
     private final @Nullable String mAttributionTag;
     private final @Nullable AttributionSource mNext;
     private final @NonNull Set<String> mRenouncedPermissions;
     private final boolean mShouldRegisterAttributionSource;

     /** {@hide} */
     public static final ContextParams EMPTY = new ContextParams.Builder().build();

     private ContextParams(@Nullable String attributionTag,
             @Nullable AttributionSource next,
             @Nullable Set<String> renouncedPermissions,
             boolean shouldRegister) {
         mAttributionTag = attributionTag;
         mNext = next;
         mRenouncedPermissions = (renouncedPermissions != null)
                 ? renouncedPermissions : Collections.emptySet();
         mShouldRegisterAttributionSource = shouldRegister;
     }

     /**
      * @return The attribution tag.
      */
     @Nullable
     public String getAttributionTag() {
         return mAttributionTag;
     }

     /**
      * @return The set of permissions to treat as renounced.
      * @hide
      */
     @SystemApi
     @RequiresPermission(android.Manifest.permission.RENOUNCE_PERMISSIONS)
     public @NonNull Set<String> getRenouncedPermissions() {
         return mRenouncedPermissions;
     }

     /** @hide */
     public boolean isRenouncedPermission(@NonNull String permission) {
         return mRenouncedPermissions.contains(permission);
     }

     /**
      * @return The receiving attribution source.
      */
     @Nullable
     public AttributionSource getNextAttributionSource() {
         return mNext;
     }

     /**
      * @return Whether the attribution source associated with the Context being created should be
      * registered.
      */
     @NonNull
     @FlaggedApi(FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE)
     public boolean shouldRegisterAttributionSource() {
         return mShouldRegisterAttributionSource;
     }

     /**
      * Builder for creating a {@link ContextParams}.
      */
     public static final class Builder {
         private @Nullable String mAttributionTag;
         private @NonNull Set<String> mRenouncedPermissions = Collections.emptySet();
         private @Nullable AttributionSource mNext;
         private boolean mShouldRegisterAttributionSource;

         /**
          * Create a new builder.
          * <p>
          * This is valuable when you are interested in having explicit control
          * over every sub-parameter, and don't want to inherit any values from
          * an existing Context.
          * <p>
          * Developers should strongly consider using
          * {@link #Builder(ContextParams)} instead of this constructor, since
          * that will will automatically inherit any new sub-parameters added in
          * future platform releases.
          */
         public Builder() {
         }

         /**
          * Create a new builder that inherits all sub-parameters by default.
          * <p>
          * This is valuable when you are only interested in overriding specific
          * sub-parameters, and want to preserve all other parameters. Setting a
          * specific sub-parameter on the returned builder will override any
          * inherited value.
          */
         public Builder(@NonNull ContextParams params) {
             Objects.requireNonNull(params);
             mAttributionTag = params.mAttributionTag;
             mRenouncedPermissions = params.mRenouncedPermissions;
             mNext = params.mNext;
         }

         /**
          * Sets an attribution tag against which to track permission accesses.
          *
          * @param attributionTag The attribution tag.
          * @return This builder.
          */
         @NonNull
         public Builder setAttributionTag(@Nullable String attributionTag) {
             mAttributionTag = attributionTag;
             return this;
         }

         /**
          * Sets the attribution source for the app on whose behalf you are doing the work.
          *
          * @param next The permission identity of the receiving app.
          * @return This builder.
          *
          * @see AttributionSource
          */
         @NonNull
         public Builder setNextAttributionSource(@Nullable AttributionSource next) {
             mNext = next;
             return this;
         }

         /**
          * Sets whether the attribution source associated with the context created from these params
          * should be registered.
          *
          * @param shouldRegister Whether the attribution source associated with the Context being
          *                       created should be registered.
          */
         @NonNull
         @FlaggedApi(FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE)
         public Builder setShouldRegisterAttributionSource(boolean shouldRegister) {
             mShouldRegisterAttributionSource = shouldRegister;
             return this;
         }

         /**
          * Sets permissions which have been voluntarily "renounced" by the
          * calling app.
          * <p>
          * Interactions performed through services obtained from the created
          * Context will ideally be treated as if these "renounced" permissions
          * have not actually been granted to the app, regardless of their actual
          * grant status.
          * <p>
          * This is designed for use by separate logical components within an app
          * which have no intention of interacting with data or services that are
          * protected by the renounced permissions.
          * <p>
          * Note that only {@link PermissionInfo#PROTECTION_DANGEROUS}
          * permissions are supported by this mechanism. Additionally, this
          * mechanism only applies to calls made through services obtained via
          * {@link Context#getSystemService}; it has no effect on static or raw
          * Binder calls.
          *
          * @param renouncedPermissions The set of permissions to treat as
          *            renounced, which is as if not granted.
          * @return This builder.
          * @hide
          */
         @SystemApi
         @RequiresPermission(android.Manifest.permission.RENOUNCE_PERMISSIONS)
         public @NonNull Builder setRenouncedPermissions(
                 @Nullable Set<String> renouncedPermissions) {
             // This is not a security check but a fail fast - the OS enforces the permission too
             if (renouncedPermissions != null && !renouncedPermissions.isEmpty()
                     && ActivityThread.currentApplication().checkSelfPermission(Manifest.permission
                     .RENOUNCE_PERMISSIONS) != PackageManager.PERMISSION_GRANTED) {
                 throw new SecurityException("Renouncing permissions requires: "
                         + Manifest.permission.RENOUNCE_PERMISSIONS);
             }
             mRenouncedPermissions = renouncedPermissions;
             return this;
         }

         /**
          * Creates a new instance.
          *
          * @return The new instance.
          */
         @NonNull
         public ContextParams build() {
             return new ContextParams(mAttributionTag, mNext,
                     mRenouncedPermissions, mShouldRegisterAttributionSource);
         }
     }
 }
	/*
	* Copyright (C) 2021 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.content;

	import static android.permission.flags.Flags.FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE;

	import android.Manifest;
	import android.annotation.FlaggedApi;
	import android.annotation.NonNull;
	import android.annotation.Nullable;
	import android.annotation.RequiresPermission;
	import android.annotation.SystemApi;
	import android.app.ActivityThread;
	import android.content.pm.PackageManager;

	import java.util.Collections;
	import java.util.Objects;
	import java.util.Set;

	/**
	* This class represents rules around how a context being created via
	* {@link Context#createContext} should behave.
	*
	* <p>One of the dimensions to customize is how permissions should behave.
	* For example, you can specify how permission accesses from a context should
	* be attributed in the platform's permission tracking system.
	*
	* <p>The two main types of attribution are: against an attribution tag which
	* is an arbitrary string your app specifies for the purposes of tracking permission
	* accesses from a given portion of your app; against another package and optionally
	* its attribution tag if you are accessing the data on behalf of another app and
	* you will be passing that data to this app, recursively. Both attributions are
	* not mutually exclusive.
	*
	* @see Context#createContext(ContextParams)
	* @see AttributionSource
	*/
	public final class ContextParams {
	private final @Nullable String mAttributionTag;
	private final @Nullable AttributionSource mNext;
	private final @NonNull Set<String> mRenouncedPermissions;
	private final boolean mShouldRegisterAttributionSource;

	/** {@hide} */
	public static final ContextParams EMPTY = new ContextParams.Builder().build();

	private ContextParams(@Nullable String attributionTag,
	@Nullable AttributionSource next,
	@Nullable Set<String> renouncedPermissions,
	boolean shouldRegister) {
	mAttributionTag = attributionTag;
	mNext = next;
	mRenouncedPermissions = (renouncedPermissions != null)
	? renouncedPermissions : Collections.emptySet();
	mShouldRegisterAttributionSource = shouldRegister;
	}

	/**
	* @return The attribution tag.
	*/
	@Nullable
	public String getAttributionTag() {
	return mAttributionTag;
	}

	/**
	* @return The set of permissions to treat as renounced.
	* @hide
	*/
	@SystemApi
	@RequiresPermission(android.Manifest.permission.RENOUNCE_PERMISSIONS)
	public @NonNull Set<String> getRenouncedPermissions() {
	return mRenouncedPermissions;
	}

	/** @hide */
	public boolean isRenouncedPermission(@NonNull String permission) {
	return mRenouncedPermissions.contains(permission);
	}

	/**
	* @return The receiving attribution source.
	*/
	@Nullable
	public AttributionSource getNextAttributionSource() {
	return mNext;
	}

	/**
	* @return Whether the attribution source associated with the Context being created should be
	* registered.
	*/
	@NonNull
	@FlaggedApi(FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE)
	public boolean shouldRegisterAttributionSource() {
	return mShouldRegisterAttributionSource;
	}

	/**
	* Builder for creating a {@link ContextParams}.
	*/
	public static final class Builder {
	private @Nullable String mAttributionTag;
	private @NonNull Set<String> mRenouncedPermissions = Collections.emptySet();
	private @Nullable AttributionSource mNext;
	private boolean mShouldRegisterAttributionSource;

	/**
	* Create a new builder.
	* <p>
	* This is valuable when you are interested in having explicit control
	* over every sub-parameter, and don't want to inherit any values from
	* an existing Context.
	* <p>
	* Developers should strongly consider using
	* {@link #Builder(ContextParams)} instead of this constructor, since
	* that will will automatically inherit any new sub-parameters added in
	* future platform releases.
	*/
	public Builder() {
	}

	/**
	* Create a new builder that inherits all sub-parameters by default.
	* <p>
	* This is valuable when you are only interested in overriding specific
	* sub-parameters, and want to preserve all other parameters. Setting a
	* specific sub-parameter on the returned builder will override any
	* inherited value.
	*/
	public Builder(@NonNull ContextParams params) {
	Objects.requireNonNull(params);
	mAttributionTag = params.mAttributionTag;
	mRenouncedPermissions = params.mRenouncedPermissions;
	mNext = params.mNext;
	}

	/**
	* Sets an attribution tag against which to track permission accesses.
	*
	* @param attributionTag The attribution tag.
	* @return This builder.
	*/
	@NonNull
	public Builder setAttributionTag(@Nullable String attributionTag) {
	mAttributionTag = attributionTag;
	return this;
	}

	/**
	* Sets the attribution source for the app on whose behalf you are doing the work.
	*
	* @param next The permission identity of the receiving app.
	* @return This builder.
	*
	* @see AttributionSource
	*/
	@NonNull
	public Builder setNextAttributionSource(@Nullable AttributionSource next) {
	mNext = next;
	return this;
	}

	/**
	* Sets whether the attribution source associated with the context created from these params
	* should be registered.
	*
	* @param shouldRegister Whether the attribution source associated with the Context being
	* created should be registered.
	*/
	@NonNull
	@FlaggedApi(FLAG_SHOULD_REGISTER_ATTRIBUTION_SOURCE)
	public Builder setShouldRegisterAttributionSource(boolean shouldRegister) {
	mShouldRegisterAttributionSource = shouldRegister;
	return this;
	}

	/**
	* Sets permissions which have been voluntarily "renounced" by the
	* calling app.
	* <p>
	* Interactions performed through services obtained from the created
	* Context will ideally be treated as if these "renounced" permissions
	* have not actually been granted to the app, regardless of their actual
	* grant status.
	* <p>
	* This is designed for use by separate logical components within an app
	* which have no intention of interacting with data or services that are
	* protected by the renounced permissions.
	* <p>
	* Note that only {@link PermissionInfo#PROTECTION_DANGEROUS}
	* permissions are supported by this mechanism. Additionally, this
	* mechanism only applies to calls made through services obtained via
	* {@link Context#getSystemService}; it has no effect on static or raw
	* Binder calls.
	*
	* @param renouncedPermissions The set of permissions to treat as
	* renounced, which is as if not granted.
	* @return This builder.
	* @hide
	*/
	@SystemApi
	@RequiresPermission(android.Manifest.permission.RENOUNCE_PERMISSIONS)
	public @NonNull Builder setRenouncedPermissions(
	@Nullable Set<String> renouncedPermissions) {
	// This is not a security check but a fail fast - the OS enforces the permission too
	if (renouncedPermissions != null && !renouncedPermissions.isEmpty()
	&& ActivityThread.currentApplication().checkSelfPermission(Manifest.permission
	.RENOUNCE_PERMISSIONS) != PackageManager.PERMISSION_GRANTED) {
	throw new SecurityException("Renouncing permissions requires: "
	+ Manifest.permission.RENOUNCE_PERMISSIONS);
	}
	mRenouncedPermissions = renouncedPermissions;
	return this;
	}

	/**
	* Creates a new instance.
	*
	* @return The new instance.
	*/
	@NonNull
	public ContextParams build() {
	return new ContextParams(mAttributionTag, mNext,
	mRenouncedPermissions, mShouldRegisterAttributionSource);
	}
	}
	}