// Copyright 2018 Google Inc.
//
// 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 google.cloud.iot.v1;

import "google/api/annotations.proto";
import "google/cloud/iot/v1/resources.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option go_package = "google.golang.org/genproto/googleapis/cloud/iot/v1;iot";
option java_multiple_files = true;
option java_outer_classname = "DeviceManagerProto";
option java_package = "com.google.cloud.iot.v1";


// Internet of things (IoT) service. Allows to manipulate device registry
// instances and the registration of devices (Things) to the cloud.
service DeviceManager {
  // Creates a device registry that contains devices.
  rpc CreateDeviceRegistry(CreateDeviceRegistryRequest) returns (DeviceRegistry) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*}/registries"
      body: "device_registry"
    };
  }

  // Gets a device registry configuration.
  rpc GetDeviceRegistry(GetDeviceRegistryRequest) returns (DeviceRegistry) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/registries/*}"
    };
  }

  // Updates a device registry configuration.
  rpc UpdateDeviceRegistry(UpdateDeviceRegistryRequest) returns (DeviceRegistry) {
    option (google.api.http) = {
      patch: "/v1/{device_registry.name=projects/*/locations/*/registries/*}"
      body: "device_registry"
    };
  }

  // Deletes a device registry configuration.
  rpc DeleteDeviceRegistry(DeleteDeviceRegistryRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=projects/*/locations/*/registries/*}"
    };
  }

  // Lists device registries.
  rpc ListDeviceRegistries(ListDeviceRegistriesRequest) returns (ListDeviceRegistriesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*/locations/*}/registries"
    };
  }

  // Creates a device in a device registry.
  rpc CreateDevice(CreateDeviceRequest) returns (Device) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*/registries/*}/devices"
      body: "device"
    };
  }

  // Gets details about a device.
  rpc GetDevice(GetDeviceRequest) returns (Device) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}"
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}"
      }
    };
  }

  // Updates a device.
  rpc UpdateDevice(UpdateDeviceRequest) returns (Device) {
    option (google.api.http) = {
      patch: "/v1/{device.name=projects/*/locations/*/registries/*/devices/*}"
      body: "device"
      additional_bindings {
        patch: "/v1/{device.name=projects/*/locations/*/registries/*/groups/*/devices/*}"
        body: "device"
      }
    };
  }

  // Deletes a device.
  rpc DeleteDevice(DeleteDeviceRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=projects/*/locations/*/registries/*/devices/*}"
      additional_bindings {
        delete: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}"
      }
    };
  }

  // List devices in a device registry.
  rpc ListDevices(ListDevicesRequest) returns (ListDevicesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*/locations/*/registries/*}/devices"
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*/groups/*}/devices"
      }
    };
  }

  // Modifies the configuration for the device, which is eventually sent from
  // the Cloud IoT Core servers. Returns the modified configuration version and
  // its metadata.
  rpc ModifyCloudToDeviceConfig(ModifyCloudToDeviceConfigRequest) returns (DeviceConfig) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/locations/*/registries/*/devices/*}:modifyCloudToDeviceConfig"
      body: "*"
      additional_bindings {
        post: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}:modifyCloudToDeviceConfig"
        body: "*"
      }
    };
  }

  // Lists the last few versions of the device configuration in descending
  // order (i.e.: newest first).
  rpc ListDeviceConfigVersions(ListDeviceConfigVersionsRequest) returns (ListDeviceConfigVersionsResponse) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/configVersions"
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/configVersions"
      }
    };
  }

  // Lists the last few versions of the device state in descending order (i.e.:
  // newest first).
  rpc ListDeviceStates(ListDeviceStatesRequest) returns (ListDeviceStatesResponse) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/states"
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/states"
      }
    };
  }

  // Sets the access control policy on the specified resource. Replaces any
  // existing policy.
  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v1/{resource=projects/*/locations/*/registries/*}:setIamPolicy"
      body: "*"
      additional_bindings {
        post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:setIamPolicy"
        body: "*"
      }
    };
  }

  // Gets the access control policy for a resource.
  // Returns an empty policy if the resource exists and does not have a policy
  // set.
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v1/{resource=projects/*/locations/*/registries/*}:getIamPolicy"
      body: "*"
      additional_bindings {
        post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:getIamPolicy"
        body: "*"
      }
    };
  }

  // Returns permissions that a caller has on the specified resource.
  // If the resource does not exist, this will return an empty set of
  // permissions, not a NOT_FOUND error.
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
    option (google.api.http) = {
      post: "/v1/{resource=projects/*/locations/*/registries/*}:testIamPermissions"
      body: "*"
      additional_bindings {
        post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:testIamPermissions"
        body: "*"
      }
    };
  }
}

// Request for `CreateDeviceRegistry`.
message CreateDeviceRegistryRequest {
  // The project and cloud region where this device registry must be created.
  // For example, `projects/example-project/locations/us-central1`.
  string parent = 1;

  // The device registry. The field `name` must be empty. The server will
  // generate that field from the device registry `id` provided and the
  // `parent` field.
  DeviceRegistry device_registry = 2;
}

// Request for `GetDeviceRegistry`.
message GetDeviceRegistryRequest {
  // The name of the device registry. For example,
  // `projects/example-project/locations/us-central1/registries/my-registry`.
  string name = 1;
}

// Request for `DeleteDeviceRegistry`.
message DeleteDeviceRegistryRequest {
  // The name of the device registry. For example,
  // `projects/example-project/locations/us-central1/registries/my-registry`.
  string name = 1;
}

// Request for `UpdateDeviceRegistry`.
message UpdateDeviceRegistryRequest {
  // The new values for the device registry. The `id` field must be empty, and
  // the `name` field must indicate the path of the resource. For example,
  // `projects/example-project/locations/us-central1/registries/my-registry`.
  DeviceRegistry device_registry = 1;

  // Only updates the `device_registry` fields indicated by this mask.
  // The field mask must not be empty, and it must not contain fields that
  // are immutable or only set by the server.
  // Mutable top-level fields: `event_notification_config`, `http_config`,
  // `mqtt_config`, and `state_notification_config`.
  google.protobuf.FieldMask update_mask = 2;
}

// Request for `ListDeviceRegistries`.
message ListDeviceRegistriesRequest {
  // The project and cloud region path. For example,
  // `projects/example-project/locations/us-central1`.
  string parent = 1;

  // The maximum number of registries to return in the response. If this value
  // is zero, the service will select a default size. A call may return fewer
  // objects than requested, but if there is a non-empty `page_token`, it
  // indicates that more entries are available.
  int32 page_size = 2;

  // The value returned by the last `ListDeviceRegistriesResponse`; indicates
  // that this is a continuation of a prior `ListDeviceRegistries` call, and
  // that the system should return the next page of data.
  string page_token = 3;
}

// Response for `ListDeviceRegistries`.
message ListDeviceRegistriesResponse {
  // The registries that matched the query.
  repeated DeviceRegistry device_registries = 1;

  // If not empty, indicates that there may be more registries that match the
  // request; this value should be passed in a new
  // `ListDeviceRegistriesRequest`.
  string next_page_token = 2;
}

// Request for `CreateDevice`.
message CreateDeviceRequest {
  // The name of the device registry where this device should be created.
  // For example,
  // `projects/example-project/locations/us-central1/registries/my-registry`.
  string parent = 1;

  // The device registration details. The field `name` must be empty. The server
  // will generate that field from the device registry `id` provided and the
  // `parent` field.
  Device device = 2;
}

// Request for `GetDevice`.
message GetDeviceRequest {
  // The name of the device. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  string name = 1;

  // The fields of the `Device` resource to be returned in the response. If the
  // field mask is unset or empty, all fields are returned.
  google.protobuf.FieldMask field_mask = 2;
}

// Request for `UpdateDevice`.
message UpdateDeviceRequest {
  // The new values for the device registry. The `id` and `num_id` fields must
  // be empty, and the field `name` must specify the name path. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0`or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  Device device = 2;

  // Only updates the `device` fields indicated by this mask.
  // The field mask must not be empty, and it must not contain fields that
  // are immutable or only set by the server.
  // Mutable top-level fields: `credentials`, `blocked`, and `metadata`
  google.protobuf.FieldMask update_mask = 3;
}

// Request for `DeleteDevice`.
message DeleteDeviceRequest {
  // The name of the device. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  string name = 1;
}

// Request for `ListDevices`.
message ListDevicesRequest {
  // The device registry path. Required. For example,
  // `projects/my-project/locations/us-central1/registries/my-registry`.
  string parent = 1;

  // A list of device numerical ids. If empty, it will ignore this field. This
  // field cannot hold more than 10,000 entries.
  repeated uint64 device_num_ids = 2;

  // A list of device string identifiers. If empty, it will ignore this field.
  // For example, `['device0', 'device12']`. This field cannot hold more than
  // 10,000 entries.
  repeated string device_ids = 3;

  // The fields of the `Device` resource to be returned in the response. The
  // fields `id`, and `num_id` are always returned by default, along with any
  // other fields specified.
  google.protobuf.FieldMask field_mask = 4;

  // The maximum number of devices to return in the response. If this value
  // is zero, the service will select a default size. A call may return fewer
  // objects than requested, but if there is a non-empty `page_token`, it
  // indicates that more entries are available.
  int32 page_size = 100;

  // The value returned by the last `ListDevicesResponse`; indicates
  // that this is a continuation of a prior `ListDevices` call, and
  // that the system should return the next page of data.
  string page_token = 101;
}

// Response for `ListDevices`.
message ListDevicesResponse {
  // The devices that match the request.
  repeated Device devices = 1;

  // If not empty, indicates that there may be more devices that match the
  // request; this value should be passed in a new `ListDevicesRequest`.
  string next_page_token = 2;
}

// Request for `ModifyCloudToDeviceConfig`.
message ModifyCloudToDeviceConfigRequest {
  // The name of the device. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  string name = 1;

  // The version number to update. If this value is zero, it will not check the
  // version number of the server and will always update the current version;
  // otherwise, this update will fail if the version number found on the server
  // does not match this version number. This is used to support multiple
  // simultaneous updates without losing data.
  int64 version_to_update = 2;

  // The configuration data for the device.
  bytes binary_data = 3;
}

// Request for `ListDeviceConfigVersions`.
message ListDeviceConfigVersionsRequest {
  // The name of the device. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  string name = 1;

  // The number of versions to list. Versions are listed in decreasing order of
  // the version number. The maximum number of versions retained is 10. If this
  // value is zero, it will return all the versions available.
  int32 num_versions = 2;
}

// Response for `ListDeviceConfigVersions`.
message ListDeviceConfigVersionsResponse {
  // The device configuration for the last few versions. Versions are listed
  // in decreasing order, starting from the most recent one.
  repeated DeviceConfig device_configs = 1;
}

// Request for `ListDeviceStates`.
message ListDeviceStatesRequest {
  // The name of the device. For example,
  // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or
  // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`.
  string name = 1;

  // The number of states to list. States are listed in descending order of
  // update time. The maximum number of states retained is 10. If this
  // value is zero, it will return all the states available.
  int32 num_states = 2;
}

// Response for `ListDeviceStates`.
message ListDeviceStatesResponse {
  // The last few device states. States are listed in descending order of server
  // update time, starting from the most recent one.
  repeated DeviceState device_states = 1;
}
