// @file sns_std.proto
//
// Defines standard messages used across multiple Sensor API definitions
//
// Copyright (c) 2016-2018,2020 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
syntax = "proto2";
import "nanopb.proto";
import public "sns_std_type.proto";

// Framework-defined message IDs:
enum sns_std_msgid {
  option (nanopb_enumopt).long_names = false;

  // Query a Sensor for all attributes
  // @event sns_std_error_event
  SNS_STD_MSGID_SNS_STD_ATTR_REQ = 1;

  // Flush a Sensor.
  // When a sensor receives a flush request it publishes any unpublished
  // samples. The sensor always  publishes a SNS_STD_MSGID_SNS_STD_FLUSH_EVENT
  // event to indicate completion of a flush request.
  // All Sensors handle this flush request message.
  // Empty Message
  // @event sns_pb_flush_event
  SNS_STD_MSGID_SNS_STD_FLUSH_REQ = 2;

  // NOTE: 10 - 20 Are reserved for Client Manager
  // NOTE: 120-127 Are reserved

  // All published attributes for a Sensor
  SNS_STD_MSGID_SNS_STD_ATTR_EVENT = 128;

  // Indicates no further events will be generated in response to a flush req.
  // Empty Message
  SNS_STD_MSGID_SNS_STD_FLUSH_EVENT = 129;

  // Indicates an error has occurred
  SNS_STD_MSGID_SNS_STD_ERROR_EVENT = 130;

  // NOTE: 250-255 Are reserved
}

// Base message payload, from which all other Request payloads must extend
// The message will be delivered decoded within the Sensor API
message sns_std_request {
  message batch_spec {
    // Logically a timer will be registered for this many microseconds.
    // All events generated since the last timer expiration will be saved
    // until the next timer has fired.  This period is interpreted as a maximum
    // period specified by the client; events may be delivered to client at a
    // faster rate (smaller batch period).
    // A batch period of 0 indicates that no batching shall occur.
    required uint32 batch_period = 1;

    // Sensor supporting Data Acquisition Engine shall support flush_period.
    // Sensor shall not drop data that is more recent than flush_period.
    // Sensor may drop data that is older than the flush_period.
    // Effective flush period may be smaller due to system constraints,
    // or larger in the case of a concurrent client with a larger value.
    // flush_period, if set, should be greater than or equal to batch_period.
    // flush_period value defaults to UINT32_MAX; units in microseconds.
    // If batch_period > 0 and flush period not specified,
    // then flush_period = batch_period.
    optional uint32 flush_period = 2;

    // If flush_only = true, the sensor should only send data to the client
    // on receiving a flush request or if the sensor cannot accumulate flush
    // period worth of data.
    optional bool flush_only = 3 [default = false];

    // If max_batch = true for all requests, the sensor should operate at
    // maximum batching capacity. If a request has both max_batch = true
    // and flush_only = true, flush_only takes precedence.
    optional bool max_batch = 4 [default = false];
  }
  // Batching is disabled by default
  optional batch_spec batching = 1;

  // Dynamic length payload, containing the actual data/configuration request
  // This payload will need to be decoded separately, using the Sensor-specific
  // header file. If the request does not contain any message body then this
  // field is not present.
  optional bytes payload = 2;

  // Set to true if a client intends to be a passive client. Else it is an
  // active client request. Absence of this field shall be treated as an active
  // request.
  // If all requests to the sensor are passive then it shall be in off
  // state and stop streaming.
  // If the sensor has at least one active request then it shall be enabled
  // and configured according to all active and passive requests.
  // When all active clients are flush_only then passive clients are also treated
  // as flush_only.
  // When all active clients are event gated then passive clients are also treated
  // as event gated.
  // delivery_type field in passive requests shall be configured as
  // SNS_CLIENT_DELIVERY_NO_WAKEUP.
  // Actively enabling one sensor shall not lead to enabling of another
  // sensor having only passive requests. For example: enabling gyro shall not
  // lead to enabling of sensor_temperature, and vice versa.
  optional bool is_passive = 3 [default = false];

}

// Query a Sensor for its list of attributes
message sns_std_attr_req {
  // Register for updates when the attributes of a Sensor change
  // This option is not presently supported
  optional bool register_updates = 2;
}

// Contains all Sensor attributes; sent in response to an sns_std_attr_req,
// or upon an attribute change to a registered Sensor
message sns_std_attr_event {
  repeated sns_std_attr attributes = 1;
}

// An Error Event generated by a Sensor/Instance or the Framework
message sns_std_error_event {
  // SNS_STD_ERROR_NOT_AVAILABLE - Transitory error in the Sensor; some data
  //    may have been lost or dropped, but streaming should resume.
  // SNS_STD_ERROR_INVALID_STATE - Catastrophic error in the Sensor; do not
  //    expect any further data.  Client may try sending enable-request again.
  // SNS_STD_ERROR_NOT_SUPPORTED - Sensor received an unsupported request; or a
  //    supported request at an unexpected time.
  required sns_std_error error = 1;
}
