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

// Reads the Microsoft Purview sensitivity labels of files.
//
// Reads the Microsoft Purview sensitivity labels of a file, for showing them next to the file in a
// user interface. The labels come from the Microsoft SharePoint Embedded storage where the vault
// keeps the file; vaults that do not store files there have no labels.
//
// The call is advisory: it never fails because labels are unavailable. Whenever the server cannot
// produce labels, it returns an empty `label_info`. Do not use it as a security check.
service IRPCSensitivityLabels {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Sensitivity labels" };

	// Gets the sensitivity labels of one file, or an empty list when no labels are available.
	//
	// - Requires a vault session. No special vault rights are needed, and the server does not look up
	//   the object that the file belongs to.
	// - The server reads only `file.master_storage_file_ref` and `file.extension`. Pass a
	//   [File](mfiles:MFiles.File) as returned with an object version.
	// - `label_info.labels` is empty when any of these holds: the feature is not enabled on the
	//   server, the vault does not store files in SharePoint Embedded, `master_storage_file_ref` is
	//   empty, the extension is not one that carries labels, or the storage service fails or answers
	//   with something the server cannot parse.
	// - Labels are looked up only for Word, Excel and PowerPoint formats (for example `docx`, `xlsx`,
	//   `pptx` and their older and macro-enabled variants) and `pdf`. The extension is compared
	//   case-insensitively.
	rpc GetSensitivityLabels( GetSensitivityLabelsRequest ) returns ( GetSensitivityLabelsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of GetSensitivityLabels.
message GetSensitivityLabelsRequest {

	// The file to query. Only `master_storage_file_ref` and `extension` are read.
	File file = 1;
}

// The response of GetSensitivityLabels.
message GetSensitivityLabelsResponse {

	// The labels of the file. An empty `labels` list means that no label information is available, not that the file is known to be unlabeled.
	FileSensitivityLabelInfo label_info = 1;
}