// Copyright 2024 Google LLC
//
// 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 = "proto3";

package com.android.adservices.shared.proto;
option java_multiple_files = true;
option java_package = "com.android.adservices.shared.proto";

// The Policy used to schedule a background job in Scheduling Policy Engine (SPE).
//
// The SPE supports singular field: Integer, Long, Boolean, String, Enum, and current it doesn't
// support repeated or composited field. Please file a request if it needs to be supported.
message JobPolicy {
  // Unique identifier of a job.
  optional int32 job_id = 1; // ** REQUIRED field **

  // Set basic description of the kind of network the job requires.
  optional NetworkType network_type = 2;

  enum NetworkType {
    // Unknown network type.
    NETWORK_TYPE_UNKNOWN = 0;

    // Default type.
    NETWORK_TYPE_NONE = 1;

    // This job requires any network connectivity.
    NETWORK_TYPE_ANY = 2;

    // This job requires network connectivity that is unmetered.
    NETWORK_TYPE_UNMETERED = 3;

    // This job requires network connectivity that is not roaming.
    NETWORK_TYPE_NOT_ROAMING = 4;

    // This job requires network connectivity that is a cellular network (metered).
    NETWORK_TYPE_CELLULAR = 5;
  }

  // Set the battery constraint for the job.
  optional BatteryType battery_type = 3;

  enum BatteryType {
    // Unknown battery type.
    BATTERY_TYPE_UNKNOWN = 0;

    // The job doesn't have any battery condition.
    BATTERY_TYPE_REQUIRE_NONE = 1;

    // The job requires the battery to be charged.
    BATTERY_TYPE_REQUIRE_CHARGING = 2;

    // The job requires the battery to be not low.
    BATTERY_TYPE_REQUIRE_NOT_LOW = 3;
  }

  // Set if the job requires the device in idle.
  optional bool require_device_idle = 4;

  // Specify that to run this job, the device's available storage must not be low.
  optional bool require_storage_not_low = 5;

  // Set whether or not to persist this job across device reboots.
  optional bool is_persisted = 6;

  // The job type for the job to schedule. It should be one of the supported types in SPE.
  oneof job_params {
    PeriodicJobParams periodic_job_params = 7;
    OneOffJobParams one_off_job_params = 8;
    TriggerContentJobParams trigger_content_job_params = 9;
  }

  // Information about a periodic job. The job will be executed periodically.
  message PeriodicJobParams {
    // The interval of a periodic job in millisecond.
    optional int64 periodic_interval_ms = 1;

    // The flex interval of a periodic job in millisecond.
    optional int64 flex_internal_ms = 2;
  }

  // Information about a one-off job. That says, the job will be only executed once.
  message OneOffJobParams {
    // Specify that this job should be delayed by the provided amount of time, in millisecond.
    optional int64 minimum_latency_ms = 1;

    // Set deadline which is the maximum scheduling latency in millisecond. The job will be ran by
    // this deadline even if other requirements aren't satisfied.
    optional int64 override_deadline_ms = 2;
  }

  // Information about a content URI modification that a job would like to trigger on.
  message TriggerContentJobParams {
    // The URI string to be parsed to build a URI.
    optional string trigger_content_uri_string = 1;

    // The maximum delay in millisecond to use before scheduling the job when triggering on content
    // URI changes.
    optional int64 trigger_content_max_delay_ms = 2;

    // The delay from when a change is detected until the job is scheduled when triggering on content
    // URI changes, in millisecond.
    optional int64 trigger_content_update_delay_ms = 3;
  }
}