// Copyright 2017 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.streetview.publish.v1;

import "google/protobuf/field_mask.proto";
import "google/rpc/status.proto";
import "google/streetview/publish/v1/resources.proto";

option go_package = "google.golang.org/genproto/googleapis/streetview/publish/v1;publish";
option java_outer_classname = "StreetViewPublishRpcMessages";
option java_package = "com.google.geo.ugc.streetview.publish.v1";


// Request to create a photo.
message CreatePhotoRequest {
  // Required. Photo to create.
  Photo photo = 1;
}

// Request to get a photo.
//
// By default
// - does not return the download URL for the photo bytes.
//
// Parameters:
// - 'view' controls if the download URL for the photo bytes will be returned.
message GetPhotoRequest {
  // Required. ID of the photo.
  string photo_id = 1;

  // Specifies if a download URL for the photo bytes should be returned in the
  // Photo response.
  PhotoView view = 2;
}

// Request to get one or more photos.
// By default
// - does not return the download URL for the photo bytes.
//
// Parameters:
// - 'view' controls if the download URL for the photo bytes will be returned.
message BatchGetPhotosRequest {
  // Required. IDs of the photos.
  repeated string photo_ids = 1;

  // Specifies if a download URL for the photo bytes should be returned in the
  // Photo response.
  PhotoView view = 2;
}

// Response to batch get of photos.
message BatchGetPhotosResponse {
  // List of results for each individual photo requested, in the same order as
  // the request.
  repeated PhotoResponse results = 1;
}

// Response payload for a single `Photo` in batch operations including
// `BatchGetPhotosRequest` and `BatchUpdatePhotosRequest`.
message PhotoResponse {
  // The status for the operation to get or update a single photo in the batch
  // request.
  google.rpc.Status status = 1;

  // The photo resource, if the request was successful.
  Photo photo = 2;
}

// Request to list all photos that belong to the user sending the request.
//
// By default
// - does not return the download URL for the photo bytes.
//
// Parameters:
// - 'view' controls if the download URL for the photo bytes will be returned.
// - 'page_size' determines the maximum number of photos to return.
// - 'page_token' is the next page token value returned from a previous List
//     request, if any.
message ListPhotosRequest {
  // Specifies if a download URL for the photos bytes should be returned in the
  // Photos response.
  PhotoView view = 1;

  // The maximum number of photos to return.
  // `page_size` must be non-negative. If `page_size` is zero or is not
  // provided, the default page size of 100 will be used.
  // The number of photos returned in the response may be less than `page_size`
  // if the number of photos that belong to the user is less than `page_size`.
  int32 page_size = 2;

  // The next_page_token value returned from a previous List request, if any.
  string page_token = 3;

  // The filter expression.
  // Example: `placeId=ChIJj61dQgK6j4AR4GeTYWZsKWw`
  string filter = 4;
}

// Response to list all photos that belong to a user.
message ListPhotosResponse {
  // List of photos. There will be a maximum number of items returned based on
  // the page_size field in the request.
  repeated Photo photos = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

// Request to update the metadata of a photo.
// Updating the pixels of a photo is not supported.
message UpdatePhotoRequest {
  // Required. Photo object containing the new metadata. Only the fields
  // specified in `update_mask` are used. If `update_mask` is not present, the
  // update applies to all fields.
  // **Note:** To update `pose.altitude`, `pose.latlngpair` has to be filled as
  // well. Otherwise, the request will fail.
  Photo photo = 1;

  // Mask that identifies fields on the photo metadata to update.
  // If not present, the old Photo metadata will be entirely replaced with the
  // new Photo metadata in this request. The update fails if invalid fields are
  // specified. Multiple fields can be specified in a comma-delimited list.
  //
  // The following fields are valid:
  //
  // * `pose.heading`
  // * `pose.latlngpair`
  // * `pose.pitch`
  // * `pose.roll`
  // * `pose.level`
  // * `pose.altitude`
  // * `connections`
  // * `places`
  //
  //
  // **Note:** Repeated fields in `update_mask` mean the entire set of repeated
  // values will be replaced with the new contents. For example, if
  // `UpdatePhotoRequest.photo.update_mask` contains `connections` and
  // `UpdatePhotoRequest.photo.connections` is empty, all connections will be
  // removed.
  google.protobuf.FieldMask update_mask = 2;
}

// Request to update the metadata of photos.
// Updating the pixels of photos is not supported.
message BatchUpdatePhotosRequest {
  // Required. List of update photo requests.
  repeated UpdatePhotoRequest update_photo_requests = 1;
}

// Response to batch update of metadata of one or more photos.
message BatchUpdatePhotosResponse {
  // List of results for each individual photo updated, in the same order as
  // the request.
  repeated PhotoResponse results = 1;
}

// Request to delete a photo.
message DeletePhotoRequest {
  // Required. ID of the photo.
  string photo_id = 1;
}

// Request to delete multiple photos.
message BatchDeletePhotosRequest {
  // Required. List of delete photo requests.
  repeated string photo_ids = 1;
}

// Response to batch delete of one or more photos.
message BatchDeletePhotosResponse {
  // The status for the operation to delete a single photo in the batch request.
  repeated google.rpc.Status status = 1;
}

// Specifies which view of the `Photo` should be included in the response.
enum PhotoView {
  // Server reponses do not include the download URL for the photo bytes.
  // The default value.
  BASIC = 0;

  // Server responses include the download URL for the photo bytes.
  INCLUDE_DOWNLOAD_URL = 1;
}