Merge "Minimal skeleton for location time zone providers"

6 files changed, 491 insertions, 0 deletions

diff --git a/location/java/android/location/timezone/LocationTimeZoneEvent.aidl b/location/java/android/location/timezone/LocationTimeZoneEvent.aidl
new file mode 100644
index 000000000000..538658822930
--- /dev/null
+++ b/location/java/android/location/timezone/LocationTimeZoneEvent.aidl
@@ -0,0 +1,19 @@
+/*
+ * Copyright (C) 2020, 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.location.timezone;
+
+parcelable LocationTimeZoneEvent;
diff --git a/location/java/android/location/timezone/LocationTimeZoneEvent.java b/location/java/android/location/timezone/LocationTimeZoneEvent.java
new file mode 100644
index 000000000000..a0808ea36679
--- /dev/null
+++ b/location/java/android/location/timezone/LocationTimeZoneEvent.java
@@ -0,0 +1,246 @@
+/*
+ * Copyright (C) 2020 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.location.timezone;
+
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.os.Parcel;
+import android.os.Parcelable;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * An event containing location time zone information.
+ *
+ * @hide
+ */
+public final class LocationTimeZoneEvent implements Parcelable {
+
+    @IntDef({ EVENT_TYPE_UNKNOWN, EVENT_TYPE_SUCCESS, EVENT_TYPE_SUCCESS })
+    @interface EventType {}
+
+    /** Uninitialized value for {@link #mEventType} */
+    private static final int EVENT_TYPE_UNKNOWN = 0;
+
+    /**
+     * Indicates there was a permanent failure. This is not generally expected, and probably means a
+     * required backend service is no longer supported / available.
+     */
+    public static final int EVENT_TYPE_PERMANENT_FAILURE = 1;
+
+    /**
+     * Indicates a successful geolocation time zone detection event. {@link #mTimeZoneIds} will be
+     * non-null but can legitimately be empty, e.g. for disputed areas, oceans.
+     */
+    public static final int EVENT_TYPE_SUCCESS = 2;
+
+    /**
+     * Indicates the time zone is not known because there was a (temporary) error, e.g. when
+     * detecting location, or when resolving the location to a time zone.
+     */
+    public static final int EVENT_TYPE_UNCERTAIN = 3;
+
+    private static final int EVENT_TYPE_MAX = EVENT_TYPE_UNCERTAIN;
+
+    @EventType
+    private final int mEventType;
+
+    @NonNull
+    private final List<String> mTimeZoneIds;
+
+    private final long mElapsedRealtimeNanos;
+
+    private LocationTimeZoneEvent(@EventType int eventType, @NonNull List<String> timeZoneIds,
+            long elapsedRealtimeNanos) {
+        mEventType = checkValidEventType(eventType);
+        mTimeZoneIds = immutableList(timeZoneIds);
+
+        boolean emptyTimeZoneIdListExpected = eventType != EVENT_TYPE_SUCCESS;
+        if (emptyTimeZoneIdListExpected && !timeZoneIds.isEmpty()) {
+            throw new IllegalStateException(
+                    "timeZoneIds must only have values when eventType is success");
+        }
+
+        mElapsedRealtimeNanos = elapsedRealtimeNanos;
+    }
+
+    /**
+     * Returns the time of this fix, in elapsed real-time since system boot.
+     *
+     * <p>This value can be reliably compared to {@link
+     * android.os.SystemClock#elapsedRealtimeNanos}, to calculate the age of a fix and to compare
+     * {@link LocationTimeZoneEvent} fixes. This is reliable because elapsed real-time is guaranteed
+     * monotonic for each system boot and continues to increment even when the system is in deep
+     * sleep.
+     *
+     * @return elapsed real-time of fix, in nanoseconds since system boot.
+     */
+    public long getElapsedRealtimeNanos() {
+        return mElapsedRealtimeNanos;
+    }
+
+    /**
+     * Returns the event type.
+     */
+    @Nullable
+    public @EventType int getEventType() {
+        return mEventType;
+    }
+
+    /**
+     * Gets the time zone IDs of this result. Contains zero or more IDs for a successful lookup.
+     * The value is undefined for an unsuccessful lookup. See also {@link #getEventType()}.
+     */
+    @NonNull
+    public List<String> getTimeZoneIds() {
+        return mTimeZoneIds;
+    }
+
+    @Override
+    public String toString() {
+        return "LocationTimeZoneEvent{"
+                + "mEventType=" + mEventType
+                + ", mTimeZoneIds=" + mTimeZoneIds
+                + ", mElapsedRealtimeNanos=" + mElapsedRealtimeNanos
+                + '}';
+    }
+
+    public static final @NonNull Parcelable.Creator<LocationTimeZoneEvent> CREATOR =
+            new Parcelable.Creator<LocationTimeZoneEvent>() {
+                @Override
+                public LocationTimeZoneEvent createFromParcel(Parcel in) {
+                    int eventType = in.readInt();
+                    @SuppressWarnings("unchecked")
+                    ArrayList<String> timeZoneIds =
+                            (ArrayList<String>) in.readArrayList(null /* classLoader */);
+                    long elapsedRealtimeNanos = in.readLong();
+                    return new LocationTimeZoneEvent(eventType, timeZoneIds, elapsedRealtimeNanos);
+                }
+
+                @Override
+                public LocationTimeZoneEvent[] newArray(int size) {
+                    return new LocationTimeZoneEvent[size];
+                }
+            };
+
+    @Override
+    public int describeContents() {
+        return 0;
+    }
+
+    @Override
+    public void writeToParcel(Parcel parcel, int flags) {
+        parcel.writeInt(mEventType);
+        parcel.writeList(mTimeZoneIds);
+        parcel.writeLong(mElapsedRealtimeNanos);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        LocationTimeZoneEvent that = (LocationTimeZoneEvent) o;
+        return mEventType == that.mEventType
+                && mElapsedRealtimeNanos == that.mElapsedRealtimeNanos
+                && mTimeZoneIds.equals(that.mTimeZoneIds);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(mEventType, mTimeZoneIds, mElapsedRealtimeNanos);
+    }
+
+    /** @hide */
+    public static final class Builder {
+
+        private @EventType int mEventType = EVENT_TYPE_UNKNOWN;
+        private @NonNull List<String> mTimeZoneIds = Collections.emptyList();
+        private long mElapsedRealtimeNanos;
+
+        public Builder() {
+        }
+
+        /**
+         * Sets the contents of this from the supplied instance.
+         */
+        public Builder(@NonNull LocationTimeZoneEvent ltz) {
+            mEventType = ltz.mEventType;
+            mTimeZoneIds = ltz.mTimeZoneIds;
+            mElapsedRealtimeNanos = ltz.mElapsedRealtimeNanos;
+        }
+
+        /**
+         * Set the time zone ID of this fix.
+         */
+        public Builder setEventType(@EventType int eventType) {
+            checkValidEventType(eventType);
+            mEventType = eventType;
+            return this;
+        }
+
+        /**
+         * Sets the time zone IDs of this fix.
+         */
+        public Builder setTimeZoneIds(@NonNull List<String> timeZoneIds) {
+            mTimeZoneIds = Objects.requireNonNull(timeZoneIds);
+            return this;
+        }
+
+        /**
+         * Sets the time of this fix, in elapsed real-time since system boot.
+         *
+         * @param time elapsed real-time of fix, in nanoseconds since system boot.
+         */
+        public Builder setElapsedRealtimeNanos(long time) {
+            mElapsedRealtimeNanos = time;
+            return this;
+        }
+
+        /**
+         * Builds a {@link LocationTimeZoneEvent} instance.
+         */
+        public LocationTimeZoneEvent build() {
+            return new LocationTimeZoneEvent(this.mEventType, this.mTimeZoneIds,
+                    this.mElapsedRealtimeNanos);
+        }
+    }
+
+    private static int checkValidEventType(int eventType) {
+        if (eventType <= EVENT_TYPE_UNKNOWN || eventType > EVENT_TYPE_MAX) {
+            throw new IllegalStateException("eventType " + eventType + " unknown");
+        }
+        return eventType;
+    }
+
+    @NonNull
+    private static List<String> immutableList(@NonNull List<String> list) {
+        Objects.requireNonNull(list);
+        if (list.isEmpty()) {
+            return Collections.emptyList();
+        } else {
+            return Collections.unmodifiableList(new ArrayList<>(list));
+        }
+    }
+}
diff --git a/location/java/com/android/internal/location/timezone/ILocationTimeZoneProvider.aidl b/location/java/com/android/internal/location/timezone/ILocationTimeZoneProvider.aidl
new file mode 100644
index 000000000000..16aa84859f6e
--- /dev/null
+++ b/location/java/com/android/internal/location/timezone/ILocationTimeZoneProvider.aidl
@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2020 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 com.android.internal.location.timezone;
+
+import com.android.internal.location.timezone.ILocationTimeZoneProviderManager;
+import com.android.internal.location.timezone.LocationTimeZoneProviderRequest;
+
+/**
+ * Binder interface for location time zone provider implementations. Do not implement this
+ * directly, extend {@link com.android.location.timezone.provider.LocationTimeZoneProviderBase}
+ * instead.
+ * @hide
+ */
+interface ILocationTimeZoneProvider {
+
+    oneway void setLocationTimeZoneProviderManager(in ILocationTimeZoneProviderManager manager);
+
+    oneway void setRequest(in LocationTimeZoneProviderRequest request);
+}
diff --git a/location/java/com/android/internal/location/timezone/ILocationTimeZoneProviderManager.aidl b/location/java/com/android/internal/location/timezone/ILocationTimeZoneProviderManager.aidl
new file mode 100644
index 000000000000..f89a64fc586c
--- /dev/null
+++ b/location/java/com/android/internal/location/timezone/ILocationTimeZoneProviderManager.aidl
@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2020 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 com.android.internal.location.timezone;
+
+import android.location.timezone.LocationTimeZoneEvent;
+
+/**
+ * Binder interface for the manager of location time zone provider implementations.
+ * @hide
+ */
+interface ILocationTimeZoneProviderManager {
+    void onLocationTimeZoneEvent(in LocationTimeZoneEvent locationTimeZoneEvent);
+}
diff --git a/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.aidl b/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.aidl
new file mode 100644
index 000000000000..bb59457094f4
--- /dev/null
+++ b/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.aidl
@@ -0,0 +1,19 @@
+/*
+ * Copyright (C) 2020 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 com.android.internal.location.timezone;
+
+parcelable LocationTimeZoneProviderRequest;
diff --git a/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.java b/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.java
new file mode 100644
index 000000000000..8f3b5d7781cf
--- /dev/null
+++ b/location/java/com/android/internal/location/timezone/LocationTimeZoneProviderRequest.java
@@ -0,0 +1,147 @@
+/*
+ * Copyright (C) 2020 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 com.android.internal.location.timezone;
+
+import android.annotation.NonNull;
+import android.os.Parcel;
+import android.os.Parcelable;
+import android.os.WorkSource;
+
+import java.util.Objects;
+
+/**
+ * An request passed to a location time zone provider to configure it.
+ *
+ * @hide
+ */
+public final class LocationTimeZoneProviderRequest implements Parcelable {
+
+    public static final Creator<LocationTimeZoneProviderRequest> CREATOR =
+            new Creator<LocationTimeZoneProviderRequest>() {
+                @Override
+                public LocationTimeZoneProviderRequest createFromParcel(Parcel in) {
+                    return LocationTimeZoneProviderRequest.createFromParcel(in);
+                }
+
+                @Override
+                public LocationTimeZoneProviderRequest[] newArray(int size) {
+                    return new LocationTimeZoneProviderRequest[size];
+                }
+            };
+
+    /** Location time zone reporting is requested (true) */
+    private final boolean mReportLocationTimeZone;
+    /** The WorkSource for power attribution. */
+    @NonNull private final WorkSource mWorkSource;
+
+    private LocationTimeZoneProviderRequest(boolean reportLocationTimeZone, WorkSource workSource) {
+        mReportLocationTimeZone = reportLocationTimeZone;
+        mWorkSource = Objects.requireNonNull(workSource);
+    }
+
+    public boolean getReportLocationTimeZone() {
+        return mReportLocationTimeZone;
+    }
+
+    @NonNull
+    public WorkSource getWorkSource() {
+        return mWorkSource;
+    }
+
+    @Override
+    public int describeContents() {
+        return 0;
+    }
+
+    @Override
+    public void writeToParcel(Parcel parcel, int flags) {
+        parcel.writeInt(mReportLocationTimeZone ? 1 : 0);
+        parcel.writeParcelable(mWorkSource, 0);
+    }
+
+    static LocationTimeZoneProviderRequest createFromParcel(Parcel in) {
+        ClassLoader classLoader = LocationTimeZoneProviderRequest.class.getClassLoader();
+        return new Builder()
+                .setReportLocationTimeZone(in.readInt() == 1)
+                .setWorkSource(in.readParcelable(classLoader))
+                .build();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        LocationTimeZoneProviderRequest that = (LocationTimeZoneProviderRequest) o;
+        return mReportLocationTimeZone == that.mReportLocationTimeZone
+                && mWorkSource.equals(that.mWorkSource);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(mReportLocationTimeZone, mWorkSource);
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder s = new StringBuilder();
+        s.append("TimeZoneProviderRequest[");
+        if (mReportLocationTimeZone) {
+            s.append("ON");
+        } else {
+            s.append("OFF");
+        }
+        s.append(",");
+        s.append("workSource=").append(mWorkSource);
+        s.append(']');
+        return s.toString();
+    }
+
+    /** @hide */
+    public static final class Builder {
+
+        private boolean mReportLocationTimeZone;
+        private WorkSource mWorkSource;
+
+        /**
+         * Sets the property that enables / disables the provider. This is set to {@code false} by
+         * default.
+         */
+        public Builder setReportLocationTimeZone(boolean reportLocationTimeZone) {
+            mReportLocationTimeZone = reportLocationTimeZone;
+            return this;
+        }
+
+        /**
+         * Sets the {@link WorkSource} to attribute the power usage to.
+         */
+        public Builder setWorkSource(@NonNull WorkSource workSource) {
+            mWorkSource = Objects.requireNonNull(workSource);
+            return this;
+        }
+
+        /** Builds the {@link LocationTimeZoneProviderRequest} instance. */
+        @NonNull
+        public LocationTimeZoneProviderRequest build() {
+            return new LocationTimeZoneProviderRequest(this.mReportLocationTimeZone,
+                    this.mWorkSource);
+        }
+    }
+}