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

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 sets the server's license, its usage, and whether licensed features such as OCR or
// M-Files Web are available.
//
// Use this interface to set or get license code and serial number.
//
// M-Files Admin uses this service on its license page. Applications mostly need only
// [DoesLicenseHaveFeature](mfiles:MFiles.IRPCLicenseManagement.DoesLicenseHaveFeature), which any
// session can call to find out whether an add-on feature is licensed before offering it.
//
// **Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
// `{00000000-0000-0000-0000-000000000000}`). Reading or changing the license code and reading the
// usage require the system administrator server role (server right `manage_licenses` in
// [ServerAccess](mfiles:MFiles.ServerAccess)); other callers get "Access denied. You do not
// have the server-level access rights required by this operation.". On servers that license each
// vault separately through M-Files Manage, a vault administrator can also read that vault's
// license and usage from a vault session.
//
// - **Feature checks**:
//   [DoesLicenseHaveFeature](mfiles:MFiles.IRPCLicenseManagement.DoesLicenseHaveFeature)
//   (session),
//   [DoesLicenseHaveFeatureByVaultDNS](mfiles:MFiles.IRPCLicenseManagement.DoesLicenseHaveFeatureByVaultDNS)
//   (no session).
// - **License code**:
//   [GetLicenseCodeAndSerialNumber](mfiles:MFiles.IRPCLicenseManagement.GetLicenseCodeAndSerialNumber),
//   [SetLicenseCodeAndSerialNumber](mfiles:MFiles.IRPCLicenseManagement.SetLicenseCodeAndSerialNumber),
//   [RefreshLicenseCode](mfiles:MFiles.IRPCLicenseManagement.RefreshLicenseCode).
// - **Usage**: [GetLicenseUsage](mfiles:MFiles.IRPCLicenseManagement.GetLicenseUsage).
service IRPCLicenseManagement {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "License management" };

	// Installs a new license for the server.
	//
	// - Requires the system administrator server role (server right `manage_licenses`).
	// - The serial number and license code must match each other. All vaults are notified of the new
	//   license.
	rpc SetLicenseCodeAndSerialNumber( SetLicenseCodeAndSerialNumberRequest ) returns ( SetLicenseCodeAndSerialNumberResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets how many named, concurrent and read-only user licenses are in use.
	//
	// - Requires the system administrator server role (server right `manage_licenses`). Denied for a
	//   vault administrator in a vault session on a server with a server license.
	// - On servers that license each vault through M-Files Manage, a vault session of a vault
	//   administrator gets the usage of that vault instead.
	rpc GetLicenseUsage( GetLicenseUsageRequest ) returns ( GetLicenseUsageResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells which of the requested add-on features (OCR, M-Files Web, AI search and so on) the license
	// allows.
	//
	// - Any session can call it, vault or server-level; no rights are needed. Calls without a
	//   session fail with `UNAUTHENTICATED`.
	// - In a vault session, the vault's own license is taken into account.
	// - Set every feature you are interested in, or `all`; the response repeats the requested features
	//   that are licensed.
	rpc DoesLicenseHaveFeature( DoesLicenseHaveFeatureRequest ) returns ( DoesLicenseHaveFeatureResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Asks the server to fetch its license again from M-Files Manage.
	//
	// - Has an effect only on servers that get their license from M-Files Manage; elsewhere it does
	//   nothing.
	// - Requires the system administrator server role (server right `manage_licenses`). On servers
	//   that get their license from M-Files Manage, a vault administrator can also call it from a
	//   vault session; then only that vault's license is refreshed.
	// - In a server-level session, all licenses of the server are refreshed.
	rpc RefreshLicenseCode( RefreshLicenseCodeRequest ) returns ( RefreshLicenseCodeResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether a feature is licensed for the vault that a host name points to, without a session.
	//
	// - Needs no session; works anonymously, also on M-Files Cloud.
	// - Returns true if the server license has the feature, whatever host name is given. Otherwise,
	//   on servers that license vaults separately, the host name is looked up in the server's vault
	//   host name configuration and the vault license is checked.
	// - An unknown host name or an unsupported feature gives false, not an error.
	rpc DoesLicenseHaveFeatureByVaultDNS( DoesLicenseHaveFeatureByVaultDNSRequest ) returns ( DoesLicenseHaveFeatureByVaultDNSResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Gets the server's serial number, license code and evaluation state.
	//
	// - Requires the system administrator server role (server right `manage_licenses`). Denied for a
	//   vault administrator on a server with a server license.
	// - On servers that license each vault through M-Files Manage, a vault session of a vault
	//   administrator gets that vault's license instead; the evaluation fields are then not set.
	rpc GetLicenseCodeAndSerialNumber( GetLicenseCodeAndSerialNumberRequest ) returns ( GetLicenseCodeAndSerialNumberResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of SetLicenseCodeAndSerialNumber.
message SetLicenseCodeAndSerialNumberRequest {

	// The serial number of the new license.
	string serial_number = 1;

	// The license code that goes with `serial_number`.
	string license_code = 2;
}

// The response of SetLicenseCodeAndSerialNumber.
message SetLicenseCodeAndSerialNumberResponse {
}

// The request of GetLicenseUsage.
message GetLicenseUsageRequest {
}

// The response of GetLicenseUsage.
message GetLicenseUsageResponse {

	// Receives the number of named user licenses in use.
	uint32 num_of_named_user_licenses_in_use = 1;

	// Receives the number of concurrent user licenses in use.
	uint32 num_of_concurrent_user_licenses_in_use = 2;

	// Receives the number of read-only user licenses in use.
	uint32 num_of_named_read_only_user_licenses_in_use = 3;
}

// The request of DoesLicenseHaveFeature.
message DoesLicenseHaveFeatureRequest {

	// The features to check. See [LICENSEDPRODUCTFEATURES](mfiles:MFiles.LICENSEDPRODUCTFEATURES).
	LICENSEDPRODUCTFEATURES requested_features = 1;
}

// The response of DoesLicenseHaveFeature.
message DoesLicenseHaveFeatureResponse {

	// The requested features that the license allows; the others are false.
	LICENSEDPRODUCTFEATURES supported_features = 1;
}

// The request of RefreshLicenseCode.
message RefreshLicenseCodeRequest {
}

// The response of RefreshLicenseCode.
message RefreshLicenseCodeResponse {
}

// The request of DoesLicenseHaveFeatureByVaultDNS.
message DoesLicenseHaveFeatureByVaultDNSRequest {

	// The host name of the vault, without `https://`.
	string vault_dns_name = 1;

	// The feature to check.
	LicensedProductFeature requested_feature = 2;
}

// The response of DoesLicenseHaveFeatureByVaultDNS.
message DoesLicenseHaveFeatureByVaultDNSResponse {

	// True if the feature is licensed.
	bool is_feature_enabled = 1;
}

// Get server license information request.
message GetLicenseCodeAndSerialNumberRequest {
}

// Get server license information response.
message GetLicenseCodeAndSerialNumberResponse {

	// Tells if the server is running in evaluation mode.
	bool evaluation_mode = 1;

	// True if the evaluation period has ended. Valid only when `evaluation_mode` is true.
	bool evaluation_expired = 2;

	// Days left in the evaluation period. Valid only when `evaluation_mode` is true and `evaluation_expired` is false.
	uint32 evaluation_days_left = 3;

	// The serial number. Empty in evaluation mode.
	string serial_number = 4;

	// The license code. Empty in evaluation mode.
	string license_code = 5;

	// When the license was last fetched from M-Files Manage, if the server gets its license from there.
	string last_license_retrieval = 6;
}