// 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 writes named values: small key-value settings stored in the vault, grouped by
// storage type and namespace.
//
// Named value storage keeps configuration and state for applications, vault applications and
// M-Files itself. A value is addressed by three things:
//
// 1. **Storage type** ([NamedValueType](mfiles:MFiles.NamedValueType)): decides who can read and
//    write, and whether the value is shared or private to one user.
// 2. **Namespace**: a string of at most 100 characters, for example `"MyCompany.MyApp"`. Choose
//    one that is unique to your application.
// 3. **Key**: the `key` of a [NamedValue](mfiles:MFiles.NamedValue), at most 100 characters. The
//    value is a [TypedValue](mfiles:MFiles.TypedValue), usually `DATATYPE_TEXT` or
//    `DATATYPE_MULTILINE_TEXT` holding the setting as text.
//
// Use the same spelling and case for namespaces and keys every time; keys that differ only in
// case are stored as separate values.
//
// | Storage type | Who can read | Who can write and remove |
// | --- | --- | --- |
// | `NAMED_VALUE_TYPE_USER_CONFIGURATION_VALUE` | any user | any user (shared by all users) |
// | `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` | the user only | the user only (private to each user) |
// | `NAMED_VALUE_TYPE_METADATA_CONFIGURATION_VALUE` | any user | vault right `change_metadata_structure` |
// | `NAMED_VALUE_TYPE_FOLDER_CONFIGURATION_VALUE` | any user | vault right `manage_common_views` |
// | `NAMED_VALUE_TYPE_ADMIN_CONFIGURATION_VALUE` | vault right `read_all_metadata_structure` | vault right `change_metadata_structure` |
// | `NAMED_VALUE_TYPE_SYSTEM_CONFIGURATION_VALUE` | system administrators | `change_metadata_structure` and full server rights |
// | `NAMED_VALUE_TYPE_REGISTRY_VALUE` | any user | nobody (read-only) |
//
// `NAMED_VALUE_TYPE_PROPERTY_AUTOMATIC_NUMBERING` and `NAMED_VALUE_TYPE_VAULT_SHARED_VARIABLE`
// are not accessible through this service ("Access denied."), and
// `NAMED_VALUE_TYPE_UNINITIALIZED` fails with "The parameter is incorrect.". Anonymous sessions
// cannot set values. Vault rights are in [VaultAccess](mfiles:MFiles.VaultAccess).
//
// Some namespaces of the configuration types hold M-Files' own vault configuration, such as vault
// settings and metadata card configuration. Writing to them changes how the vault behaves and can
// change the metadata structure version. Do not write to namespaces that your application does not own.
service IRPCNamedValueStorage {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Named value storage" };

	// Gets all named values of one storage type and namespace.
	//
	// - Requires a vault session; the read rights depend on `storage_type` (see the service
	//   overview). A storage type the caller cannot read fails with "Access denied.".
	// - Returns every value in the namespace, sorted by key. An unknown namespace returns an empty
	//   list, not an error.
	// - With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` only the calling user's own values are returned.
	// - A namespace longer than 100 characters fails with "The parameter is incorrect. (Too long
	//   namespace.)".
	rpc GetNamedValues( GetNamedValuesRequest ) returns ( GetNamedValuesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Removes named values from one namespace by key.
	//
	// - Requires a vault session; the write rights depend on `storage_type` (see the service
	//   overview).
	// - Keys that do not exist are ignored; the call succeeds.
	// - With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` only the calling user's own values are removed.
	rpc RemoveNamedValues( RemoveNamedValuesRequest ) returns ( RemoveNamedValuesResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Creates or replaces the given named values in one namespace, optionally only if the current
	// values are as expected.
	//
	// - Requires a vault session; the write rights depend on `storage_type` (see the service
	//   overview). Anonymous sessions get "Access denied.".
	// - Only the keys in `values` are written; other keys in the namespace stay as they are. Each
	//   written key gets the new value as a whole.
	// - **Optimistic concurrency** with `required_existing_value`: every listed key must currently
	//   have exactly the listed value, or, if the listed value is empty, must have no value. If any of
	//   them differs, nothing is written and the call fails with "An SQL update statement yielded a
	//   probable lock conflict." (0x800403F9). Read the values again, merge and retry.
	// - If no value would change, nothing is written.
	// - With `NAMED_VALUE_TYPE_USER_SPECIFIC_VALUE` the values are stored for the calling user only.
	rpc SetNamedValues( SetNamedValuesRequest ) returns ( SetNamedValuesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetNamedValues.
message GetNamedValuesRequest {

	// The storage type to read. See the table in the service overview.
	NamedValueType storage_type = 1;

	// The namespace, for example `"MyCompany.MyApp"`.
	string namespace_name = 2;
}

// The response of GetNamedValues.
message GetNamedValuesResponse {

	// The values of the namespace, sorted by key.
	repeated NamedValue values = 1;
}

// The request of RemoveNamedValues.
message RemoveNamedValuesRequest {

	// The storage type of the values.
	NamedValueType storage_type = 1;

	// The namespace of the values.
	string namespace_name = 2;

	// The keys of the values to remove.
	repeated string keys = 3;
}

// The response of RemoveNamedValues.
message RemoveNamedValuesResponse {
}

// The request of SetNamedValues.
message SetNamedValuesRequest {

	// The storage type to write. See the table in the service overview.
	NamedValueType storage_type = 1;

	// The namespace, at most 100 characters.
	string namespace_name = 2;

	// The values to create or replace. Keys are at most 100 characters.
	repeated NamedValue values = 3;

	// Optional. Values that must be current before the write, typically the values you read with [GetNamedValues](mfiles:MFiles.IRPCNamedValueStorage.GetNamedValues). A key with an empty value means "must not exist". On a mismatch the call fails with 0x800403F9 and nothing is written.
	repeated NamedValue required_existing_value = 4;
}

// The response of SetNamedValues.
message SetNamedValuesResponse {
}