// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Stores the task pane configuration of M-Files Desktop per user and for all users.
//
// Stores the task pane configuration of M-Files Desktop for each user, and a common configuration
// that administrators publish for all users. Used by M-Files clients; applications rarely call it.
//
// The configuration is an opaque blob that the client defines. The server stores it per user and
// per data version and checks only its first four bytes:
//
// - Every non-empty blob starts with its data version as a 32-bit little-endian integer, and that
//   value must equal the `data_version` it is saved with; otherwise saving fails with "The
//   parameter is incorrect.".
// - An empty blob means the program defaults.
// - Readers pass `max_data_version_interpretable`, the newest data version they understand. The
//   server returns the newest stored blob whose version is not greater; saving a version deletes
//   the caller's stored blobs of newer versions.
//
// Lookup order when reading: the user's own configuration, then the common configuration, then the
// program defaults (an empty blob).
service IRPCTaskPaneConfigurations {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Task pane configurations" };

	// Gets the calling user's task pane configuration, falling back to the common configuration and
	// then to the program defaults.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Returns the newest stored blob whose data version is at most `max_data_version_interpretable`.
	//   An empty `data` means the program defaults.
	rpc LoadTaskPaneConfiguration( LoadTaskPaneConfigurationRequest ) returns ( LoadTaskPaneConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Saves the calling user's task pane configuration.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - The first four bytes of `data_` must be `data_version` as a 32-bit little-endian integer, or
	//   the call fails with "The parameter is incorrect.". An empty `data_` stores the program
	//   defaults.
	// - Saving deletes the caller's stored configurations of newer data versions.
	rpc SaveTaskPaneConfiguration( SaveTaskPaneConfigurationRequest ) returns ( SaveTaskPaneConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Resets the calling user's task pane configuration to the program defaults or to the common
	// configuration.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - With `reset_to_program_defaults` true, the user's configuration becomes empty (program
	//   defaults). With false, the server copies the common configuration (or the program defaults if
	//   there is none) into the user's configuration.
	// - Like a save, the reset deletes the user's stored configurations of newer data versions than
	//   the one written.
	rpc ResetTaskPaneConfiguration( ResetTaskPaneConfigurationRequest ) returns ( ResetTaskPaneConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Publishes the calling user's current task pane configuration as the common configuration for all
	// users.
	//
	// - Requires the vault rights `license_allows_modifications` and `manage_common_uisettings`;
	//   otherwise fails with "Access denied.".
	// - Copies what [LoadTaskPaneConfiguration](mfiles:MFiles.IRPCTaskPaneConfigurations.LoadTaskPaneConfiguration)
	//   would return for the caller into the common configuration.
	// - With `reset_common_configuration_for_all_users` true, the server also overwrites every user's
	//   own configuration of that data version, adds it for users who have only older versions, and
	//   deletes newer versions, so all users get the published configuration.
	rpc PublishCurrentTaskPaneConfigurationAsCommonConfiguration( PublishCurrentTaskPaneConfigurationAsCommonConfigurationRequest ) returns ( PublishCurrentTaskPaneConfigurationAsCommonConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of LoadTaskPaneConfiguration.
message LoadTaskPaneConfigurationRequest {

	// The newest data version that the caller understands.
	int32 max_data_version_interpretable = 1;
}

// The response of LoadTaskPaneConfiguration.
message LoadTaskPaneConfigurationResponse {

	// The configuration blob. Its first four bytes are its data version (little-endian); empty means the program defaults.
	bytes data = 1;
}

// The request of SaveTaskPaneConfiguration.
message SaveTaskPaneConfigurationRequest {

	// The data version of the blob.
	int32 data_version = 1;

	// The configuration blob, starting with `data_version` as a 32-bit little-endian integer.
	bytes data_ = 2;
}

// The response of SaveTaskPaneConfiguration.
message SaveTaskPaneConfigurationResponse {
}

// The request of ResetTaskPaneConfiguration.
message ResetTaskPaneConfigurationRequest {

	// True to reset to the program defaults; false to reset to the common configuration.
	bool reset_to_program_defaults = 1;

	// The newest data version that the caller understands.
	int32 max_data_version_interpretable = 2;
}

// The response of ResetTaskPaneConfiguration.
message ResetTaskPaneConfigurationResponse {
}

// The request of PublishCurrentTaskPaneConfigurationAsCommonConfiguration.
message PublishCurrentTaskPaneConfigurationAsCommonConfigurationRequest {

	// True to also replace the configurations of all users with the published one.
	bool reset_common_configuration_for_all_users = 1;

	// The newest data version that the caller understands.
	int32 max_data_version_interpretable = 2;
}

// The response of PublishCurrentTaskPaneConfigurationAsCommonConfiguration.
message PublishCurrentTaskPaneConfigurationAsCommonConfigurationResponse {
}