// 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_";

// Reads and maintains the views of the vault: the common views and the calling user's own
// (private) views.
//
// All view operations can be done via this interface.
// MFClient uses this interface to manage the user-specific view collection and common
// view collection.
//
// A view is a saved search with optional grouping levels, shown as a folder in M-Files clients.
// **Common views** are defined by administrators and are visible to the users their ACL allows.
// **Private views** belong to one user. Every user has a view collection: the common views they
// may see plus their own private views, each with a per-user visible or hidden flag. For the
// search side of views, see
// [Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/).
//
// - **Read the view collection**:
//   [GetViews](mfiles:MFiles.IRPCViews.GetViews) (all views, or the children of one view),
//   [GetViewsOrDelta](mfiles:MFiles.IRPCViews.GetViewsOrDelta) (keep a local copy up to date),
//   [GetView](mfiles:MFiles.IRPCViews.GetView) (one view).
// - **Create and change views**: [AddNewView](mfiles:MFiles.IRPCViews.AddNewView),
//   [ModifyView](mfiles:MFiles.IRPCViews.ModifyView),
//   [DeleteView](mfiles:MFiles.IRPCViews.DeleteView),
//   [SetViewVisibility](mfiles:MFiles.IRPCViews.SetViewVisibility) (per user).
// - **Share a private view** with another user:
//   [EnableShareView](mfiles:MFiles.IRPCViews.EnableShareView) by the owner, then
//   [CopyView](mfiles:MFiles.IRPCViews.CopyView) by the recipient.
// - **External repositories**: [GetMultipleViews](mfiles:MFiles.IRPCViews.GetMultipleViews) and
//   [GetExternalRepositoryIcons](mfiles:MFiles.IRPCViews.GetExternalRepositoryIcons).
// - **Traditional folders in a view**: [CreateSubFolder](mfiles:MFiles.IRPCViews.CreateSubFolder).
//
// To list the objects in a view, search with the view's `content_definition`, or browse it with
// the folder content methods of [IRPCSearch](mfiles:MFiles.IRPCSearch).
//
// **Rights.** Reading needs no special vault rights. Creating or changing private views needs the
// vault right `manage_private_views`; creating, changing or deleting common views needs
// `manage_common_views`; making a view indexed needs `materialize_views`
// ([VaultAccess](mfiles:MFiles.VaultAccess)). Anonymous sessions cannot create or delete views.
//
// **Built-in views.** Every vault has built-in views with fixed IDs, for example 5 Checked Out to
// Me, 7 Recently Modified by Me, 9 Assigned to Me, 14 Recently Accessed by Me and 15 Favorites.
// Some of them are hidden by default (for example 12 and 18 ID views, 13 Built-in, 16 Reports,
// 17 Conflicts, 23 All object types). Built-in views cannot be deleted, and most of them cannot
// be changed.
service IRPCViews {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Views" };

	// Creates a new private or common view.
	//
	// - **Private view** (`is_common` false): requires the vault right `manage_private_views`. The
	//   server replaces the ACL you send with one that gives all internal users read access; only the
	//   owner sees the view anyway.
	// - **Common view** (`is_common` true): requires `manage_common_views` and an explicit `acl`
	//   without named ACL references; an empty ACL fails with "The parameter is incorrect. (Zero
	//   length ACL.)".
	// - The server assigns `id` and `guid`; the values you send are ignored. The response has the
	//   stored view.
	// - Names must be unique, ignoring case, among the common views and the user's own views at the
	//   same level; a duplicate fails with "Another view with the same name already exists.".
	// - To place the view inside another view, set `location`. A common view needs a common parent,
	//   and a private view's parent must be a common view or one of the user's own views. Views cannot
	//   be added under the built-in views 13 (Built-in) and 23 (All object types).
	// - Indexed views (`options.indexed`) need `materialize_views`, cannot be private and cannot be
	//   filter-only views.
	// - Vault event handlers for views run. Anonymous sessions get "Access denied.".
	rpc AddNewView( AddNewViewRequest ) returns ( AddNewViewResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Replaces the definition of an existing view.
	//
	// - Send the complete view, identified by `id`: read it first, change what you need and send it
	//   back.
	// - Private views need `manage_private_views`; common views (or turning a common view into a
	//   private one, or the other way round) need `manage_common_views`. Only the owner can modify a
	//   private view; for other users it fails with "Not found.".
	// - Some built-in views cannot be changed at all, for example 12, 13, 15, 16, 17, 18 and 23. Of
	//   the views under Built-in (13) only the name and ACL can be changed, and of the views under
	//   All object types (23) only the visualization.
	// - If the grouping levels change, child views that are inside the grouping levels are deleted.
	// - A common view can be made private only if all its child views are the caller's own private
	//   views.
	// - The duplicate-name and indexing rules of [AddNewView](mfiles:MFiles.IRPCViews.AddNewView)
	//   apply. Vault event handlers for views run.
	rpc ModifyView( ModifyViewRequest ) returns ( ModifyViewResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Deletes a view and its child views.
	//
	// - Common views need `manage_common_views`; otherwise the call fails with "Deleting a common view
	//   is not allowed.". A private view can be deleted only by its owner ("Access denied." for
	//   others).
	// - Child views are deleted too, including other users' private child views of a common view.
	// - Built-in views cannot be deleted. Anonymous sessions get "Access denied.".
	// - Deleting a view that does not exist, or was already deleted, succeeds and does nothing.
	// - The view appears in `removed_views` of
	//   [GetViewsOrDelta](mfiles:MFiles.IRPCViews.GetViewsOrDelta). Vault event handlers for views
	//   run.
	rpc DeleteView( DeleteViewRequest ) returns ( DeleteViewResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets the calling user's view collection: all views, or the direct child views of one view.
	//
	// - Requires a vault session. No special vault rights are needed. Common views that the user may
	//   not see and other users' private views are left out.
	// - Hidden views are included; check `View.is_visible`.
	// - With `get_all_views` false, set `parent_view`: -1 returns the top-level views. The default 0
	//   is not the top level and returns nothing.
	// - The order of the views is not specified. Lookup values in search conditions are returned in
	//   the session's vault language.
	// - To keep a local copy in sync, use [GetViewsOrDelta](mfiles:MFiles.IRPCViews.GetViewsOrDelta)
	//   instead.
	rpc GetViews( GetViewsRequest ) returns ( GetViewsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Shows or hides a view in the calling user's view collection.
	//
	// - Affects only the calling user: hiding a common view does not hide it from other users. No
	//   special vault rights are needed.
	// - Works for common views and for the user's own private views. Hidden views are still returned
	//   by [GetViews](mfiles:MFiles.IRPCViews.GetViews), with `is_visible` false.
	rpc SetViewVisibility( SetViewVisibilityRequest ) returns ( SetViewVisibilityResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets the calling user's whole view collection, or only the changes since a version the caller
	// already has.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - First call with `callers_current_views_version` 0: `views_or_delta.type` is false (a full
	//   list) and `current_views_version_on_server` is the version to store.
	// - Later, send the stored version back:
	//   - nothing changed: the same version comes back with `type` true and empty lists;
	//   - something changed: `type` true; `views` has the added and changed views, `removed_views` the
	//     IDs of deleted views, and `invisible_views` the IDs of views the user can no longer see. Then
	//     store the new version.
	// - A version newer than the server's (for example from another vault) returns the full list and
	//   the server's current version.
	// - Hiding or showing a view with
	//   [SetViewVisibility](mfiles:MFiles.IRPCViews.SetViewVisibility) also produces a change.
	// - When a deleted view had child views, only the parent's ID appears in `removed_views`; remove
	//   its descendants from your copy too.
	rpc GetViewsOrDelta( GetViewsOrDeltaRequest ) returns ( GetViewsOrDeltaResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets icons that external repository connections provide for their views and objects.
	//
	// - Requires a vault session. The icons are requested from the external repository connections
	//   of the vault. An empty `ids` list fails with "Not found.".
	// - Each result carries its `id`, so you can match results to requests.
	rpc GetExternalRepositoryIcons( GetExternalRepositoryIconsRequest ) returns ( GetExternalRepositoryIconsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets one view of the calling user's view collection, or one external view, as folder data.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - For a vault view, set `view_id.internal_id` and set `required_folder_info.folder_info` to true;
	//   without it the call fails with "The parameter is incorrect.". Requiring `location` fails with
	//   "Not implemented.".
	// - The response holds the view in `putf8szview.data.view_folder.view`.
	// - A view that is not in the user's collection, such as another user's private view, fails with
	//   "Not found.".
	// - For a view of an external repository, set `view_id.external_repository_id` instead.
	rpc GetView( GetViewRequest ) returns ( GetViewResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets several views of external repositories in one call.
	//
	// - Only for external repository views: every ID must have `external_repository_id` set. A vault
	//   view ID fails the call with "The parameter is incorrect."; read vault views with
	//   [GetView](mfiles:MFiles.IRPCViews.GetView) or [GetViews](mfiles:MFiles.IRPCViews.GetViews).
	// - The views are requested from the external repository connections of the vault.
	rpc GetMultipleViews( GetMultipleViewsRequest ) returns ( GetMultipleViewsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Copies a private view that another user has shared, with its child views, into the caller's
	// own views.
	//
	// - The owner must first share the view with
	//   [EnableShareView](mfiles:MFiles.IRPCViews.EnableShareView). Otherwise the call fails with
	//   "This view is not shared with you.". The sharing expires after the number of days that
	//   [EnableShareView](mfiles:MFiles.IRPCViews.EnableShareView) returns (14 by default).
	// - Common views cannot be copied.
	// - The copy is a new private view at the top level of the caller's views; its child views are
	//   copied with it. Vault event handlers for views run.
	rpc CopyView( CopyViewRequest ) returns ( CopyViewResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Allows other users to copy the given private views of the caller for a limited time.
	//
	// - Only the caller's own private views can be shared; another user's view or a common view fails
	//   with "Access denied.".
	// - Sharing starts now and lasts the returned number of days. Calling again restarts the period.
	// - Other users take a copy with [CopyView](mfiles:MFiles.IRPCViews.CopyView); the original view
	//   stays private.
	rpc EnableShareView( EnableShareViewRequest ) returns ( EnableShareViewResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Creates a traditional folder at a location inside a view, or returns an existing folder with
	// the same name there.
	//
	// - `view_location.parent_folder` must not be empty, and `subfolder` must not have a parent
	//   folder; otherwise the call fails with "The parameter is incorrect.".
	// - Only works at locations that allow traditional folders; elsewhere it fails with "Sorry, but
	//   it's not possible to create traditional folders here.".
	// - If a folder with the same name exists at the location, it is returned instead of a new one.
	// - Related: [CreateOrFindTraditionalFolder](mfiles:MFiles.IRPCValueLists.CreateOrFindTraditionalFolder)
	//   creates folders outside view locations.
	rpc CreateSubFolder( CreateSubFolderRequest ) returns ( CreateSubFolderResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Not available: always fails with "Not implemented.".
	rpc GetFolderContentDownloadUrl( GetFolderContentDownloadUrlRequest ) returns ( GetFolderContentDownloadUrlResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}

	// Not available: always fails with "Not implemented.".
	rpc DownloadFolderContentWithDownloadKey( DownloadFolderContentWithDownloadKeyRequest ) returns ( DownloadFolderContentWithDownloadKeyResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}
}

// The request of AddNewView.
message AddNewViewRequest {

	// The new view. Set at least `name`, `type`, `is_common`, `is_visible` and `content_definition`; for a common view also `acl`. `id` and `guid` are ignored.
	View utf8szview = 1;
}

// The response of AddNewView.
message AddNewViewResponse {

	// The view as stored, with its new ID and GUID.
	View new_view = 1;
}

// The request of ModifyView.
message ModifyViewRequest {

	// The complete new definition of the view, with the `id` of the view to change.
	View utf8szview = 1;
}

// The response of ModifyView.
message ModifyViewResponse {
}

// The request of DeleteView.
message DeleteViewRequest {

	// The ID of the view to delete.
	int32 id = 1;
}

// The response of DeleteView.
message DeleteViewResponse {
}

// The request of GetViews.
message GetViewsRequest {

	// True to get every view in the user's collection. Then `parent_view` is ignored.
	bool get_all_views = 1;

	// With `get_all_views` false, the ID of the view whose direct child views to get, or -1 for the top-level views.
	int32 parent_view = 2;
}

// The response of GetViews.
message GetViewsResponse {

	// The views. See [View](mfiles:MFiles.View).
	repeated View views = 1;
}

// The request of SetViewVisibility.
message SetViewVisibilityRequest {

	// The ID of the view.
	int32 id = 1;

	// True to show the view, false to hide it.
	bool visible = 2;
}

// The response of SetViewVisibility.
message SetViewVisibilityResponse {
}

// The request of GetViewsOrDelta.
message GetViewsOrDeltaRequest {

	// The `current_views_version_on_server` from the caller's previous response, or 0 to get the full collection.
	int64 callers_current_views_version = 1;
}

// The response of GetViewsOrDelta.
message GetViewsOrDeltaResponse {

	// The version of the view collection now. Store it and send it next time.
	int64 current_views_version_on_server = 1;

	// The full collection (`type` false) or the changes (`type` true). See [ViewsOrDeltaEx](mfiles:MFiles.ViewsOrDeltaEx).
	ViewsOrDeltaEx views_or_delta = 2;
}

// The request of GetExternalRepositoryIcons.
message GetExternalRepositoryIconsRequest {

	// The icon IDs: the external repository connection and the icon's ID within it.
	repeated ExternalRepositoryID ids = 1;

	// `ICON_FORMAT_ICO` for a multi-size .ico file, or `ICON_FORMAT_PNG` for a PNG image of `size` pixels.
	IconFormat icon_format = 2;

	// With `ICON_FORMAT_PNG`, the width and height of the image in pixels. Ignored for `ICON_FORMAT_ICO`.
	int32 size = 3;
}

// The response of GetExternalRepositoryIcons.
message GetExternalRepositoryIconsResponse {

	// The icons; see [ExternalRepositoryIcon](mfiles:MFiles.ExternalRepositoryIcon).
	repeated ExternalRepositoryIcon icons = 1;
}

// The request of GetView.
message GetViewRequest {

	// The view: `internal_id` for a vault view, or `external_repository_id` for an external view.
	ItemID view_id = 1;

	// The folder information that must be returned. For a vault view, set `folder_info`.
	FOLDERDATAREQUESTFLAGS required_folder_info = 2;

	// Additional folder information the caller can accept. Used for external views.
	FOLDERDATAREQUESTFLAGS accepted_folder_info = 3;
}

// The response of GetView.
message GetViewResponse {

	// The view as [FolderData](mfiles:MFiles.FolderData).
	FolderData putf8szview = 1;
}

// The request of GetMultipleViews.
message GetMultipleViewsRequest {

	// The IDs of the external views, each with `external_repository_id` set.
	repeated ItemID utf8szviewids = 1;

	// The folder information that must be returned.
	FOLDERDATAREQUESTFLAGS required = 2;

	// Additional folder information the caller can accept.
	FOLDERDATAREQUESTFLAGS accepted = 3;
}

// The response of GetMultipleViews.
message GetMultipleViewsResponse {

	// The views as [FolderData](mfiles:MFiles.FolderData).
	repeated FolderData putf8szviews = 1;
}

// The request of CopyView.
message CopyViewRequest {

	// The ID of the shared view (`internal_id`).
	ItemID view_id = 1;
}

// The response of CopyView.
message CopyViewResponse {

	// The new view and its copied child views.
	repeated View putf8szviews = 1;
}

// The request of EnableShareView.
message EnableShareViewRequest {

	// The number of entries in `shared_views`. Must match.
	uint32 views_count = 1;

	// The IDs (`internal_id`) of the views to share.
	repeated ItemID shared_views = 2;
}

// The response of EnableShareView.
message EnableShareViewResponse {

	// How many days other users can copy the views, as set by the vault administrator (14 by default).
	int32 sharing_days = 1;
}

// Requests to create a sub-folder.
message CreateSubFolderRequest {

	// The location in the view: `parent_folder` starts with the view folder.
	ViewLocation view_location = 1;

	// The folder to create: `item_info.obj_id.type` 4 (Traditional folders) and `item_info.name`. The item ID is ignored.
	ValueListItem subfolder = 2;
}

// Response to create sub-folder request.
message CreateSubFolderResponse {

	// The created or found folder.
	ValueListItem folder = 1;

	// The current version of the Traditional folders list's items.
	int64 value_list_version = 2;
}

// Request details for generating a download key for downloading contents of multiple folders.
message GetFolderContentDownloadUrlRequest {

	// Download requests.
	repeated FolderContentDownloadUrlRequestData download_requests = 1;
}

// Response details for generating a download key for downloading contents of multiple folders.
message GetFolderContentDownloadUrlResponse {

	// The download URL.
	string url = 1;
}

// The request of DownloadFolderContentWithDownloadKey.
message DownloadFolderContentWithDownloadKeyRequest {

	// Contains identifier that will be used to locate the folder contents.
	StringValue download_key = 1;
}

// The response of DownloadFolderContentWithDownloadKey.
message DownloadFolderContentWithDownloadKeyResponse {
}