android-35/android/bluetooth/le/DistanceMeasurementParams.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * Copyright 2022 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.bluetooth.le;

 import android.annotation.FlaggedApi;
 import android.annotation.IntDef;
 import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.SystemApi;
 import android.bluetooth.BluetoothDevice;
 import android.bluetooth.le.DistanceMeasurementMethod.DistanceMeasurementMethodId;
 import android.os.Parcel;
 import android.os.Parcelable;

 import com.android.bluetooth.flags.Flags;

 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.Objects;

 /**
  * The {@link DistanceMeasurementParams} provide a way to adjust distance measurement preferences.
  * Use {@link DistanceMeasurementParams.Builder} to create an instance of this class.
  *
  * @hide
  */
 @SystemApi
 public final class DistanceMeasurementParams implements Parcelable {

     /** @hide */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef(value = {REPORT_FREQUENCY_LOW, REPORT_FREQUENCY_MEDIUM, REPORT_FREQUENCY_HIGH})
     @interface ReportFrequency {}

     /**
      * Perform distance measurement in low frequency. This is the default frequency as it consumes
      * the least power.
      *
      * @hide
      */
     @SystemApi public static final int REPORT_FREQUENCY_LOW = 0;

     /**
      * Perform distance measurement in medium frequency. Provides a good trade-off between report
      * frequency and power consumption.
      *
      * @hide
      */
     @SystemApi public static final int REPORT_FREQUENCY_MEDIUM = 1;

     /**
      * Perform distance measurement in high frequency. It's recommended to only use this mode when
      * the application is running in the foreground.
      *
      * @hide
      */
     @SystemApi public static final int REPORT_FREQUENCY_HIGH = 2;

     private static final int REPORT_DURATION_DEFAULT = 60;
     private static final int REPORT_DURATION_MAX = 3600;

     private BluetoothDevice mDevice = null;
     private int mDuration;
     private int mFrequency;
     private int mMethodId;
     private ChannelSoundingParams mChannelSoundingParams = null;

     /** @hide */
     public DistanceMeasurementParams(
             BluetoothDevice device,
             int duration,
             int frequency,
             int methodId,
             ChannelSoundingParams channelSoundingParams) {
         mDevice = Objects.requireNonNull(device);
         mDuration = duration;
         mFrequency = frequency;
         mMethodId = methodId;
         mChannelSoundingParams = channelSoundingParams;
     }

     /**
      * Returns device of this DistanceMeasurementParams.
      *
      * @hide
      */
     @SystemApi
     public @NonNull BluetoothDevice getDevice() {
         return mDevice;
     }

     /**
      * Returns duration in seconds of this DistanceMeasurementParams. Once the distance measurement
      * successfully started, the Bluetooth process will keep reporting the measurement result until
      * this time has been reached or the session is explicitly stopped with {@link
      * DistanceMeasurementSession#stopSession}
      *
      * @hide
      */
     @SystemApi
     public @IntRange(from = 0) int getDurationSeconds() {
         return mDuration;
     }

     /**
      * Returns frequency of this DistanceMeasurementParams. The Bluetooth process uses this value to
      * determine report frequency of the measurement result.
      *
      * @hide
      */
     @SystemApi
     public @ReportFrequency int getFrequency() {
         return mFrequency;
     }

     /**
      * Returns method id of this DistanceMeasurementParams.
      *
      * @hide
      */
     @SystemApi
     public @DistanceMeasurementMethodId int getMethodId() {
         return mMethodId;
     }

     /**
      * Returns {@link ChannelSoundingParams} of this DistanceMeasurementParams.
      *
      * @hide
      */
     @FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
     @SystemApi
     public @Nullable ChannelSoundingParams getChannelSoundingParams() {
         return mChannelSoundingParams;
     }

     /**
      * Get the default duration in seconds of the parameter.
      *
      * @hide
      */
     @SystemApi
     public static int getDefaultDurationSeconds() {
         return REPORT_DURATION_DEFAULT;
     }

     /**
      * Get the maximum duration in seconds that can be set for the parameter.
      *
      * @hide
      */
     @SystemApi
     public static int getMaxDurationSeconds() {
         return REPORT_DURATION_MAX;
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @Override
     public int describeContents() {
         return 0;
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @Override
     public void writeToParcel(Parcel out, int flags) {
         out.writeParcelable(mDevice, 0);
         out.writeInt(mDuration);
         out.writeInt(mFrequency);
         out.writeInt(mMethodId);
         out.writeParcelable(mChannelSoundingParams, 0);
     }

     /** A {@link Parcelable.Creator} to create {@link DistanceMeasurementParams} from parcel. */
     public static final @NonNull Parcelable.Creator<DistanceMeasurementParams> CREATOR =
             new Parcelable.Creator<DistanceMeasurementParams>() {
                 @Override
                 public @NonNull DistanceMeasurementParams createFromParcel(@NonNull Parcel in) {
                     Builder builder = new Builder((BluetoothDevice) in.readParcelable(null));
                     builder.setDurationSeconds(in.readInt());
                     builder.setFrequency(in.readInt());
                     builder.setMethodId(in.readInt());
                     builder.setChannelSoundingParams(
                             (ChannelSoundingParams) in.readParcelable(null));
                     return builder.build();
                 }

                 @Override
                 public @NonNull DistanceMeasurementParams[] newArray(int size) {
                     return new DistanceMeasurementParams[size];
                 }
             };

     /**
      * Builder for {@link DistanceMeasurementParams}.
      *
      * @hide
      */
     @SystemApi
     public static final class Builder {
         private BluetoothDevice mDevice = null;
         private int mDuration = REPORT_DURATION_DEFAULT;
         private int mFrequency = REPORT_FREQUENCY_LOW;
         private int mMethodId = DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI;
         private ChannelSoundingParams mChannelSoundingParams = null;

         /**
          * Constructor of the Builder.
          *
          * @param device the remote device for the distance measurement
          */
         public Builder(@NonNull BluetoothDevice device) {
             mDevice = Objects.requireNonNull(device);
         }

         /**
          * Set duration in seconds for the DistanceMeasurementParams. Once the distance measurement
          * successfully started, the Bluetooth process will keep reporting the measurement result
          * until this time has been reached or the session is explicitly stopped with {@link
          * DistanceMeasurementSession#stopSession}.
          *
          * @param duration duration in seconds of this DistanceMeasurementParams
          * @return the same Builder instance
          * @throws IllegalArgumentException if duration greater than {@link
          *     DistanceMeasurementParams#getMaxDurationSeconds()} or less than zero.
          * @hide
          */
         @SystemApi
         public @NonNull Builder setDurationSeconds(@IntRange(from = 0) int duration) {
             if (duration < 0 || duration > getMaxDurationSeconds()) {
                 throw new IllegalArgumentException("illegal duration " + duration);
             }
             mDuration = duration;
             return this;
         }

         /**
          * Set frequency for the DistanceMeasurementParams. The Bluetooth process uses this value to
          * determine report frequency of the measurement result.
          *
          * @param frequency frequency of this DistanceMeasurementParams
          * @return the same Builder instance
          * @hide
          */
         @SystemApi
         public @NonNull Builder setFrequency(@ReportFrequency int frequency) {
             switch (frequency) {
                 case REPORT_FREQUENCY_LOW:
                 case REPORT_FREQUENCY_MEDIUM:
                 case REPORT_FREQUENCY_HIGH:
                     mFrequency = frequency;
                     break;
                 default:
                     throw new IllegalArgumentException("unknown frequency " + frequency);
             }
             return this;
         }

         /**
          * Set method id for the DistanceMeasurementParams.
          *
          * @param methodId method id of this DistanceMeasurementParams
          * @return the same Builder instance
          * @hide
          */
         @SystemApi
         public @NonNull Builder setMethodId(@DistanceMeasurementMethodId int methodId) {
             switch (methodId) {
                 case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_AUTO:
                 case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI:
                 case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_CHANNEL_SOUNDING:
                     mMethodId = methodId;
                     break;
                 default:
                     throw new IllegalArgumentException("unknown method id " + methodId);
             }
             return this;
         }

         /**
          * Set {@link ChannelSoundingParams} for the DistanceMeasurementParams.
          *
          * @param channelSoundingParams parameters for Channel Sounding
          * @return the same Builder instance
          * @hide
          */
         @FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
         @SystemApi
         public @NonNull Builder setChannelSoundingParams(
                 @NonNull ChannelSoundingParams channelSoundingParams) {
             mChannelSoundingParams = channelSoundingParams;
             return this;
         }

         /**
          * Build the {@link DistanceMeasurementParams} object.
          *
          * @hide
          */
         @SystemApi
         public @NonNull DistanceMeasurementParams build() {
             return new DistanceMeasurementParams(
                     mDevice, mDuration, mFrequency, mMethodId, mChannelSoundingParams);
         }
     }
 }
	/*
	* Copyright 2022 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.bluetooth.le;

	import android.annotation.FlaggedApi;
	import android.annotation.IntDef;
	import android.annotation.IntRange;
	import android.annotation.NonNull;
	import android.annotation.Nullable;
	import android.annotation.SystemApi;
	import android.bluetooth.BluetoothDevice;
	import android.bluetooth.le.DistanceMeasurementMethod.DistanceMeasurementMethodId;
	import android.os.Parcel;
	import android.os.Parcelable;

	import com.android.bluetooth.flags.Flags;

	import java.lang.annotation.Retention;
	import java.lang.annotation.RetentionPolicy;
	import java.util.Objects;

	/**
	* The {@link DistanceMeasurementParams} provide a way to adjust distance measurement preferences.
	* Use {@link DistanceMeasurementParams.Builder} to create an instance of this class.
	*
	* @hide
	*/
	@SystemApi
	public final class DistanceMeasurementParams implements Parcelable {

	/** @hide */
	@Retention(RetentionPolicy.SOURCE)
	@IntDef(value = {REPORT_FREQUENCY_LOW, REPORT_FREQUENCY_MEDIUM, REPORT_FREQUENCY_HIGH})
	@interface ReportFrequency {}

	/**
	* Perform distance measurement in low frequency. This is the default frequency as it consumes
	* the least power.
	*
	* @hide
	*/
	@SystemApi public static final int REPORT_FREQUENCY_LOW = 0;

	/**
	* Perform distance measurement in medium frequency. Provides a good trade-off between report
	* frequency and power consumption.
	*
	* @hide
	*/
	@SystemApi public static final int REPORT_FREQUENCY_MEDIUM = 1;

	/**
	* Perform distance measurement in high frequency. It's recommended to only use this mode when
	* the application is running in the foreground.
	*
	* @hide
	*/
	@SystemApi public static final int REPORT_FREQUENCY_HIGH = 2;

	private static final int REPORT_DURATION_DEFAULT = 60;
	private static final int REPORT_DURATION_MAX = 3600;

	private BluetoothDevice mDevice = null;
	private int mDuration;
	private int mFrequency;
	private int mMethodId;
	private ChannelSoundingParams mChannelSoundingParams = null;

	/** @hide */
	public DistanceMeasurementParams(
	BluetoothDevice device,
	int duration,
	int frequency,
	int methodId,
	ChannelSoundingParams channelSoundingParams) {
	mDevice = Objects.requireNonNull(device);
	mDuration = duration;
	mFrequency = frequency;
	mMethodId = methodId;
	mChannelSoundingParams = channelSoundingParams;
	}

	/**
	* Returns device of this DistanceMeasurementParams.
	*
	* @hide
	*/
	@SystemApi
	public @NonNull BluetoothDevice getDevice() {
	return mDevice;
	}

	/**
	* Returns duration in seconds of this DistanceMeasurementParams. Once the distance measurement
	* successfully started, the Bluetooth process will keep reporting the measurement result until
	* this time has been reached or the session is explicitly stopped with {@link
	* DistanceMeasurementSession#stopSession}
	*
	* @hide
	*/
	@SystemApi
	public @IntRange(from = 0) int getDurationSeconds() {
	return mDuration;
	}

	/**
	* Returns frequency of this DistanceMeasurementParams. The Bluetooth process uses this value to
	* determine report frequency of the measurement result.
	*
	* @hide
	*/
	@SystemApi
	public @ReportFrequency int getFrequency() {
	return mFrequency;
	}

	/**
	* Returns method id of this DistanceMeasurementParams.
	*
	* @hide
	*/
	@SystemApi
	public @DistanceMeasurementMethodId int getMethodId() {
	return mMethodId;
	}

	/**
	* Returns {@link ChannelSoundingParams} of this DistanceMeasurementParams.
	*
	* @hide
	*/
	@FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
	@SystemApi
	public @Nullable ChannelSoundingParams getChannelSoundingParams() {
	return mChannelSoundingParams;
	}

	/**
	* Get the default duration in seconds of the parameter.
	*
	* @hide
	*/
	@SystemApi
	public static int getDefaultDurationSeconds() {
	return REPORT_DURATION_DEFAULT;
	}

	/**
	* Get the maximum duration in seconds that can be set for the parameter.
	*
	* @hide
	*/
	@SystemApi
	public static int getMaxDurationSeconds() {
	return REPORT_DURATION_MAX;
	}

	/**
	* {@inheritDoc}
	*
	* @hide
	*/
	@Override
	public int describeContents() {
	return 0;
	}

	/**
	* {@inheritDoc}
	*
	* @hide
	*/
	@Override
	public void writeToParcel(Parcel out, int flags) {
	out.writeParcelable(mDevice, 0);
	out.writeInt(mDuration);
	out.writeInt(mFrequency);
	out.writeInt(mMethodId);
	out.writeParcelable(mChannelSoundingParams, 0);
	}

	/** A {@link Parcelable.Creator} to create {@link DistanceMeasurementParams} from parcel. */
	public static final @NonNull Parcelable.Creator<DistanceMeasurementParams> CREATOR =
	new Parcelable.Creator<DistanceMeasurementParams>() {
	@Override
	public @NonNull DistanceMeasurementParams createFromParcel(@NonNull Parcel in) {
	Builder builder = new Builder((BluetoothDevice) in.readParcelable(null));
	builder.setDurationSeconds(in.readInt());
	builder.setFrequency(in.readInt());
	builder.setMethodId(in.readInt());
	builder.setChannelSoundingParams(
	(ChannelSoundingParams) in.readParcelable(null));
	return builder.build();
	}

	@Override
	public @NonNull DistanceMeasurementParams[] newArray(int size) {
	return new DistanceMeasurementParams[size];
	}
	};

	/**
	* Builder for {@link DistanceMeasurementParams}.
	*
	* @hide
	*/
	@SystemApi
	public static final class Builder {
	private BluetoothDevice mDevice = null;
	private int mDuration = REPORT_DURATION_DEFAULT;
	private int mFrequency = REPORT_FREQUENCY_LOW;
	private int mMethodId = DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI;
	private ChannelSoundingParams mChannelSoundingParams = null;

	/**
	* Constructor of the Builder.
	*
	* @param device the remote device for the distance measurement
	*/
	public Builder(@NonNull BluetoothDevice device) {
	mDevice = Objects.requireNonNull(device);
	}

	/**
	* Set duration in seconds for the DistanceMeasurementParams. Once the distance measurement
	* successfully started, the Bluetooth process will keep reporting the measurement result
	* until this time has been reached or the session is explicitly stopped with {@link
	* DistanceMeasurementSession#stopSession}.
	*
	* @param duration duration in seconds of this DistanceMeasurementParams
	* @return the same Builder instance
	* @throws IllegalArgumentException if duration greater than {@link
	* DistanceMeasurementParams#getMaxDurationSeconds()} or less than zero.
	* @hide
	*/
	@SystemApi
	public @NonNull Builder setDurationSeconds(@IntRange(from = 0) int duration) {
	if (duration < 0 \|\| duration > getMaxDurationSeconds()) {
	throw new IllegalArgumentException("illegal duration " + duration);
	}
	mDuration = duration;
	return this;
	}

	/**
	* Set frequency for the DistanceMeasurementParams. The Bluetooth process uses this value to
	* determine report frequency of the measurement result.
	*
	* @param frequency frequency of this DistanceMeasurementParams
	* @return the same Builder instance
	* @hide
	*/
	@SystemApi
	public @NonNull Builder setFrequency(@ReportFrequency int frequency) {
	switch (frequency) {
	case REPORT_FREQUENCY_LOW:
	case REPORT_FREQUENCY_MEDIUM:
	case REPORT_FREQUENCY_HIGH:
	mFrequency = frequency;
	break;
	default:
	throw new IllegalArgumentException("unknown frequency " + frequency);
	}
	return this;
	}

	/**
	* Set method id for the DistanceMeasurementParams.
	*
	* @param methodId method id of this DistanceMeasurementParams
	* @return the same Builder instance
	* @hide
	*/
	@SystemApi
	public @NonNull Builder setMethodId(@DistanceMeasurementMethodId int methodId) {
	switch (methodId) {
	case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_AUTO:
	case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI:
	case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_CHANNEL_SOUNDING:
	mMethodId = methodId;
	break;
	default:
	throw new IllegalArgumentException("unknown method id " + methodId);
	}
	return this;
	}

	/**
	* Set {@link ChannelSoundingParams} for the DistanceMeasurementParams.
	*
	* @param channelSoundingParams parameters for Channel Sounding
	* @return the same Builder instance
	* @hide
	*/
	@FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
	@SystemApi
	public @NonNull Builder setChannelSoundingParams(
	@NonNull ChannelSoundingParams channelSoundingParams) {
	mChannelSoundingParams = channelSoundingParams;
	return this;
	}

	/**
	* Build the {@link DistanceMeasurementParams} object.
	*
	* @hide
	*/
	@SystemApi
	public @NonNull DistanceMeasurementParams build() {
	return new DistanceMeasurementParams(
	mDevice, mDuration, mFrequency, mMethodId, mChannelSoundingParams);
	}
	}
	}