// 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 value lists and their items, and lets users add and edit value list items and traditional
// folders.
//
// Use it to fill lookup controls and to read or maintain the items of value lists. The service is
// not read-only: the remarks of its write methods list the vault rights they need. For how value
// lists relate to object types, classes and properties, see
// [Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/);
// for keeping a cached list current, see
// [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/).
//
// - **List the value lists** (and object types) of the vault:
//   [GetValueLists](mfiles:MFiles.IRPCValueLists.GetValueLists),
//   [GetValueList](mfiles:MFiles.IRPCValueLists.GetValueList).
// - **Candidate values for lookup properties** (lookup control, autocomplete), several lists per
//   call: [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems).
// - **Find items of one list** by name, ID, owner, parent or deleted state:
//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions).
// - **Keep a local copy of a list** up to date with deltas:
//   [GetValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.GetValueListItemsWithPermissions).
// - **The user's recently used values** of a lookup property:
//   [GetValueListItemProposals](mfiles:MFiles.IRPCValueLists.GetValueListItemProposals).
// - **Add, update or undelete an item**:
//   [AddValueListItemFromClient](mfiles:MFiles.IRPCValueLists.AddValueListItemFromClient),
//   [UpdateValueListItemFromClient](mfiles:MFiles.IRPCValueLists.UpdateValueListItemFromClient),
//   [UndeleteValueListItem](mfiles:MFiles.IRPCValueLists.UndeleteValueListItem).
// - **Traditional folders**:
//   [CreateOrFindTraditionalFolder](mfiles:MFiles.IRPCValueLists.CreateOrFindTraditionalFolder),
//   [RenameValueListItemFromClient](mfiles:MFiles.IRPCValueLists.RenameValueListItemFromClient),
//   [RemoveValueListItemFromClient](mfiles:MFiles.IRPCValueLists.RemoveValueListItemFromClient),
//   [RemoveOrDestroyTraditionalFolder](mfiles:MFiles.IRPCValueLists.RemoveOrDestroyTraditionalFolder),
//   [ChangeValueListItemPermissionsFromClient](mfiles:MFiles.IRPCValueLists.ChangeValueListItemPermissionsFromClient).
// - **Permissions of an item**:
//   [GetValueListItemPermissions](mfiles:MFiles.IRPCValueLists.GetValueListItemPermissions),
//   [CheckAccessToValueListItem](mfiles:MFiles.IRPCValueLists.CheckAccessToValueListItem).
//
// **IDs.** Value lists and object types share one ID space: an object type is a value list whose
// items are objects (`ValueList.is_real_object_type`). The item calls accept both, so
// [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems) returns customers for object type
// 136 just as it returns countries for value list 154. An item is identified by an
// [ObjID](mfiles:MFiles.ObjID): `type` is the value list ID and `item_id.internal_id` the item
// ID. Item IDs are unique only within one list. Lookup property values
// ([PropertyDef](mfiles:MFiles.PropertyDef) with `is_based_on_value_list`) point to items of
// `PropertyDef.value_list`. Built-in lists keep their IDs in every vault, for example 1 Classes,
// 2 Class groups, 4 Traditional folders, 6 Users, 7 Workflows, 8 Workflow states, 16 User groups.
//
// **Item search conditions.** The `search_conditions` of the item searches are
// [SearchCondition](mfiles:MFiles.SearchCondition)s whose expression is a property value
// (`EXPRESSION_TYPE_PROPERTY_VALUE`) on one of these pseudo property definition IDs. They exist
// only in item searches; ordinary property definitions are rejected with "Invalid search
// condition.". Conditions are combined with AND.
//
// | ID | Item field | Value (`TypedValue`) | Example condition type |
// | --- | --- | --- | --- |
// | 1 | Item ID | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
// | 2 | Name | `DATATYPE_TEXT` | `CONDITION_TYPE_CONTAINS`, `CONDITION_TYPE_STARTS_WITH` (case-insensitive) |
// | 3 | Owner item | `DATATYPE_LOOKUP` (`lookup.value_list_item_info.obj_id` = owner item) | `CONDITION_TYPE_EQUAL` |
// | 4 | Parent item | `DATATYPE_INTEGER`, or unset for top-level items | `CONDITION_TYPE_EQUAL` |
// | 5 | Deleted | `DATATYPE_BOOLEAN` | `CONDITION_TYPE_EQUAL` |
// | 6 | Object type | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
// | 7 | External (display) ID | `DATATYPE_TEXT` | `CONDITION_TYPE_EQUAL` |
// | 8 | GUID | `DATATYPE_TEXT` (with braces) | `CONDITION_TYPE_EQUAL` |
//
// To search objects by their properties, use [SearchObjects](mfiles:MFiles.IRPCSearch.SearchObjects)
// instead. Item lists are not covered by the metadata structure version: adding or changing items does not
// change the `mfiles-metadata-version-bin` trailer, so do not cache items by it.
service IRPCValueLists {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_CORE title: "Value lists" };

	// Changes the permissions of a traditional folder.
	//
	// - Works only for Traditional folders (value list 4); other lists fail with "Access denied.".
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
	//   and read access to the folder.
	// - `visible` tells whether the caller can still see the folder under the new permissions.
	rpc ChangeValueListItemPermissionsFromClient( ChangeValueListItemPermissionsFromClientRequest ) returns ( ChangeValueListItemPermissionsFromClientResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Checks whether the calling user has the given access under an access control list that the
	// caller supplies.
	//
	// - Evaluates the ACL against the user's identity and group memberships, which the caller may not
	//   know. Nothing in the vault is changed.
	// - `allowed` is unset (false) when the user lacks any of the requested rights.
	rpc CheckAccessToValueListItem( CheckAccessToValueListItemRequest ) returns ( CheckAccessToValueListItemResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Deletes a traditional folder (marks it deleted).
	//
	// - Works only for Traditional folders (value list 4); other lists fail with "Access denied.".
	//   `allow_removing_owned_items` must be false; true also fails with "Access denied.".
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
	//   and read access to the folder.
	// - Related: [RemoveOrDestroyTraditionalFolder](mfiles:MFiles.IRPCValueLists.RemoveOrDestroyTraditionalFolder)
	//   also handles the folder's contents.
	rpc RemoveValueListItemFromClient( RemoveValueListItemFromClientRequest ) returns ( RemoveValueListItemFromClientResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Restores a deleted item of a plain value list, together with its deleted parent items.
	//
	// - Requires the vault rights `license_allows_modifications` and
	//   `manage_value_list_items_from_client` (for Traditional folders: `manage_traditional_folders`).
	// - Not for real object types: they fail with "Not found."; undelete objects with
	//   [UndeleteObject](mfiles:MFiles.IRPCObjectOperations.UndeleteObject).
	// - Find deleted items with the condition Deleted (5) equal to true in
	//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions).
	rpc UndeleteValueListItem( UndeleteValueListItemRequest ) returns ( UndeleteValueListItemResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}

	// Adds a new item to a value list, as a user.
	//
	// - Requires a vault session whose user has the vault rights `manage_value_list_items_from_client`
	//   and `license_allows_modifications` ([VaultAccess](mfiles:MFiles.VaultAccess)); otherwise the
	//   call fails with "Access denied.".
	// - The list must allow new items (`ValueList.options.can_add_items`), and the user must be
	//   allowed to add items to it (`ValueList.object_type_permissions.can_user_add_new_items`).
	//   Otherwise the call fails with "Access denied." or "You are not allowed to add new values to
	//   the list ...".
	// - Only plain value lists: a real object type fails with "Not found." (create objects with
	//   [AddObject](mfiles:MFiles.IRPCObjectOperations.AddObject)), and Traditional folders (4) fail
	//   with "The parameter is incorrect." (use
	//   [CreateOrFindTraditionalFolder](mfiles:MFiles.IRPCValueLists.CreateOrFindTraditionalFolder)).
	// - The name must not be empty. `has_parent` is allowed only in hierarchical lists and
	//   `has_owner` only in lists that are not hierarchical; violations fail with an error.
	// - The server assigns the item ID and a new GUID; the values you send are ignored. Names do not
	//   have to be unique, so a retried call creates a second item with the same name: search by name
	//   first if the call may be repeated.
	// - The new item gets the list's default permissions for new items. If the user could not see the
	//   new item, the call fails and nothing is added.
	// - For a list connected to an external database, the item is also written to that database.
	//   Vault event handlers for new value list items run.
	// - Adding items does not change the metadata structure version. Remove items with the administration
	//   service ([RemoveObjectTypeItem](mfiles:MFiles.IRPCObjectTypesAdmin.RemoveObjectTypeItem));
	//   this service cannot remove items of ordinary value lists.
	rpc AddValueListItemFromClient( AddValueListItemFromClientRequest ) returns ( AddValueListItemFromClientResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Creates a traditional folder, or returns an existing folder with the same name.
	//
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`.
	// - The item must be in Traditional folders (`item_info.obj_id.type` 4) and have a name; it cannot
	//   have an owner. Set `has_parent` and `parent_id` for a subfolder.
	// - Names are compared case-insensitively. A deleted folder with the same name is always
	//   undeleted and returned, whatever `can_return_existing_folder` says.
	// - The response lists the folder and its parent folders.
	rpc CreateOrFindTraditionalFolder( CreateOrFindTraditionalFolderRequest ) returns ( CreateOrFindTraditionalFolderResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Renames a traditional folder.
	//
	// - Works only for Traditional folders (value list 4); other lists fail with "The parameter is
	//   incorrect.". The new name must not be empty.
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
	//   and read access to the folder.
	rpc RenameValueListItemFromClient( RenameValueListItemFromClientRequest ) returns ( RenameValueListItemFromClientResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets all value lists of the vault, including the object types, without icons.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Returns plain value lists (such as Classes, Users or Country) **and** real object types; use
	//   `is_real_object_type` to tell them apart. `icon` is always empty here; get icons with
	//   [GetObjectTypes](mfiles:MFiles.IRPCObjectTypes.GetObjectTypes).
	// - Lists that the user is not allowed to see are returned with empty `name_singular` and
	//   `name_plural` and `object_type_permissions.can_user_see` false.
	// - `options.can_add_items` and `object_type_permissions.can_user_add_new_items` together tell
	//   whether [AddValueListItemFromClient](mfiles:MFiles.IRPCValueLists.AddValueListItemFromClient)
	//   can add items to the list for this user.
	// - Names are in the session language when the vault has translations for it.
	// - Cacheable by metadata structure version. Returns the lists only, not their items: get items with
	//   [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems).
	rpc GetValueLists( GetValueListsRequest ) returns ( GetValueListsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets one value list or object type by ID, without its icon.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Accepts both value list IDs and object type IDs. An unknown ID fails with "Not found.".
	// - A list the user cannot see is returned with empty names; it does not fail.
	// - Cacheable by metadata structure version. Same data as
	//   [GetObjectType](mfiles:MFiles.IRPCObjectTypes.GetObjectType) without the icon.
	rpc GetValueList( GetValueListRequest ) returns ( GetValueListResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Updates an item of a plain value list or a traditional folder, as a user.
	//
	// - Requires the vault rights `license_allows_modifications` and
	//   `manage_value_list_items_from_client` (for Traditional folders, list 4:
	//   `manage_traditional_folders`), and read access to the item.
	// - Not for real object types ("Not found."), the Classes list (1) or the Class groups list (2)
	//   ("The parameter is incorrect."), or lists whose `options.is_external` is set (this includes
	//   built-in lists such as Users and Workflows).
	// - Send the complete item: read it first (for example with
	//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions)),
	//   change what you need and send it back.
	// - The response echoes the item you sent; fields you left out (such as the GUID) come back
	//   empty even though the stored values are unchanged. Re-read the item if you need them.
	rpc UpdateValueListItemFromClient( UpdateValueListItemFromClientRequest ) returns ( UpdateValueListItemFromClientResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Deletes or destroys a traditional folder and everything in it.
	//
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`,
	//   and read access to the folder.
	// - With `destroy` true the folder and its contents are destroyed permanently.
	rpc RemoveOrDestroyTraditionalFolder( RemoveOrDestroyTraditionalFolderRequest ) returns ( RemoveOrDestroyTraditionalFolderResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets the permissions of one item of a plain value list.
	//
	// - Requires read access to the item; otherwise fails with an access denied error.
	// - Not for real object types ("Not found."): get object permissions from
	//   [IRPCObjectOperations](mfiles:MFiles.IRPCObjectOperations).
	rpc GetValueListItemPermissions( GetValueListItemPermissionsRequest ) returns ( GetValueListItemPermissionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets the items of one value list or object type, or only the changes since a known version.
	//
	// - Requires a vault session. No special vault rights are needed; items the user cannot see are
	//   left out. Deleted items are not returned (except as `removed_items` in a delta).
	// - Meant for clients that keep a local copy of a list. First call with `known_version` 0 and
	//   store `current_version`. Later, send it back as `known_version` with `allow_delta`:
	//   - unchanged list: same `current_version`, no items;
	//   - changed list: `is_delta` true, `items` has the added and changed items and `removed_items`
	//     the IDs of deleted ones;
	//   - if the server cannot give a delta, `is_delta` is false and `items` is the full list.
	// - The server limits the number of items (`results_limit` in the response, 5000 by default);
	//   `has_more_results` tells whether the list was cut. For large lists use
	//   [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems) with a name condition.
	rpc GetValueListItemsWithPermissions( GetValueListItemsWithPermissionsRequest ) returns ( GetValueListItemsWithPermissionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Searches the items of one value list or object type by item ID, name, owner, parent or deleted
	// state.
	//
	// - Requires a vault session. No special vault rights are needed; items the user is not allowed
	//   to see are left out.
	// - Works for plain value lists and for real object types (whose items are objects). For the
	//   supported conditions, see the item search conditions table in the
	//   [IRPCValueLists](mfiles:MFiles.IRPCValueLists) overview. Property values of objects cannot
	//   be searched here: use [SearchObjects](mfiles:MFiles.IRPCSearch.SearchObjects).
	// - **Deleted items are included** by default and flagged with `item_info.options.is_deleted`.
	//   Add the condition Deleted (5) equal to false to get only existing items, or equal to true for
	//   only deleted ones. [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems) leaves
	//   deleted items out by default.
	// - `results_limit` 0 returns all matching items. With a limit, `has_more_results` tells whether
	//   more items matched; there is no paging.
	// - In hierarchical lists, the parents of matching items are returned too.
	// - With `include_permissions`, `item_acls` and `item_current_user_permissions` have one entry
	//   per item, in the order of `items`.
	// - The order of the items is not specified.
	// - An unknown list fails with "Not found.". Not cacheable.
	rpc SearchValueListItemsWithPermissions( SearchValueListItemsWithPermissionsRequest ) returns ( SearchValueListItemsWithPermissionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets the selectable items of one or more value lists or object types in one call, for example
	// to fill lookup controls.
	//
	// - Requires a vault session. No special vault rights are needed; items the user is not allowed
	//   to see are left out.
	// - One [LookupItemRequest](mfiles:MFiles.LookupItemRequest) per list. The response has one
	//   [LookupItemResponse](mfiles:MFiles.LookupItemResponse) per request, in request order;
	//   identical requests are run once and their result copied.
	// - **Deleted items are left out** unless a request has the condition Deleted (5) equal to true,
	//   in which case only deleted items are returned. This differs from
	//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions).
	// - Set `LookupItemRequest.property_def` to the lookup property being edited to apply that
	//   property's value filter (`PropertyDef.value_list_item_filter`); use -1 for no filter.
	// - `results_limit` unset or 0 returns all matching items. When a list has more items than the
	//   limit, `has_more_results` is true; narrow the search with a name condition instead of paging
	//   (there is no offset).
	// - In hierarchical lists, the parents of matching items are returned too, so a response can
	//   contain more items than `results_limit`.
	// - The order of the items is not specified; sort on the client.
	// - If any request names an unknown list, the whole call fails with "Not found.".
	// - For external lists, `external_data_source_refresh` can refresh the list from its external
	//   database before the read. Not cacheable: item lists change without a metadata structure version change.
	// - Related: [GetValueListItemProposals](mfiles:MFiles.IRPCValueLists.GetValueListItemProposals)
	//   for the user's recently used values.
	rpc GetLookupItems( GetLookupItemsRequest ) returns ( GetLookupItemsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets the values that the calling user has most recently used for a lookup property.
	//
	// - Requires a vault session. Returns at most five items, the most recently used first. Deleted
	//   items and items the user cannot see are left out.
	// - A property that is not a lookup, or that the user has not used yet, gives an empty list.
	// - Use it to offer quick picks next to a lookup control filled with
	//   [GetLookupItems](mfiles:MFiles.IRPCValueLists.GetLookupItems).
	rpc GetValueListItemProposals( GetValueListItemProposalsRequest ) returns ( GetValueListItemProposalsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Creates a tree of traditional folders under one anchor in one transaction: either every folder
	// is created or the call fails and nothing is saved.
	//
	// - Not available in this version: the server fails the call with "Not implemented.". Use
	//   [CreateOrFindTraditionalFolder](mfiles:MFiles.IRPCValueLists.CreateOrFindTraditionalFolder)
	//   for each folder instead.
	// - Requires the vault rights `license_allows_modifications` and `manage_traditional_folders`.
	rpc CreateFolderTree( CreateFolderTreeRequest ) returns ( CreateFolderTreeResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}
}

// The request of ChangeValueListItemPermissionsFromClient.
message ChangeValueListItemPermissionsFromClientRequest {

	// The folder: `type` 4 and the folder's item ID.
	ObjID obj_id = 1;

	// The new access control list of the folder.
	AccessControlList acl = 2;
}

// The response of ChangeValueListItemPermissionsFromClient.
message ChangeValueListItemPermissionsFromClientResponse {

	// True if the caller can still see the folder after the change.
	bool visible = 1;
}

// The request of CheckAccessToValueListItem.
message CheckAccessToValueListItemRequest {

	// The access control list to evaluate, for example one returned by [GetValueListItemPermissions](mfiles:MFiles.IRPCValueLists.GetValueListItemPermissions).
	AccessControlList utf8szacl = 1;

	// The rights to check, for example `read` or `edit`. All of them must be granted.
	ObjectAccess required = 2;
}

// The response of CheckAccessToValueListItem.
message CheckAccessToValueListItemResponse {

	// True if the user has all the `required` rights under the ACL.
	bool allowed = 1;
}

// The request of RemoveValueListItemFromClient.
message RemoveValueListItemFromClientRequest {

	// The folder: `type` 4 and the folder's item ID.
	ObjID obj_id = 1;

	// Must be false; the server rejects true with "Access denied.".
	bool allow_removing_owned_items = 2;
}

// The response of RemoveValueListItemFromClient.
message RemoveValueListItemFromClientResponse {
}

// The request of UndeleteValueListItem.
message UndeleteValueListItemRequest {

	// The item: `type` is the value list ID, `item_id.internal_id` the item ID.
	ObjID obj_id = 1;
}

// The response of UndeleteValueListItem.
message UndeleteValueListItemResponse {
}

// The request of AddValueListItemFromClient.
message AddValueListItemFromClientRequest {

	// The item to add. Set `item_info.obj_id.type` to the value list ID and `item_info.name`; for a hierarchical list set `has_parent` and `parent_id`, for a list with an owner list set `has_owner` and `owner_id`. The item ID and GUID are ignored.
	ValueListItem utf8szvlitem = 1;
}

// The response of AddValueListItemFromClient.
message AddValueListItemFromClientResponse {

	// The new item as stored, with its new item ID and GUID.
	ValueListItem result = 1;
}

// The request of CreateOrFindTraditionalFolder.
message CreateOrFindTraditionalFolderRequest {

	// The folder to create: `item_info.obj_id.type` 4, `item_info.name`, and for a subfolder `has_parent` and `parent_id`. The item ID is ignored.
	ValueListItem vl_item = 1;

	// True to return an existing folder with the same name (compared case-insensitively) instead of failing.
	bool can_return_existing_folder = 2;
}

// The response of CreateOrFindTraditionalFolder.
message CreateOrFindTraditionalFolderResponse {

	// The created or found folder and its parent folders.
	repeated ValueListItem putf8szvlitems = 1;

	// The current version of the Traditional folders list's items (see `GetValueListItemsWithPermissions.known_version`).
	int64 current_version_on_server = 2;
}

// The request of RenameValueListItemFromClient.
message RenameValueListItemFromClientRequest {

	// The folder: `type` 4 and the folder's item ID.
	ObjID obj_id = 1;

	// The new name; must not be empty.
	string new_name = 2;
}

// The response of RenameValueListItemFromClient.
message RenameValueListItemFromClientResponse {

	// The renamed folder and its parent folders.
	repeated ValueListItem items = 1;

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

// The request of GetValueLists.
message GetValueListsRequest {

	// The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`.
	CallImportance call_importance = 1;
}

// The response of GetValueLists.
message GetValueListsResponse {

	// All value lists and object types, including those the user cannot see (with empty names). See [ValueList](mfiles:MFiles.ValueList).
	repeated ValueList value_lists = 1;
}

// The request of GetValueList.
message GetValueListRequest {

	// The ID of the value list or object type.
	int32 value_list = 1;
}

// The response of GetValueList.
message GetValueListResponse {

	// The value list. See [ValueList](mfiles:MFiles.ValueList).
	ValueList object_type_basic = 1;
}

// The request of UpdateValueListItemFromClient.
message UpdateValueListItemFromClientRequest {

	// The complete item, identified by `item_info.obj_id` (value list ID and item ID).
	ValueListItem vl_item = 1;
}

// The response of UpdateValueListItemFromClient.
message UpdateValueListItemFromClientResponse {

	// The item as sent in the request.
	ValueListItem result = 1;
}

// The request of RemoveOrDestroyTraditionalFolder.
message RemoveOrDestroyTraditionalFolderRequest {

	// Must be 4 (Traditional folders); any other value fails.
	int32 folder_structure = 1;

	// The item ID of the folder.
	int32 folder = 2;

	// True to destroy the folder and its contents permanently, false to mark them deleted.
	bool destroy = 3;
}

// The response of RemoveOrDestroyTraditionalFolder.
message RemoveOrDestroyTraditionalFolderResponse {

	// The IDs of the objects that were deleted or destroyed.
	repeated ObjID objects = 1;
}

// The request of GetValueListItemPermissions.
message GetValueListItemPermissionsRequest {

	// The item: `type` is the value list ID, `item_id.internal_id` the item ID.
	ObjID obj_id = 1;
}

// The response of GetValueListItemPermissions.
message GetValueListItemPermissionsResponse {

	// The access control list of the item.
	AccessControlList putf8szacl = 1;

	// What the calling user may do with the item.
	ObjectPermissionsForClient object_permissions = 2;
}

// The request of GetValueListItemsWithPermissions.
message GetValueListItemsWithPermissionsRequest {

	// The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`.
	CallImportance call_importance = 1;

	// For a list connected to an external database: whether to refresh it from the database first.
	ExtDBRefreshType external_data_source_refresh = 2;

	// The ID of the value list or object type.
	int32 value_list = 3;

	// The ID of a lookup property definition whose value filter is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition.
	int32 filtering_property_def = 4;

	// The `current_version` from the caller's previous response, or 0 to get the full list. With 0 the server never returns a delta.
	int64 known_version = 5;

	// True to accept only the changes since `known_version`.
	bool allow_delta = 6;

	// True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID.
	bool resolve_current_user_placeholders = 7;

	// True to fill `item_acls` and `item_current_user_permissions`.
	bool include_permissions = 8;
}

// The response of GetValueListItemsWithPermissions.
message GetValueListItemsWithPermissionsResponse {

	// The current version of the list's items. Store it and send it as `known_version` next time. It changes when items change, not with the metadata structure version.
	int64 current_version = 1;

	// True if `items` and `removed_items` are only the changes since `known_version`.
	bool is_delta = 2;

	// In a delta, the IDs of items deleted since `known_version`; otherwise empty.
	repeated int32 removed_items = 3;

	// The items, or in a delta the added and changed items.
	repeated ValueListItem items = 4;

	// With `include_permissions`, the access control list of each item, in the order of `items`.
	repeated AccessControlList item_acls = 5;

	// With `include_permissions`, what the caller may do with each item, in the order of `items`.
	repeated ObjectPermissionsForClient item_current_user_permissions = 8;

	// True if the list has more items than `results_limit`.
	bool has_more_results = 6;

	// The item limit the server applied (0 when no items were returned).
	uint32 results_limit = 7;
}

// The request of SearchValueListItemsWithPermissions.
message SearchValueListItemsWithPermissionsRequest {

	// The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`.
	CallImportance call_importance = 1;

	// For a list connected to an external database: whether to refresh it from the database before the search. `EXT_DBREFRESH_TYPE_NONE` reads the items the vault already has.
	ExtDBRefreshType external_data_source_refresh = 2;

	// The ID of the value list or object type to search.
	int32 value_list = 3;

	// The ID of a lookup property definition whose value filter (`PropertyDef.value_list_item_filter`) is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title).
	int32 filtering_property_def = 4;

	// Conditions on the item pseudo properties 1-8 (see the service overview), combined with AND. Empty returns all items, deleted ones included.
	repeated SearchCondition search_conditions = 5;

	// True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID.
	bool resolve_current_user_placeholders = 6;

	// True to fill `item_acls` and `item_current_user_permissions`.
	bool include_permissions = 7;

	// The maximum number of items to return; 0 returns all.
	uint32 results_limit = 8;
}

// The response of SearchValueListItemsWithPermissions.
message SearchValueListItemsWithPermissionsResponse {

	// The matching items. See [ValueListItem](mfiles:MFiles.ValueListItem).
	repeated ValueListItem items = 1;

	// With `include_permissions`, the access control list of each item, in the order of `items`; otherwise empty.
	repeated AccessControlList item_acls = 2;

	// With `include_permissions`, what the caller may do with each item, in the order of `items`; otherwise empty.
	repeated ObjectPermissionsForClient item_current_user_permissions = 4;

	// True if more items matched than `results_limit` allowed.
	bool has_more_results = 3;
}

// Request for getting lookup items of multiple object types or value lists (lookup types).
message GetLookupItemsRequest {

	// One request per value list or object type. See [LookupItemRequest](mfiles:MFiles.LookupItemRequest).
	repeated LookupItemRequest requests = 1;

	// True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID.
	bool resolve_current_user_placeholders = 2;

	// True to fill `acl` and `current_user_permissions` of each returned item. Leave false if you need only IDs and names.
	bool include_permissions = 3;

	// 0 for no timeout. Otherwise the server checks the elapsed time between the steps of the call and fails it with a timeout error once the limit has passed.
	uint32 timeout_in_seconds = 4;
}

// Search multiple object type items response.
message GetLookupItemsResponse {

	// One result per request, in the order of `requests`.
	repeated LookupItemResponse lookup_item_results = 1;
}

// Request for getting proposed values for a lookup property.
message GetValueListItemProposalsRequest {

	// The ID of the lookup property definition whose recently used values are wanted.
	uint32 property_def_id = 1;
}

// Response for getting proposed values for a lookup property.
message GetValueListItemProposalsResponse {

	// Up to five items, most recently used first.
	repeated ValueListItem proposed_values = 1;
}

// Requests to create a tree of Traditional Folders under one anchor.
message CreateFolderTreeRequest {

	// Where the tree is attached.
	FolderTreeAnchorType anchor_type = 1;

	// The ID of the existing folder to create the tree in, as known to the client (the folder the user drops onto). Required for the folder anchor, not allowed for the others. Not the ID of any folder in the request: those are created by the server and returned in the response.
	optional int32 anchor_folder_id = 2;

	// The anchor view location. Required for the viewLocation anchor, not allowed for the others.
	ViewLocation view_location = 3;

	// The folders to create under the anchor, parents before children.
	repeated FolderTreeNode nodes = 4;

	// What to do when a folder name is used by a sibling: false fails the whole request, true gives the folder the name "<name> (n)".
	bool rename_on_conflict = 5;
}

// Response to a create folder tree request. Always describes a fully created tree.
message CreateFolderTreeResponse {

	// One result per submitted folder, in the order of the request.
	repeated FolderTreeNodeResult nodes = 1;

	// The current version of the Traditional Folders value list's data on the server.
	int64 current_version_on_server = 2;
}