// ###############################################################
// Copyright(c) Carl Zeiss AG, Germany. All Rights Reserved.
//
// Permission is granted to use and distribute this code,
// as long as this copyright notice remains part of the code.
// ###############################################################

syntax = "proto3";
package zen_api.acquisition.v1beta;
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";
import "zen_api/acquisition/v1beta/experiment_descriptor.proto";
import "zen_api/acquisition/v1beta/experiment_status.proto";

// The ExperimentServiceCloneRequest class.
message ExperimentServiceCloneRequest {
   // Id of the experiment to be cloned.
   string experiment_id = 1;
}
// Response object of the method for cloning an experiment.
message ExperimentServiceCloneResponse {
   // The experiment id which is used to reference the cloned experiment.
   string experiment_id = 1;
}
// The ExperimentServiceDeleteRequest class.
message ExperimentServiceDeleteRequest {
   // Name of the experiment to be deleted.
   string experiment_name = 1;
}
// The ExperimentServiceDeleteResponse class.
message ExperimentServiceDeleteResponse {
}
// The ExperimentServiceExportRequest class.
message ExperimentServiceExportRequest {
   // Experiment id.
   string experiment_id = 1;
}
// Response object of the method for exporting an experiment.
message ExperimentServiceExportResponse {
   // Xml string of experiment.
   string xml = 1;
}
// The ExperimentServiceGetAvailableExperimentsRequest class.
message ExperimentServiceGetAvailableExperimentsRequest {
}
// Response object of available experiments.
message ExperimentServiceGetAvailableExperimentsResponse {
   // List of available experiments.
   repeated ExperimentDescriptor experiments = 1;
}
// The ExperimentServiceGetImageOutputPathRequest class.
message ExperimentServiceGetImageOutputPathRequest {
}
// Response object of the method for getting the image output path.
message ExperimentServiceGetImageOutputPathResponse {
   // The image output path.
   string image_output_path = 1;
}
// The ExperimentServiceGetStatusRequest class.
message ExperimentServiceGetStatusRequest {
   // ID of an experiment for which status is requested.
   // If ID is provided, the status can be retrieved for both active and finished experiments.
   // If ID is not provided, status of one of the active experiments is returned.
   // If ID is not provided and there are no active experiments, an exception is thrown.
   string experiment_id = 1;
}
// Response object representing the status of an experiment.
message ExperimentServiceGetStatusResponse {
   // The experiment status.
   ExperimentStatus status = 1;
}
// The ExperimentServiceImportRequest class.
message ExperimentServiceImportRequest {
   // Xml string of the experiment.
   string xml_string = 1;
}
// Response object of the method for importing an experiment.
message ExperimentServiceImportResponse {
   // The experiment id which is used to reference the imported experiment.
   string experiment_id = 1;
}
// The ExperimentServiceLoadRequest class.
message ExperimentServiceLoadRequest {
   // Name of the experiment.
   string experiment_name = 1;
}
// Response object of the method for loading an experiment.
message ExperimentServiceLoadResponse {
   // The experiment id which is used to reference the loaded experiment.
   string experiment_id = 1;
}
// The ExperimentServiceRegisterOnStatusChangedRequest class.
message ExperimentServiceRegisterOnStatusChangedRequest {
   // ID of an active experiment for which status is monitored.
   // If ID is not provided, status of one of the active experiments is monitored.
   string experiment_id = 1;
}
// Response object representing the status of an experiment.
// It contains full set of status information, which can consist a single or multiple new states.
message ExperimentServiceRegisterOnStatusChangedResponse {
   // The experiment status.
   ExperimentStatus status = 1;
}
// The ExperimentServiceRunExperimentRequest class.
message ExperimentServiceRunExperimentRequest {
   // Experiment id.
   string experiment_id = 1;
   // Optional name of the experiment's output. If a null or an empty name is provided, the
   // output name will be created automatically, otherwise the output name must be in a format
   // of a file name without a file extension.
   string output_name = 2;
}
// Information about execution of an experiment.
message ExperimentServiceRunExperimentResponse {
   // The name of the experiment's output (in a format of a file name without a
   // file extension).
   string output_name = 1;
}
// The ExperimentServiceRunSnapRequest class.
message ExperimentServiceRunSnapRequest {
   // Experiment id.
   string experiment_id = 1;
   // Optional name of the experiment's output. If a null or an empty name is provided, the
   // output name will be created automatically, otherwise the output name must be in a format
   // of a file name without a file extension.
   string output_name = 2;
}
// Information about execution of a snap experiment.
message ExperimentServiceRunSnapResponse {
   // The name of the snap's output (in a format of a file name without a file
   // extension).
   string output_name = 1;
}
// The ExperimentServiceSaveRequest class.
message ExperimentServiceSaveRequest {
   // Experiment id.
   string experiment_id = 1;
   // Name to be used when saving the experiment.
   string experiment_name = 2;
   // Allow override of already existing experiment with the same name.
   bool allow_override = 3;
}
// The ExperimentServiceSaveResponse class.
message ExperimentServiceSaveResponse {
}
// The ExperimentServiceStartContinuousRequest class.
message ExperimentServiceStartContinuousRequest {
   // Experiment id.
   string experiment_id = 1;
}
// The ExperimentServiceStartExperimentRequest class.
message ExperimentServiceStartExperimentRequest {
   // Experiment id.
   string experiment_id = 1;
   // Optional name of the experiment's output. If a null or an empty name is provided, the
   // output name will be created automatically, otherwise the output name must be in a format
   // of a file name without a file extension.
   string output_name = 2;
}
// Information about execution of an experiment.
message ExperimentServiceStartExperimentResponse {
   // The name of the experiment's output (in a format of a file name without a
   // file extension).
   string output_name = 1;
}
// The ExperimentServiceStartLiveRequest class.
message ExperimentServiceStartLiveRequest {
   // Experiment id.
   string experiment_id = 1;
   // Optional track index. When index is not provided the first selected or activated track
   // (in that order) will be used, but when the index is provided the track with than index
   // will be selected. The track index starts with "0".
   .google.protobuf.Int32Value track_index = 2;
}
// The ExperimentServiceStartSnapRequest class.
message ExperimentServiceStartSnapRequest {
   // Experiment id.
   string experiment_id = 1;
   // Optional name of the experiment's output. If a null or an empty name is provided, the
   // output name will be created automatically, otherwise the output name must be in a format
   // of a file name without a file extension.
   string output_name = 2;
}
// Information about execution of a snap experiment.
message ExperimentServiceStartSnapResponse {
   // The name of the snap's output (in a format of a file name without a file
   // extension).
   string output_name = 1;
}
// The ExperimentServiceStopRequest class.
message ExperimentServiceStopRequest {
   // ID of an experiment to stop or an empty GUID to stop one of the active experiments.
   string experiment_id = 1;
}
// Information about execution of an experiment.
message ExperimentServiceStopResponse {
   // The ID of the experiment which is used to reference the stopped experiment.
   string experiment_id = 1;
}
// The IExperimentService interface.
service ExperimentService {
   // Clones an already loaded experiment. Useful when one wants to clone an experiment before
   // modifying it in order to preserve the original experiment. This method returns the info
   // needed to reference the cloned experiment.
   rpc Clone (ExperimentServiceCloneRequest) returns (ExperimentServiceCloneResponse);
   // Deletes an experiment file from the predefined location on disk.
   // It does not delete the corresponding loaded experiment instance.
   rpc Delete (ExperimentServiceDeleteRequest) returns (ExperimentServiceDeleteResponse);
   // Returns xml representation of an experiment.
   rpc Export (ExperimentServiceExportRequest) returns (ExperimentServiceExportResponse)
   {
      option idempotency_level = NO_SIDE_EFFECTS;
   }
   // Retrieves a list of all available experiments of the system.
   rpc GetAvailableExperiments (ExperimentServiceGetAvailableExperimentsRequest) returns (ExperimentServiceGetAvailableExperimentsResponse)
   {
      option idempotency_level = NO_SIDE_EFFECTS;
   }
   // Gets the location where the images will be stored on the machine where ZEN Client is
   // running.
   rpc GetImageOutputPath (ExperimentServiceGetImageOutputPathRequest) returns (ExperimentServiceGetImageOutputPathResponse)
   {
      option idempotency_level = NO_SIDE_EFFECTS;
   }
   // Gets status of an experiment.
   // The information is updated in interval (several times per seconds). As a result, some
   // status updates could be skipped.
   rpc GetStatus (ExperimentServiceGetStatusRequest) returns (ExperimentServiceGetStatusResponse)
   {
      option idempotency_level = NO_SIDE_EFFECTS;
   }
   // Imports an experiment from the provided experiment xml string. This method returns the
   // info needed to reference the imported experiment.
   rpc Import (ExperimentServiceImportRequest) returns (ExperimentServiceImportResponse);
   // Loads an experiment from the available experiments. Consequently, the experiment is
   // ready to be executed or modified. This method returns the info needed to reference the
   // loaded experiment.
   rpc Load (ExperimentServiceLoadRequest) returns (ExperimentServiceLoadResponse);
   // Register on experiment status changed events.
   // The information is updated in interval (several times per seconds). As a result, some
   // status updates could be skipped.
   // The notifications can be retrieved for experiments which are active at the time the
   // method is invoked. If the method is invoked after an experiment is finished, the call
   // will throw an exception.
   rpc RegisterOnStatusChanged (ExperimentServiceRegisterOnStatusChangedRequest) returns (stream ExperimentServiceRegisterOnStatusChangedResponse)
   {
      option idempotency_level = NO_SIDE_EFFECTS;
   }
   // Executes an experiment and waits until the experiment execution is finished. This means
   // that the method will block until the experiment was successfully completed, it fails, or
   // it is cancelled. If the call is interrupted (e.g., caller is not available anymore) the
   // experiment will be stopped.
   rpc RunExperiment (ExperimentServiceRunExperimentRequest) returns (ExperimentServiceRunExperimentResponse);
   // Acquires a single snap image with the activated channels in the specified experiment and
   // waits until the process of acquiring snap is finished. This means that the method will
   // block until the experiment was successfully completed, it fails, or it is cancelled. If
   // the call is interrupted (e.g., caller is not available anymore) the snap will be stopped.
   rpc RunSnap (ExperimentServiceRunSnapRequest) returns (ExperimentServiceRunSnapResponse);
   // Saves a loaded experiment to the predefined location on disk.
   rpc Save (ExperimentServiceSaveRequest) returns (ExperimentServiceSaveResponse);
   // Starts the continuous with the activated channels in the specified experiment and waits
   // for the acquisition to start. After that point continuous will run until it is
   // explicitly stopped or it fails - even if the caller is not available anymore.
   rpc StartContinuous (ExperimentServiceStartContinuousRequest) returns (.google.protobuf.Empty);
   // Starts the process of executing an experiment and waits for the acquisition to start.
   // After that point the experiment will either run to completion (successful or not) or
   // until it is explicitly stopped - even if the caller is not available anymore.
   rpc StartExperiment (ExperimentServiceStartExperimentRequest) returns (ExperimentServiceStartExperimentResponse);
   // Starts live with the requested track in the specified experiment and waits for the
   // acquisition to start. After that point live will run until it is explicitly stopped or
   // it fails - even if the caller is not available anymore.
   rpc StartLive (ExperimentServiceStartLiveRequest) returns (.google.protobuf.Empty);
   // Starts the process of acquiring a single snap image with the activated channels in the
   // specified experiment and waits for the acquisition to start. After that point the
   // snap will either run to completion (successful or not) or until it is explicitly
   // stopped - even if the caller is not available anymore.
   rpc StartSnap (ExperimentServiceStartSnapRequest) returns (ExperimentServiceStartSnapResponse);
   // Stops the specified experiment or one of the active experiments if the experiment ID is
   // not provided. This will stop any type of experiment (i.e., experiment, snap, continuous,
   // live) if it is active and known to this service. This method returns the info needed to
   // reference the stopped experiment.
   rpc Stop (ExperimentServiceStopRequest) returns (ExperimentServiceStopResponse);
}