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

// An interface for retrieving property definitions.
//
// Provides methods for read-only access to PropertyDefs.
//
// Reads property definitions and classes: what metadata objects can have and how it is grouped.
//
// | Job | Call |
// | --- | --- |
// | All property definitions (names, data types, lookup targets) | [GetPropertyDefs](mfiles:MFiles.IRPCPropertyDefs.GetPropertyDefs) |
// | One property definition | [GetPropertyDef](mfiles:MFiles.IRPCPropertyDefs.GetPropertyDef) |
// | All classes and class groups | [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups) |
// | One class, for example to build a metadata card | [GetObjectClass](mfiles:MFiles.IRPCPropertyDefs.GetObjectClass) |
//
// **ID spaces.** Property definition IDs, class IDs, class group IDs and object type IDs are
// separate number spaces; the same number means different things in each.
//
// - A property definition ID identifies a property such as 0 (Name or title), 100 (Class) or
//   1079 (Customer). Built-in property definitions have the same ID in every vault.
// - A class is an item of value list 1 (Classes); its ID is
//   `base_info.item_info.obj_id.item_id.internal_id` of [ObjectClass](mfiles:MFiles.ObjectClass).
//   Class 0 is Document; the default classes of some built-in object types have negative IDs
//   (for example -100 Assignment). A class belongs to exactly one object type
//   (`ObjectClass.object_type`).
// - A class group is an item of value list 2 (Class groups).
// - A lookup property points to an object type or value list with `PropertyDef.value_list`.
//
// IDs of custom property definitions and classes differ between vaults: resolve them by alias or
// GUID with [GetMetadataStructureItemIdByAlias](mfiles:MFiles.IRPCVault.GetMetadataStructureItemIdByAlias).
//
// How property values are written and read is described in
// [Properties and values](https://developer.m-files.com/APIs/gRPC-API/concepts/properties-and-values/).
//
// All four calls are cacheable by the metadata structure version (`mfiles-metadata-version-bin` trailer).
// [GetPropertyDefs](mfiles:MFiles.IRPCPropertyDefs.GetPropertyDefs) and
// [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups) also take
// a `known_version`, so a client that keeps a cache can ask for the data only when it has changed.
service IRPCPropertyDefs {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_CORE title: "Property definitions and classes" };

	// Gets all property definitions that the user is allowed to see.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Property definitions that the user cannot see (because of the property definition's
	//   permissions) are left out. The owner property definitions of built-in object types that can
	//   never have an owner are also left out.
	// - Names are in the session language when the vault has translations for it.
	// - **Change check:** send the `current_version` of the previous response as `known_version`. If
	//   nothing has changed, the response has the same `current_version` and an **empty**
	//   `property_defs`: keep your cached list, do not treat it as "no property definitions". Send 0
	//   to always get the full list. This version counter is separate from the class version of
	//   [GetObjectClassesAndGroups](mfiles:MFiles.IRPCPropertyDefs.GetObjectClassesAndGroups).
	// - Whether a property is required depends on the class, not on the property definition: read
	//   `associated_property_defs` of [ObjectClass](mfiles:MFiles.ObjectClass).
	// - Cacheable by metadata structure version.
	rpc GetPropertyDefs( GetPropertyDefsRequest ) returns ( GetPropertyDefsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets one property definition by ID.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Fails with the error message "You can't get access to the property ..." both when the ID
	//   does not exist and when the user is not allowed to see the property definition. IDs 1-19
	//   are never real property definitions (see
	//   [SearchValueListItemsWithPermissions](mfiles:MFiles.IRPCValueLists.SearchValueListItemsWithPermissions)
	//   for their use in value list item searches).
	// - `property_def_permissions` is set only when the property definition has its own permissions.
	// - Cacheable by metadata structure version.
	rpc GetPropertyDef( GetPropertyDefRequest ) returns ( GetPropertyDefResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets all classes and class groups that the user is allowed to see.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Returns the classes of all object types; group or filter them by `object_type`.
	// - Deleted classes are left out, and so are classes and class groups the user is not allowed to
	//   see. In each class, `associated_property_defs` lists only the property definitions the user
	//   can see.
	// - `current_user_permissions.can_user_attach_objects` tells whether the user may attach objects
	//   to the class; offer only such classes when the user creates an object.
	// - **Change check:** send the `current_version` of the previous response as `known_version`. If
	//   nothing has changed, the response has the same `current_version` and **empty** `classes` and
	//   `class_groups`. Send 0 to always get everything.
	// - Names are in the session language when the vault has translations for it.
	// - Cacheable by metadata structure version.
	rpc GetObjectClassesAndGroups( GetObjectClassesAndGroupsRequest ) returns ( GetObjectClassesAndGroupsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets one class by ID, with the property definitions associated with it.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Use it to build a metadata card or to check properties before
	//   [AddObject](mfiles:MFiles.IRPCObjectOperations.AddObject): the class gives
	//   the required and optional properties (`associated_property_defs`), the property used as the
	//   object's name (`name_property_def`) and the default workflow.
	// - A class that does not exist, or that the user is not allowed to see, fails with the error
	//   message "Not found.". A deleted class also fails unless `allow_deleted` is true.
	// - `associated_property_defs` lists only the property definitions the user can see.
	// - Cacheable by metadata structure version.
	rpc GetObjectClass( GetObjectClassRequest ) returns ( GetObjectClassResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}
}

// The request of GetPropertyDefs.
message GetPropertyDefsRequest {

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

	// Ignored by the server; the response is the same for true and false.
	bool include_icons = 2;

	// The `current_version` from the caller's previous response, or 0 to get all property definitions. If it equals the server's current version, `property_defs` is empty.
	int32 known_version = 3;
}

// The response of GetPropertyDefs.
message GetPropertyDefsResponse {

	// The current version of the property definitions on the server. Store it and send it as `known_version` next time.
	int32 current_version = 1;

	// The property definitions the user can see, or empty if `known_version` was current. See [PropertyDef](mfiles:MFiles.PropertyDef).
	repeated PropertyDef property_defs = 2;

	// Always empty. Required properties are defined per class: see `ObjectClass.associated_property_defs`.
	repeated bool is_property_def_required = 3;
}

// The request of GetPropertyDef.
message GetPropertyDefRequest {

	// The ID of the property definition.
	int32 property_def = 1;

	// Ignored by the server.
	bool icons = 2;
}

// The response of GetPropertyDef.
message GetPropertyDefResponse {

	// The property definition. See [PropertyDef](mfiles:MFiles.PropertyDef).
	PropertyDef value = 1;
}

// The request of GetObjectClassesAndGroups.
message GetObjectClassesAndGroupsRequest {

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

	// The `current_version` from the caller's previous response, or 0 to get all classes and class groups. If it is still current, both result lists are empty.
	int64 known_version = 2;
}

// The response of GetObjectClassesAndGroups.
message GetObjectClassesAndGroupsResponse {

	// The current version of the classes on the server. Store it and send it as `known_version` next time.
	int64 current_version = 1;

	// The classes the user can see, or empty if `known_version` was current. See [ObjectClass](mfiles:MFiles.ObjectClass).
	repeated ObjectClass classes = 2;

	// The class groups the user can see, or empty if `known_version` was current. See [ClassGroup](mfiles:MFiles.ClassGroup).
	repeated ClassGroup class_groups = 3;
}

// The request of GetObjectClass.
message GetObjectClassRequest {

	// The ID of the class (an item ID in value list 1, Classes). 0 is the Document class; some built-in classes have negative IDs.
	int32 class_id = 1;

	// True to return the class even if it has been deleted.
	bool allow_deleted = 2;
}

// The response of GetObjectClass.
message GetObjectClassResponse {

	// The class. See [ObjectClass](mfiles:MFiles.ObjectClass).
	ObjectClass object_class = 1;
}