/*
 * Copyright (C) 2018 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.os.statsd;
option java_package = "com.android.os";
option java_multiple_files = true;
option java_outer_classname = "AtomFieldOptions";

import "google/protobuf/descriptor.proto";

enum StateField {
    // Default value for fields that are not primary or exclusive state.
    STATE_FIELD_UNSET = 0;
    // Fields that represent the key that the state belongs to.
    PRIMARY = 1;
    // The field that represents the state. It's an exclusive state.
    EXCLUSIVE = 2;
}

// Used to annotate an atom that reprsents a state change. A state change atom must have exactly ONE
// exclusive state field, and any number of primary key fields.
// For example,
// message UidProcessStateChanged {
//    optional int32 uid = 1 [(stateFieldOption).option = PRIMARY];
//    optional android.app.ProcessStateEnum state = 2 [(stateFieldOption).option = EXCLUSIVE];
//  }
// Each of this UidProcessStateChanged atom represents a state change for a specific uid.
// A new state automatically overrides the previous state.
//
// If the atom has 2 or more primary fields, it means the combination of the primary fields are
// the primary key.
// For example:
// message ThreadStateChanged {
//    optional int32 pid = 1  [(stateFieldOption).option = PRIMARY];
//    optional int32 tid = 2  [(stateFieldOption).option = PRIMARY];
//    optional int32 state = 3 [(stateFieldOption).option = EXCLUSIVE];
// }
//
// Sometimes, there is no primary key field, when the state is GLOBAL.
// For example,
//
// message ScreenStateChanged {
//    optional android.view.DisplayStateEnum state = 1 [(stateFieldOption).option = EXCLUSIVE];
// }
//
// Only fields of primary types can be annotated. AttributionNode cannot be primary keys (and they
// usually are not).
message StateAtomFieldOption {
    optional StateField option = 1 [default = STATE_FIELD_UNSET];
}

extend google.protobuf.FieldOptions {
    // Flags to decorate an atom that presents a state change.
    optional StateAtomFieldOption stateFieldOption = 50000;
}