Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fd2ae229 authored by Evan Chen's avatar Evan Chen
Browse files

[W] Introduce DeviceId 

The DeviceId replaces the AssociationTag and provides
a foundation for future feature expansion.
The customDeviceId offers the same functionality as the AssociationTag

Bug: 330793944
Test: cts
Flag: android.companion.association_tag

Change-Id: Id31cbd03840d7d6f55150535813f6597b7fd59a6
parent 6493c50c

core/api/current.txt

+17 −3
Original line number Diff line number Diff line
@@ -9999,12 +9999,12 @@ package android.companion { 
    method public int describeContents();

    method @Nullable public android.companion.AssociatedDevice getAssociatedDevice();

    method @FlaggedApi("android.companion.association_device_icon") @Nullable public android.graphics.drawable.Icon getDeviceIcon();

    method @FlaggedApi("android.companion.association_tag") @Nullable public android.companion.DeviceId getDeviceId();

    method @Nullable public android.net.MacAddress getDeviceMacAddress();

    method @Nullable public String getDeviceProfile();

    method @Nullable public CharSequence getDisplayName();

    method public int getId();

    method public int getSystemDataSyncFlags();

    method @FlaggedApi("android.companion.association_tag") @Nullable public String getTag();

    method public boolean isSelfManaged();

    method public void writeToParcel(@NonNull android.os.Parcel, int);

    field @NonNull public static final android.os.Parcelable.Creator<android.companion.AssociationInfo> CREATOR;
@@ -10077,7 +10077,6 @@ package android.companion { 
    method @RequiresPermission(android.Manifest.permission.DELIVER_COMPANION_MESSAGES) public void attachSystemDataTransport(int, @NonNull java.io.InputStream, @NonNull java.io.OutputStream) throws android.companion.DeviceNotAssociatedException;

    method @Nullable public android.content.IntentSender buildAssociationCancellationIntent();

    method @Nullable public android.content.IntentSender buildPermissionTransferUserConsentIntent(int) throws android.companion.DeviceNotAssociatedException;

    method @FlaggedApi("android.companion.association_tag") public void clearAssociationTag(int);

    method @RequiresPermission(android.Manifest.permission.DELIVER_COMPANION_MESSAGES) public void detachSystemDataTransport(int) throws android.companion.DeviceNotAssociatedException;

    method public void disableSystemDataSyncForTypes(int, int);

    method @Deprecated public void disassociate(@NonNull String);
@@ -10089,7 +10088,7 @@ package android.companion { 
    method @FlaggedApi("android.companion.perm_sync_user_consent") public boolean isPermissionTransferUserConsented(int);

    method @FlaggedApi("android.companion.unpair_associated_device") @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT) public boolean removeBond(int);

    method public void requestNotificationAccess(android.content.ComponentName);

    method @FlaggedApi("android.companion.association_tag") public void setAssociationTag(int, @NonNull String);

    method @FlaggedApi("android.companion.association_tag") public void setDeviceId(int, @Nullable android.companion.DeviceId);

    method @Deprecated @FlaggedApi("android.companion.device_presence") @RequiresPermission(android.Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE) public void startObservingDevicePresence(@NonNull String) throws android.companion.DeviceNotAssociatedException;

    method @FlaggedApi("android.companion.device_presence") @RequiresPermission(android.Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE) public void startObservingDevicePresence(@NonNull android.companion.ObservingDevicePresenceRequest);

    method public void startSystemDataTransfer(int, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Void,android.companion.CompanionException>) throws android.companion.DeviceNotAssociatedException;
@@ -10134,6 +10133,21 @@ package android.companion { 
  public interface DeviceFilter<D extends android.os.Parcelable> extends android.os.Parcelable {

  }













  @FlaggedApi("android.companion.association_tag") public final class DeviceId implements android.os.Parcelable {













    method public int describeContents();













    method @Nullable public String getCustomId();













    method @Nullable public android.net.MacAddress getMacAddress();













    method public void writeToParcel(@NonNull android.os.Parcel, int);













    field @NonNull public static final android.os.Parcelable.Creator<android.companion.DeviceId> CREATOR;













  }

























  public static final class DeviceId.Builder {













    ctor public DeviceId.Builder();













    method @NonNull public android.companion.DeviceId build();













    method @NonNull public android.companion.DeviceId.Builder setCustomId(@Nullable String);













    method @NonNull public android.companion.DeviceId.Builder setMacAddress(@Nullable android.net.MacAddress);













  }



























  public class DeviceNotAssociatedException extends java.lang.RuntimeException {















  }







































core/api/test-current.txt



+1
−1




























Original line number
Diff line number
Diff line








@@ -934,6 +934,7 @@ package android.companion {













    method @NonNull public android.companion.AssociationInfo build();















    method @NonNull public android.companion.AssociationInfo.Builder setAssociatedDevice(@Nullable android.companion.AssociatedDevice);















    method @FlaggedApi("android.companion.association_device_icon") @NonNull public android.companion.AssociationInfo.Builder setDeviceIcon(@Nullable android.graphics.drawable.Icon);













    method @FlaggedApi("android.companion.association_tag") @NonNull public android.companion.AssociationInfo.Builder setDeviceId(@Nullable android.companion.DeviceId);















    method @NonNull public android.companion.AssociationInfo.Builder setDeviceMacAddress(@Nullable android.net.MacAddress);















    method @NonNull public android.companion.AssociationInfo.Builder setDeviceProfile(@Nullable String);















    method @NonNull public android.companion.AssociationInfo.Builder setDisplayName(@Nullable CharSequence);









@@ -942,7 +943,6 @@ package android.companion {













    method @NonNull public android.companion.AssociationInfo.Builder setRevoked(boolean);















    method @NonNull public android.companion.AssociationInfo.Builder setSelfManaged(boolean);















    method @NonNull public android.companion.AssociationInfo.Builder setSystemDataSyncFlags(int);













    method @FlaggedApi("android.companion.association_tag") @NonNull public android.companion.AssociationInfo.Builder setTag(@Nullable String);















    method @NonNull public android.companion.AssociationInfo.Builder setTimeApproved(long);















  }

















































core/java/android/companion/AssociationInfo.java



+38
−26




























Original line number
Diff line number
Diff line








@@ -54,8 +54,6 @@ public final class AssociationInfo implements Parcelable {













    @NonNull















    private final String mPackageName;















    @Nullable













    private final String mTag;













    @Nullable















    private final MacAddress mDeviceMacAddress;















    @Nullable















    private final CharSequence mDisplayName;










@@ -85,6 +83,8 @@ public final class AssociationInfo implements Parcelable {













     */















    private final long mLastTimeConnectedMs;















    private final int mSystemDataSyncFlags;













    @Nullable













    private final DeviceId mDeviceId;































    /**















     * A device icon displayed on a selfManaged association dialog.









@@ -97,11 +97,11 @@ public final class AssociationInfo implements Parcelable {













     * @hide















     */















    public AssociationInfo(int id, @UserIdInt int userId, @NonNull String packageName,













            @Nullable String tag, @Nullable MacAddress macAddress,













            @Nullable CharSequence displayName, @Nullable String deviceProfile,













            @Nullable AssociatedDevice associatedDevice, boolean selfManaged,













            boolean notifyOnDeviceNearby, boolean revoked, boolean pending, long timeApprovedMs,













            long lastTimeConnectedMs, int systemDataSyncFlags, @Nullable Icon deviceIcon) {













            @Nullable MacAddress macAddress, @Nullable CharSequence displayName,













            @Nullable String deviceProfile, @Nullable AssociatedDevice associatedDevice,













            boolean selfManaged, boolean notifyOnDeviceNearby, boolean revoked, boolean pending,













            long timeApprovedMs, long lastTimeConnectedMs, int systemDataSyncFlags,













            @Nullable Icon deviceIcon, @Nullable DeviceId deviceId) {















        if (id <= 0) {















            throw new IllegalArgumentException("Association ID should be greater than 0");















        }









@@ -115,7 +115,6 @@ public final class AssociationInfo implements Parcelable {













        mPackageName = packageName;















        mDeviceMacAddress = macAddress;















        mDisplayName = displayName;













        mTag = tag;















        mDeviceProfile = deviceProfile;















        mAssociatedDevice = associatedDevice;















        mSelfManaged = selfManaged;









@@ -126,6 +125,7 @@ public final class AssociationInfo implements Parcelable {













        mLastTimeConnectedMs = lastTimeConnectedMs;















        mSystemDataSyncFlags = systemDataSyncFlags;















        mDeviceIcon = deviceIcon;













        mDeviceId = deviceId;















    }































    /**










@@ -155,13 +155,13 @@ public final class AssociationInfo implements Parcelable {













    }































    /**













     * @return the tag of this association.













     * @see CompanionDeviceManager#setAssociationTag(int, String)













     * @return the {@link DeviceId} of this association.













     * @see CompanionDeviceManager#setDeviceId(int, DeviceId)















     */















    @FlaggedApi(Flags.FLAG_ASSOCIATION_TAG)















    @Nullable













    public String getTag() {













        return mTag;













    public DeviceId getDeviceId() {













        return mDeviceId;















    }































    /**










@@ -355,7 +355,6 @@ public final class AssociationInfo implements Parcelable {













                + "mId=" + mId















                + ", mUserId=" + mUserId















                + ", mPackageName='" + mPackageName + '\''













                + ", mTag='" + mTag + '\''















                + ", mDeviceMacAddress=" + mDeviceMacAddress















                + ", mDisplayName='" + mDisplayName + '\''















                + ", mDeviceProfile='" + mDeviceProfile + '\''









@@ -369,6 +368,7 @@ public final class AssociationInfo implements Parcelable {













                    mLastTimeConnectedMs == Long.MAX_VALUE















                        ? LAST_TIME_CONNECTED_NONE : new Date(mLastTimeConnectedMs))















                + ", mSystemDataSyncFlags=" + mSystemDataSyncFlags













                + ", mDeviceId='" + mDeviceId















                + '}';















    }

























@@ -386,21 +386,22 @@ public final class AssociationInfo implements Parcelable {













                && mTimeApprovedMs == that.mTimeApprovedMs















                && mLastTimeConnectedMs == that.mLastTimeConnectedMs















                && Objects.equals(mPackageName, that.mPackageName)













                && Objects.equals(mTag, that.mTag)















                && Objects.equals(mDeviceMacAddress, that.mDeviceMacAddress)















                && Objects.equals(mDisplayName, that.mDisplayName)















                && Objects.equals(mDeviceProfile, that.mDeviceProfile)















                && Objects.equals(mAssociatedDevice, that.mAssociatedDevice)















                && mSystemDataSyncFlags == that.mSystemDataSyncFlags















                && (mDeviceIcon == null ? that.mDeviceIcon == null













                : mDeviceIcon.sameAs(that.mDeviceIcon));













                : mDeviceIcon.sameAs(that.mDeviceIcon))













                && Objects.equals(mDeviceId, that.mDeviceId);















    }































    @Override















    public int hashCode() {













        return Objects.hash(mId, mUserId, mPackageName, mTag, mDeviceMacAddress, mDisplayName,













        return Objects.hash(mId, mUserId, mPackageName, mDeviceMacAddress, mDisplayName,















                mDeviceProfile, mAssociatedDevice, mSelfManaged, mNotifyOnDeviceNearby, mRevoked,













                mPending, mTimeApprovedMs, mLastTimeConnectedMs, mSystemDataSyncFlags, mDeviceIcon);













                mPending, mTimeApprovedMs, mLastTimeConnectedMs, mSystemDataSyncFlags, mDeviceIcon,













                mDeviceId);















    }































    @Override









@@ -413,7 +414,6 @@ public final class AssociationInfo implements Parcelable {













        dest.writeInt(mId);















        dest.writeInt(mUserId);















        dest.writeString(mPackageName);













        dest.writeString(mTag);















        dest.writeTypedObject(mDeviceMacAddress, 0);















        dest.writeCharSequence(mDisplayName);















        dest.writeString(mDeviceProfile);









@@ -431,13 +431,19 @@ public final class AssociationInfo implements Parcelable {













        } else {















            dest.writeInt(0);















        }



























        if (Flags.associationTag() && mDeviceId != null) {













            dest.writeInt(1);













            dest.writeTypedObject(mDeviceId, flags);













        } else {













            dest.writeInt(0);













        }















    }































    private AssociationInfo(@NonNull Parcel in) {















        mId = in.readInt();















        mUserId = in.readInt();















        mPackageName = in.readString();













        mTag = in.readString();















        mDeviceMacAddress = in.readTypedObject(MacAddress.CREATOR);















        mDisplayName = in.readCharSequence();















        mDeviceProfile = in.readString();









@@ -454,6 +460,12 @@ public final class AssociationInfo implements Parcelable {













        } else {















            mDeviceIcon = null;















        }



























        if (Flags.associationTag() && in.readInt() == 1) {













            mDeviceId = in.readTypedObject(DeviceId.CREATOR);













        } else {













            mDeviceId = null;













        }















    }































    @NonNull










@@ -481,7 +493,6 @@ public final class AssociationInfo implements Parcelable {













        private final int mId;















        private final int mUserId;















        private final String mPackageName;













        private String mTag;















        private MacAddress mDeviceMacAddress;















        private CharSequence mDisplayName;















        private String mDeviceProfile;









@@ -494,6 +505,7 @@ public final class AssociationInfo implements Parcelable {













        private long mLastTimeConnectedMs;















        private int mSystemDataSyncFlags;















        private Icon mDeviceIcon;













        private DeviceId mDeviceId;































        /** @hide */















        @TestApi









@@ -509,7 +521,6 @@ public final class AssociationInfo implements Parcelable {













            mId = info.mId;















            mUserId = info.mUserId;















            mPackageName = info.mPackageName;













            mTag = info.mTag;















            mDeviceMacAddress = info.mDeviceMacAddress;















            mDisplayName = info.mDisplayName;















            mDeviceProfile = info.mDeviceProfile;









@@ -522,6 +533,7 @@ public final class AssociationInfo implements Parcelable {













            mLastTimeConnectedMs = info.mLastTimeConnectedMs;















            mSystemDataSyncFlags = info.mSystemDataSyncFlags;















            mDeviceIcon = info.mDeviceIcon;













            mDeviceId = info.mDeviceId;















        }































        /**









@@ -534,7 +546,6 @@ public final class AssociationInfo implements Parcelable {













            mId = id;















            mUserId = userId;















            mPackageName = packageName;













            mTag = info.mTag;















            mDeviceMacAddress = info.mDeviceMacAddress;















            mDisplayName = info.mDisplayName;















            mDeviceProfile = info.mDeviceProfile;









@@ -547,14 +558,15 @@ public final class AssociationInfo implements Parcelable {













            mLastTimeConnectedMs = info.mLastTimeConnectedMs;















            mSystemDataSyncFlags = info.mSystemDataSyncFlags;















            mDeviceIcon = info.mDeviceIcon;













            mDeviceId = info.mDeviceId;















        }































        /** @hide */















        @FlaggedApi(Flags.FLAG_ASSOCIATION_TAG)















        @TestApi















        @NonNull













        public Builder setTag(@Nullable String tag) {













            mTag = tag;













        public Builder setDeviceId(@Nullable DeviceId deviceId) {













            mDeviceId = deviceId;















            return this;















        }


























@@ -684,7 +696,6 @@ public final class AssociationInfo implements Parcelable {













                    mId,















                    mUserId,















                    mPackageName,













                    mTag,















                    mDeviceMacAddress,















                    mDisplayName,















                    mDeviceProfile,









@@ -696,7 +707,8 @@ public final class AssociationInfo implements Parcelable {













                    mTimeApprovedMs,















                    mLastTimeConnectedMs,















                    mSystemDataSyncFlags,













                    mDeviceIcon













                    mDeviceIcon,













                    mDeviceId















            );















        }















    }

































core/java/android/companion/CompanionDeviceManager.java



+7
−45




























Original line number
Diff line number
Diff line








@@ -277,12 +277,6 @@ public final class CompanionDeviceManager {













     */















    public static final int MESSAGE_ONEWAY_TO_WEARABLE = 0x43847987; // +TOW





























    /**













     * The length limit of Association tag.













     * @hide













     */













    private static final int ASSOCIATION_TAG_LENGTH_LIMIT = 1024;





























    /**















     * Callback for applications to receive updates about and the outcome of















     * {@link AssociationRequest} issued via {@code associate()} call.










@@ -1780,57 +1774,25 @@ public final class CompanionDeviceManager {













    }































    /**













     * Sets the {@link AssociationInfo#getTag() tag} for this association.













     *













     * <p>The length of the tag must be at most 1024 characters to save disk space.













     *













     * <p>This allows to store useful information about the associated devices.













     *













     * @param associationId The unique {@link AssociationInfo#getId ID} assigned to the Association













     *                          of the companion device recorded by CompanionDeviceManager













     * @param tag the tag of this association













     */













    @FlaggedApi(Flags.FLAG_ASSOCIATION_TAG)













    @UserHandleAware













    public void setAssociationTag(int associationId, @NonNull String tag) {













        if (mService == null) {













            Log.w(TAG, "CompanionDeviceManager service is not available.");













            return;













        }



























        Objects.requireNonNull(tag, "tag cannot be null");



























        if (tag.length() > ASSOCIATION_TAG_LENGTH_LIMIT) {













            throw new IllegalArgumentException("Length of the tag must be at most"













                    + ASSOCIATION_TAG_LENGTH_LIMIT + " characters");













        }



























        try {













            mService.setAssociationTag(associationId, tag);













        } catch (RemoteException e) {













            throw e.rethrowFromSystemServer();













        }













    }



























    /**













     * Clears the {@link AssociationInfo#getTag() tag} for this association.













     * Sets the {@link DeviceId deviceId} for this association.















     *













     * <p>The tag will be set to null for this association when calling this API.













     * <p>This device id helps the system uniquely identify your device for efficient device













     * management and prevents duplicate entries.















     *















     * @param associationId The unique {@link AssociationInfo#getId ID} assigned to the Association













     *                          of the companion device recorded by CompanionDeviceManager













     * @see CompanionDeviceManager#setAssociationTag(int, String)













     *                          of the companion device recorded by CompanionDeviceManager.













     * @param deviceId to be used as device identifier to represent the associated device.















     */















    @FlaggedApi(Flags.FLAG_ASSOCIATION_TAG)















    @UserHandleAware













    public void clearAssociationTag(int associationId) {













    public void setDeviceId(int associationId, @Nullable DeviceId deviceId) {















        if (mService == null) {















            Log.w(TAG, "CompanionDeviceManager service is not available.");















            return;















        }































        try {













            mService.clearAssociationTag(associationId);













            mService.setDeviceId(associationId, deviceId);















        } catch (RemoteException e) {















            throw e.rethrowFromSystemServer();















        }

































core/java/android/companion/DeviceId.aidl
0 → 100644



+19
−0




























Original line number
Diff line number
Diff line













/*













 * Copyright (C) 2024 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.companion;



























parcelable DeviceId;










 No newline at end of file