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

// Adds, reads, modifies and removes the named access control lists (permission templates) of a
// vault.
//
// Use this interface to add, modify and delete named ACLs in a vault.
//
// A named ACL is a reusable set of permissions with a name, such as "Visible to company management
// only". Users pick one when they set the permissions of an object; value list items and classes
// can apply one automatically. See
// [Permissions](https://developer.m-files.com/APIs/gRPC-API/concepts/permissions/). M-Files Admin
// uses this service for the Named access control lists node of a vault.
//
// - **Session and rights.** Requires a vault session. Reading needs the vault right
//   `read_all_metadata_structure` ([VaultAccess](mfiles:MFiles.VaultAccess)); adding, modifying and
//   removing need `change_metadata_structure` and `license_allows_modifications`.
// - **Two ACLs per named ACL** ([NamedACLAdmin](mfiles:MFiles.NamedACLAdmin)):
//   `named_acl.acl_for_objects` is the permission set that objects get; `acl` controls who can see
//   and select the named ACL.
// - **Types.** `NACLTYPE_NORMAL` named ACLs are offered to users. `NACLTYPE_INTERNAL` named ACLs
//   hold automatic permissions defined on value list items and classes, and are not offered to
//   users.
// - **Built-in named ACLs** have negative IDs, for example -1 "Full control for all internal
//   users" and -20 "Only for me".
// - Objects that use a named ACL stay linked to it: modifying the named ACL can update their
//   permissions in the background, see
//   [ModifyNamedACL](mfiles:MFiles.IRPCNamedACLsAdmin.ModifyNamedACL).
//
// Users who are not administrators read the named ACLs they can select with
// [GetNamedACLs](mfiles:MFiles.IRPCNamedACLs.GetNamedACLs).
service IRPCNamedACLsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Named access control list administration" };

	// Adds a named ACL to the vault.
	//
	// - Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
	// - The name must be unique (compared case-insensitively).
	// - The server assigns the ID and the GUID; the values you send are ignored.
	rpc AddNamedACL( AddNamedACLRequest ) returns ( AddNamedACLResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the named ACLs of the given types, including the ACLs that control who sees them.
	//
	// - Requires the vault right `read_all_metadata_structure`.
	// - Built-in named ACLs (negative IDs) are included. "Current user" entries are returned as such;
	//   they are not replaced with the caller's identity as in
	//   [GetNamedACLs](mfiles:MFiles.IRPCNamedACLs.GetNamedACLs).
	// - `nacl_types` 0 returns an empty list. Names are in the session language. The order is not
	//   specified.
	rpc GetNamedACLsForAdmin( GetNamedACLsForAdminRequest ) returns ( GetNamedACLsForAdminResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether a named ACL is used in the automatic permissions of any value list item or class.
	//
	// - Requires a vault session; no vault rights are needed.
	// - A named ACL that is used in automatic permissions cannot be removed with
	//   [RemoveNamedACL](mfiles:MFiles.IRPCNamedACLsAdmin.RemoveNamedACL). An unknown ID returns
	//   false.
	rpc IsNamedACLUsedInAutomaticPermissions( IsNamedACLUsedInAutomaticPermissionsRequest ) returns ( IsNamedACLUsedInAutomaticPermissionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Changes a named ACL, and optionally the permissions of the objects that use it.
	//
	// - Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
	// - When objects must get new permissions, the server starts a background task and returns before
	//   it completes; `task_idchange_objects` identifies it.
	// - The type cannot be changed, and the name must stay unique. A named ACL used in automatic
	//   permissions cannot contain a "current user" entry.
	// - Send the complete named ACL: read it with
	//   [GetNamedACLsForAdmin](mfiles:MFiles.IRPCNamedACLsAdmin.GetNamedACLsForAdmin) first.
	rpc ModifyNamedACL( ModifyNamedACLRequest ) returns ( ModifyNamedACLResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Removes a named ACL from the vault.
	//
	// - Deletes the named ACL permanently. Objects keep their current permissions; with
	//   `allow_propagation` their link to the named ACL is removed in a background task.
	// - Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
	// - Fails if the named ACL is used in automatic permissions; check with
	//   [IsNamedACLUsedInAutomaticPermissions](mfiles:MFiles.IRPCNamedACLsAdmin.IsNamedACLUsedInAutomaticPermissions).
	// - Changes the metadata structure version.
	rpc RemoveNamedACL( RemoveNamedACLRequest ) returns ( RemoveNamedACLResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of AddNamedACL.
message AddNamedACLRequest {

	// The new named ACL. See [NamedACLAdmin](mfiles:MFiles.NamedACLAdmin).
	NamedACLAdmin named_acladmin = 1;
}

// The response of AddNamedACL.
message AddNamedACLResponse {

	// The stored named ACL with its new ID and GUID.
	NamedACLAdmin putf8sznamedacladmin = 1;
}

// The request of GetNamedACLsForAdmin.
message GetNamedACLsForAdminRequest {

	// Which types to return, as a bit mask of [NACLType](mfiles:MFiles.NACLType) values: 1 normal, 2 internal, 3 both.
	uint32 nacl_types = 1;
}

// The response of GetNamedACLsForAdmin.
message GetNamedACLsForAdminResponse {

	// The named ACLs. See [NamedACLAdmin](mfiles:MFiles.NamedACLAdmin).
	repeated NamedACLAdmin values = 1;
}

// The request of IsNamedACLUsedInAutomaticPermissions.
message IsNamedACLUsedInAutomaticPermissionsRequest {

	// The ID of the named ACL, or -2147483648 to ask whether any named ACL is used.
	int32 id = 1;
}

// The response of IsNamedACLUsedInAutomaticPermissions.
message IsNamedACLUsedInAutomaticPermissionsResponse {

	// True if the named ACL is used in automatic permissions.
	bool used_in_automatic_permissions = 1;
}

// The request of ModifyNamedACL.
message ModifyNamedACLRequest {

	// The complete new data; `named_acl.id` identifies the named ACL.
	NamedACLAdmin named_acladmin = 1;

	// True to apply the change to the objects that use the named ACL. False to leave their permissions as they are and remove their link to the named ACL.
	bool maintain_links = 2;

	// True to allow the change to reach the objects as `maintain_links` says. False to fail the call instead if any object would be affected.
	bool allow_propagation = 3;
}

// The response of ModifyNamedACL.
message ModifyNamedACLResponse {

	// The stored named ACL.
	NamedACLAdmin putf8sznamedacladmin = 1;

	// The ID of the background task that updates the objects, or -1 if no objects needed changes.
	int64 task_idchange_objects = 2;
}

// The request of RemoveNamedACL.
message RemoveNamedACLRequest {

	// The ID of the named ACL to remove.
	int32 id = 1;

	// True to remove the link from the objects that use the named ACL. False to fail the call instead if any object uses it.
	bool allow_propagation = 2;
}

// The response of RemoveNamedACL.
message RemoveNamedACLResponse {

	// The ID of the background task that updates the objects, or -1 if no objects needed changes.
	int64 task_idchange_objects = 1;
}