/*
 * 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.
 */

syntax = "proto2";
package android.app.time;

import "frameworks/base/core/proto/android/privacy.proto";

option java_multiple_files = true;
option java_outer_classname = "TimeZoneDetectorProto";

// Represents a LocationTimeZoneProviderEvent that can be / has been passed to the time zone
// detector.
message LocationTimeZoneProviderEventProto {
  option (android.msg_privacy).dest = DEST_AUTOMATIC;

  optional GeolocationTimeZoneSuggestionProto suggestion = 1;
  repeated string debug_info = 2;
  optional LocationTimeZoneAlgorithmStatusProto algorithm_status = 3;
}

// Represents a LocationTimeZoneAlgorithmStatus that can be / has been passed to the time zone
// detector.
message LocationTimeZoneAlgorithmStatusProto {
  option (android.msg_privacy).dest = DEST_AUTOMATIC;

  optional DetectionAlgorithmStatusEnum status = 1;
}

// The state enum for detection algorithms.
enum DetectionAlgorithmStatusEnum {
    DETECTION_ALGORITHM_STATUS_UNKNOWN = 0;
    DETECTION_ALGORITHM_STATUS_NOT_SUPPORTED = 1;
    DETECTION_ALGORITHM_STATUS_NOT_RUNNING = 2;
    DETECTION_ALGORITHM_STATUS_RUNNING = 3;
}

// Represents a GeolocationTimeZoneSuggestion that can be contained in a
// LocationTimeZoneProviderEvent.
message GeolocationTimeZoneSuggestionProto {
  option (android.msg_privacy).dest = DEST_AUTOMATIC;

  repeated string zone_ids = 1;
}

/*
 * A generic-form time zone suggestion for metrics use. Required to be a superset of the
 * MetricsTimeZoneSuggestion proto defined in atoms.proto to ensure binary compatibility.
 */
message MetricsTimeZoneSuggestion {
  option (android.msg_privacy).dest = DEST_AUTOMATIC;

  enum Type {
    CERTAIN = 1;
    UNCERTAIN = 2;
  }
  optional Type type = 1;

  // The ordinals for time zone(s) in the suggestion. Always empty for
  // UNCERTAIN, and can be empty for CERTAIN, for example when the device is in
  // a disputed area / on an ocean.
  //
  // The suggestion's time zone IDs (which relate to location) are obfuscated by
  // mapping them to an ordinal. When the ordinal is assigned consistently across
  // several objects (i.e. so the same time zone ID is always mapped to the same
  // ordinal), this allows comparisons between those objects. For example, we can
  // answer "did these two suggestions agree?", "does the suggestion match the
  // device's current time zone?", without leaking knowledge of location. Ordinals
  // are also significantly more compact than full IANA TZDB IDs, albeit unstable
  // and of limited use.
  repeated int32 time_zone_ordinals = 2;

  // The actual time zone ID(s) in the suggestion. Similar to time_zone_ordinals
  // but contains the actual string IDs.
  //
  // This information is only captured / reported for some devices based on the
  // value of a server side flag, i.e. it could be enabled for internal testers.
  // Therefore the list can be empty even when time_zone_ordinals is populated.
  //
  // When enabled, see time_zone_ordinals for the expected number of values.
  repeated string time_zone_ids = 3;
}