// 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";
import "mfiles/enums.proto";
import "mfiles/structs.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 display settings of folders per user and as common defaults.
//
// Stores the display settings of folders: which listing columns are shown and how wide, sorting,
// grouping, view mode, and the layout of the panes. Settings are kept per user and folder, and an
// administrator can save common settings that users get by default. Used by M-Files clients;
// applications rarely call it.
//
// A folder is identified by a [UISettingsFolderID](mfiles:MFiles.UISettingsFolderID): a folder type
// (`UISETTINGS_FOLDER_TYPE_...`) and, for folders inside a view, the view ID. All folders of the
// same type in one view share their settings.
//
// Two families of methods work on the same stored settings:
//
// - **Structured state** (newer clients):
//   [GetFolderUIState](mfiles:MFiles.IRPCFolderUISettings.GetFolderUIState),
//   [SetFolderUIState](mfiles:MFiles.IRPCFolderUISettings.SetFolderUIState) and
//   [ResetFolderUIStateToDefaults](mfiles:MFiles.IRPCFolderUISettings.ResetFolderUIStateToDefaults)
//   exchange a [FolderUIState](mfiles:MFiles.FolderUIState). The get and set methods take a folder
//   location (a path of [Folder](mfiles:MFiles.Folder) elements from the vault root) and resolve
//   the folder ID on the server.
// - **Opaque blobs** (M-Files Desktop):
//   [GetFolderUISettings](mfiles:MFiles.IRPCFolderUISettings.GetFolderUISettings),
//   [SaveFolderUISettings](mfiles:MFiles.IRPCFolderUISettings.SaveFolderUISettings) and
//   [ResetFolderUISettingsToDefaults](mfiles:MFiles.IRPCFolderUISettings.ResetFolderUISettingsToDefaults)
//   exchange the client's binary format. A non-empty blob starts with its data version as a 32-bit
//   little-endian integer, which must equal the version it is saved with; an empty blob means the
//   program defaults.
//
// **Data versions.** Every stored setting has a data version. Readers pass
// `max_data_version_interpretable`; the server returns the newest stored version that is not
// greater. The structured state is stored in data version 15 on current servers.
//
// **Lookup order** when reading a user's settings: the user's own settings, then the common
// settings, then the program defaults.
//
// **Rights.** Any user can store their own settings. Saving common settings, or resetting all users
// to them, needs the vault right `manage_common_uisettings`. Common settings cannot be stored for a
// folder in a user's own (not common) view, and only the owner of such a view can store settings
// for its folders. Anonymous sessions cannot save settings.
//
// [SetFolderSelection](mfiles:MFiles.IRPCFolderUISettings.SetFolderSelection) stores a different
// per-user setting: folders that the user wants to see on a view level whose listing is cut by the
// folder limit.
service IRPCFolderUISettings {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Folder UI settings" };

	// Gets the display settings of a folder as an opaque blob.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - With `common_settings` false, returns the caller's own settings, falling back to the common
	//   settings and then to the program defaults (empty `data`). With true, returns the common
	//   settings or empty `data`.
	// - Returns the newest stored data version that is at most `max_data_version_interpretable`.
	rpc GetFolderUISettings( GetFolderUISettingsRequest ) returns ( GetFolderUISettingsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Resets the caller's display settings of a folder to the program defaults or to the common
	// settings, and returns the result as an opaque blob.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Exactly one of `reset_to_program_defaults` and `reset_to_common_defaults` must be true;
	//   otherwise the call fails with "The parameter is incorrect." and nothing changes.
	// - Resetting to the common settings copies them into the caller's own settings (or stores
	//   program defaults if there are no common settings) and deletes the caller's settings of newer
	//   data versions.
	// - Only the caller's own settings change.
	rpc ResetFolderUISettingsToDefaults( ResetFolderUISettingsToDefaultsRequest ) returns ( ResetFolderUISettingsToDefaultsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Saves the display settings of a folder as an opaque blob, for the caller and optionally as the
	// common settings.
	//
	// - Requires a vault session. With `save_as_common_settings` it also needs the vault right
	//   `manage_common_uisettings`; otherwise the call fails with "Access denied.".
	// - The first four bytes of `data` must be `data_version` (32-bit little-endian), or the call fails
	//   with "The parameter is incorrect.".
	// - The settings are always saved for the caller. With `save_as_common_settings` they are also
	//   saved as the common settings. With `reset_common_settings_to_all_users` as well, every user's
	//   own settings of this folder are overwritten, and their settings of newer data versions are
	//   deleted.
	rpc SaveFolderUISettings( SaveFolderUISettingsRequest ) returns ( SaveFolderUISettingsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets the display settings of a folder location as a structure.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - The server resolves the folder from `folder_location`, for example a view folder followed by
	//   property folders. An empty location means the vault root. Set `type` for folders that a
	//   location cannot express, such as `UISETTINGS_FOLDER_TYPE_HISTORY_UI`; the resolved ID is
	//   returned in `folder_uistate.folder_id`.
	// - With `common_settings` false, returns the caller's effective settings (own, then common, then
	//   program defaults); with true, the common settings. `program_defaults` true returns the program
	//   defaults and overrides `common_settings`.
	// - Column positions in the returned listing state are not always numbered from 0: state read from
	//   settings that older clients saved can number the visible columns from 1. Renumber them before
	//   sending the state back with
	//   [SetFolderUIState](mfiles:MFiles.IRPCFolderUISettings.SetFolderUIState).
	rpc GetFolderUIState( GetFolderUIStateRequest ) returns ( GetFolderUIStateResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Saves the display settings of a folder location from a structure, for the caller and optionally
	// as the common settings.
	//
	// - Requires a vault session. Saving common settings needs the vault right
	//   `manage_common_uisettings`.
	// - The server resolves the folder from `folder_location` and `type` as in
	//   [GetFolderUIState](mfiles:MFiles.IRPCFolderUISettings.GetFolderUIState).
	// - Set `max_data_version_interpretable` to 15: the server stores the state in that data version
	//   and fails with "The parameter is incorrect." for any other value.
	// - The listing columns are validated: the visible columns must have unique positions numbered
	//   from 0 ("The first visible column should have position 0.", "Non-unique column position.").
	//   Hidden columns use position -1.
	// - With `save_as_common_settings` and `reset_common_settings_to_all_users`, every user's settings
	//   of the folder are overwritten, as with
	//   [SaveFolderUISettings](mfiles:MFiles.IRPCFolderUISettings.SaveFolderUISettings).
	rpc SetFolderUIState( SetFolderUIStateRequest ) returns ( SetFolderUIStateResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Resets the caller's display settings of a folder to the program defaults or to the common
	// settings, and returns the resulting state as a structure.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Behaves like
	//   [ResetFolderUISettingsToDefaults](mfiles:MFiles.IRPCFolderUISettings.ResetFolderUISettingsToDefaults)
	//   but returns a [FolderUIState](mfiles:MFiles.FolderUIState), so the caller can refresh its
	//   listing without another call.
	// - Exactly one of `reset_to_program_defaults` and `reset_to_common_defaults` must be true;
	//   otherwise the call fails with "The parameter is incorrect." and nothing changes.
	// - The folder is given directly as a [UISettingsFolderID](mfiles:MFiles.UISettingsFolderID), for
	//   example the `folder_id` from [GetFolderUIState](mfiles:MFiles.IRPCFolderUISettings.GetFolderUIState).
	// - Fails with "Not implemented." on servers where the feature is not enabled.
	rpc ResetFolderUIStateToDefaults( ResetFolderUIStateToDefaultsRequest ) returns ( ResetFolderUIStateToDefaultsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Replaces the calling user's folder selection for one view level: the folders that the user
	// always wants to see on a level whose listing is cut by the folder limit.
	//
	// - Not available on servers where the feature is not enabled: fails with "Not implemented."
	//   ("Folder selection is not enabled on this server.").
	// - Requires a vault session of a named user; anonymous sessions get "Access denied.".
	// - `folder_location` must be a view folder followed only by property folders, and the level it
	//   leads to must group by a property or value; other locations fail.
	// - `folders` are the property folder values as the listing returned them. Lookups are stored by
	//   item ID only, so a renamed item stays selected. Empty values, multi-select lookups and
	//   duplicates are rejected. The selection may not have more folders than the level's folder
	//   limit.
	// - An empty `folders` clears the selection. The whole selection is replaced; a failed call leaves
	//   the stored selection unchanged.
	rpc SetFolderSelection( SetFolderSelectionRequest ) returns ( SetFolderSelectionResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetFolderUISettings.
message GetFolderUISettingsRequest {

	// True for the common settings; false for the caller's effective settings.
	bool common_settings = 1;

	// The folder.
	UISettingsFolderID uisfid = 2;

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

// The response of GetFolderUISettings.
message GetFolderUISettingsResponse {

	// The settings blob, starting with its data version as a 32-bit little-endian integer; empty means the program defaults.
	bytes data = 1;
}

// The request of ResetFolderUISettingsToDefaults.
message ResetFolderUISettingsToDefaultsRequest {

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

	// True to reset to the common settings.
	bool reset_to_common_defaults = 2;

	// The folder.
	UISettingsFolderID uisfid = 3;

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

// The response of ResetFolderUISettingsToDefaults.
message ResetFolderUISettingsToDefaultsResponse {

	// The caller's settings after the reset, as returned by [GetFolderUISettings](mfiles:MFiles.IRPCFolderUISettings.GetFolderUISettings).
	bytes data = 1;
}

// The request of SaveFolderUISettings.
message SaveFolderUISettingsRequest {

	// True to also save the settings as the common settings of the folder.
	bool save_as_common_settings = 1;

	// True to also overwrite every user's settings of the folder. Used only with `save_as_common_settings`.
	bool reset_common_settings_to_all_users = 2;

	// The folder.
	UISettingsFolderID uisfid = 3;

	// The data version of `data`.
	int32 data_version = 4;

	// The settings blob, starting with `data_version` as a 32-bit little-endian integer.
	bytes data = 5;
}

// The response of SaveFolderUISettings.
message SaveFolderUISettingsResponse {
}

// The request of GetFolderUIState.
message GetFolderUIStateRequest {

	// True for the common settings; false for the caller's effective settings.
	bool common_settings = 1;

	// True when the location is an object's folder (its files) inside `folder_location`. Prefer `type` `UISETTINGS_FOLDER_TYPE_OBJECT_FILES_CONTAINER`.
	bool object_folder = 2;

	// The path of folders from the vault root to the folder. Empty for the root.
	repeated Folder folder_location = 3;

	// The newest settings data version that the caller understands. Use 15.
	int32 max_data_version_interpretable = 4;

	// The folder type, for folders whose type cannot be resolved from the location (such as the history or relationships dialogs). Leave unset to resolve it from `folder_location`.
	UISettingsFolderType type = 5;

	// True to get the program defaults, ignoring stored and common settings.
	bool program_defaults = 6;
}

// A structure that specifies the response type for the GetFolderUIState method.
message GetFolderUIStateResponse {

	// The display settings, including the resolved `folder_id`.
	FolderUIState folder_uistate = 1;

	// True when the caller has a stored folder selection (see [SetFolderSelection](mfiles:MFiles.IRPCFolderUISettings.SetFolderSelection)) for exactly this location.
	bool has_selected_folders = 2;
}

// The request of SetFolderUIState.
message SetFolderUIStateRequest {

	// True to also save the state as the common settings of the folder.
	bool save_as_common_settings = 1;

	// True to also overwrite every user's settings of the folder. Used only with `save_as_common_settings`.
	bool reset_common_settings_to_all_users = 2;

	// True when the location is an object's folder (its files) inside `folder_location`. Prefer `type` `UISETTINGS_FOLDER_TYPE_OBJECT_FILES_CONTAINER`.
	bool object_folder = 3;

	// The path of folders from the vault root to the folder. Empty for the root.
	repeated Folder folder_location = 4;

	// The data version to store. Must be 15.
	int32 max_data_version_interpretable = 5;

	// The display settings to store.
	FolderUIState folder_uistate = 6;

	// The folder type, for folders whose type cannot be resolved from the location. Leave unset to resolve it from `folder_location`.
	UISettingsFolderType type = 7;
}

// The response of SetFolderUIState.
message SetFolderUIStateResponse {
}

// The request of ResetFolderUIStateToDefaults. Exactly one of `reset_to_program_defaults` and
// `reset_to_common_defaults` must be true.
message ResetFolderUIStateToDefaultsRequest {

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

	// True to reset to the common settings.
	bool reset_to_common_defaults = 2;

	// The folder.
	UISettingsFolderID uisfid = 3;

	// The newest settings data version that the caller understands. Use 15.
	int32 max_data_version_interpretable = 4;
}

// The response of ResetFolderUIStateToDefaults: the resulting state, in the same form as the
// response of GetFolderUIState.
message ResetFolderUIStateToDefaultsResponse {

	// The caller's display settings after the reset.
	FolderUIState folder_uistate = 1;
}

// Replaces the calling user's folder selection for one folder location. The selection always belongs to
// the session's user, so the request has no user field. An empty folder array clears the selection.
message SetFolderSelectionRequest {

	// The path from the vault root to the parent of the level whose folders are selected: a view folder followed by property folders.
	repeated Folder folder_location = 1;

	// The complete new selection, as the folder values that the listing returned. Empty clears it.
	repeated TypedValue folders = 2;
}

// A structure that specifies the response type for the SetFolderSelection method.
message SetFolderSelectionResponse {

	// True when the caller has a stored selection for the location after the call.
	bool has_selected_folders = 1;
}