// 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 reading object types.
//
// This interface provides read-only access to object types.
//
// Reads the object types of the vault: the kinds of objects users create, such as Document (0),
// Customer or Project. Use it to resolve object type IDs to names, find the property definition
// that refers to objects of a type, and check whether the user can create objects of a type.
//
// | Job | Call |
// | --- | --- |
// | List all object types (with icons) | [GetObjectTypes](mfiles:MFiles.IRPCObjectTypes.GetObjectTypes) |
// | Read one object type or value list by ID | [GetObjectType](mfiles:MFiles.IRPCObjectTypes.GetObjectType) |
// | Object types *and* plain value lists, without icons | [GetValueLists](mfiles:MFiles.IRPCValueLists.GetValueLists) |
// | Ask the server to re-read an external object type now | [RefreshExternalObjectType](mfiles:MFiles.IRPCObjectTypes.RefreshExternalObjectType) |
//
// **ID spaces.** An object type is a value list whose items are objects, so object types and value
// lists share one ID space and both are described by [ValueList](mfiles:MFiles.ValueList)
// (`is_real_object_type` tells them apart). Property definition IDs
// ([IRPCPropertyDefs](mfiles:MFiles.IRPCPropertyDefs)) are a separate space, and so are the item
// IDs inside each list: a class ID, for example, is an item ID in value list 1 (Classes). Built-in
// object types keep their IDs in every vault (0 Document, 9 Document collection, 10 Assignment);
// the IDs of custom object types differ between vaults, so resolve them by alias or GUID with
// [GetMetadataStructureItemIdByAlias](mfiles:MFiles.IRPCVault.GetMetadataStructureItemIdByAlias)
// instead of hard-coding them.
//
// The read calls are cacheable: keep the result until the metadata structure version that the server returns
// in the `mfiles-metadata-version-bin` trailer changes. See
// [Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/)
// and
// [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/).
service IRPCObjectTypes {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_CORE title: "Object types" };

	// Refreshes the items of an external object type or value list from its external database now.
	//
	// - Requires a vault session and a license that allows modifications.
	// - For an object type that is not connected to an external database, the call succeeds and does
	//   nothing.
	// - Fails if the external connection of the object type is disabled, or if the connection or its
	//   SELECT statement does not work.
	// - Rarely needed by applications: the lookup calls of
	//   [IRPCValueLists](mfiles:MFiles.IRPCValueLists) take an `ExtDBRefreshType` that can refresh
	//   an external list as part of the read.
	rpc RefreshExternalObjectType( RefreshExternalObjectTypeRequest ) returns ( RefreshExternalObjectTypeResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets all object types (real object types only, not plain value lists), with their icons.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Returns only real object types (`is_real_object_type` is true). For plain value lists such as
	//   Country, call [GetValueLists](mfiles:MFiles.IRPCValueLists.GetValueLists), which returns both
	//   kinds but no icons.
	// - Object types that the user is not allowed to see are **not** left out: they are returned with
	//   empty `name_singular` and `name_plural`, and `object_type_permissions.can_user_see` false.
	//   Filter on `object_type_permissions` before showing a list to the user.
	// - `object_type_permissions.can_user_add_new_items` tells whether the user may create objects
	//   of the type; `options.can_add_items` tells whether the type allows new objects at all.
	// - Names are in the session language when the vault has translations for it.
	// - `icon` holds the type's .ICO image (about 17 KB for the default icon), so the response grows
	//   with the number of types.
	// - Cacheable by metadata structure version.
	rpc GetObjectTypes( GetObjectTypesRequest ) returns ( GetObjectTypesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}

	// Gets one object type or value list by ID, with its icon.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Accepts any ID from the shared object type / value list ID space: a real object type (for
	//   example 136) or a plain value list (for example 154) both work. Only real object types carry
	//   an icon.
	// - An ID that does not exist fails with the error message "Not found." (gRPC status `UNKNOWN`).
	// - An object type that the user cannot see is returned with empty names and
	//   `object_type_permissions.can_user_see` false; it does not fail.
	// - Cacheable by metadata structure version.
	// - Related: [GetValueList](mfiles:MFiles.IRPCValueLists.GetValueList) returns the same data
	//   without the icon.
	rpc GetObjectType( GetObjectTypeRequest ) returns ( GetObjectTypeResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true highlighted: true };
	}
}

// The request of RefreshExternalObjectType.
message RefreshExternalObjectTypeRequest {

	// The ID of the object type or value list to refresh.
	int32 object_type = 1;

	// `EXT_DBREFRESH_TYPE_QUICK` or `EXT_DBREFRESH_TYPE_FULL`.
	ExtDBRefreshType ext_dbrefresh_type = 2;
}

// The response of RefreshExternalObjectType.
message RefreshExternalObjectTypeResponse {
}

// The request of GetObjectTypes.
message GetObjectTypesRequest {

	// The importance level of this call. Typically CALL_IMPORTANCE_NORMAL.
	CallImportance call_importance = 1;
}

// The response of GetObjectTypes.
message GetObjectTypesResponse {

	// The real object types of the vault, including those the user cannot see (with empty names). See [ValueList](mfiles:MFiles.ValueList).
	repeated ValueList object_types = 1;
}

// The request of GetObjectType.
message GetObjectTypeRequest {

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

	// The ID of the object type or value list to get.
	int32 object_type = 2;
}

// The response of GetObjectType.
message GetObjectTypeResponse {

	// The object type or value list. See [ValueList](mfiles:MFiles.ValueList).
	ValueList putf8szobjtypebasic = 1;
}