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

// Lists, installs, enables, disables, licenses and removes the applications of the vault: vault
// applications (server side) and UI extension applications (client side), and downloads their
// packages and files.
//
// An application is a ZIP package with an application definition (`appdef.xml`). Its GUID
// identifies it in every call. [ExtApplication](mfiles:MFiles.ExtApplication) describes it;
// `type` tells a vault application (`EXT_APPLICATION_TYPE_SERVER`) from a UI extension application
// (`EXT_APPLICATION_TYPE_CLIENT`), and `platforms` (a bit mask of
// [ExtApplicationPlatform](mfiles:MFiles.ExtApplicationPlatform) values) the clients it supports.
//
// **Reading:**
//
// - [GetScriptApplicationsEx](mfiles:MFiles.IRPCClientScript.GetScriptApplicationsEx) lists the
//   applications; [GetScriptApplication](mfiles:MFiles.IRPCClientScript.GetScriptApplication)
//   gets one.
// - [GetClientScriptApplicationsDetails](mfiles:MFiles.IRPCClientScript.GetClientScriptApplicationsDetails)
//   lists the modules and dashboards of the UI extension applications of the new M-Files clients.
// - [DownloadScriptApplicationFile_Begin](mfiles:MFiles.IRPCClientScript.DownloadScriptApplicationFile_Begin)
//   and [DownloadScriptApplicationFile_ReadBlock](mfiles:MFiles.IRPCClientScript.DownloadScriptApplicationFile_ReadBlock)
//   download an application package;
//   [GetDownloadSessionIdOfScriptApplicationFile](mfiles:MFiles.IRPCClientScript.GetDownloadSessionIdOfScriptApplicationFile)
//   downloads one file of a UI extension application.
//
// **Managing** (requires the vault right `change_metadata_structure`, see
// [VaultAccess](mfiles:MFiles.VaultAccess); these are the operations of M-Files Admin):
//
// - Install or upgrade: upload the package with
//   [UploadScriptApplicationFileBlockEx](mfiles:MFiles.IRPCClientScript.UploadScriptApplicationFileBlockEx).
// - Enable or disable a vault application:
//   [GetScriptApplicationServerEnable](mfiles:MFiles.IRPCClientScript.GetScriptApplicationServerEnable),
//   [SetScriptApplicationServerEnable](mfiles:MFiles.IRPCClientScript.SetScriptApplicationServerEnable).
// - Restart a hot-swappable vault application:
//   [ReloadApplication](mfiles:MFiles.IRPCClientScript.ReloadApplication).
// - Licenses: [SetVaultApplicationLicense](mfiles:MFiles.IRPCClientScript.SetVaultApplicationLicense),
//   [GetVaultApplicationLicenseStatus](mfiles:MFiles.IRPCClientScript.GetVaultApplicationLicenseStatus).
// - Uninstall: [RemoveScriptApplication](mfiles:MFiles.IRPCClientScript.RemoveScriptApplication).
//
// **Enabled state.** `ExtApplication.is_enabled` is the default enabled state for clients, not
// whether a vault application runs. A disabled vault application can show `is_enabled` true; ask
// [GetScriptApplicationServerEnable](mfiles:MFiles.IRPCClientScript.GetScriptApplicationServerEnable).
service IRPCClientScript {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Client scripts and UI extension applications" };

	// Starts downloading the package (ZIP file) of an application and returns its first block.
	//
	// - Continue with
	//   [DownloadScriptApplicationFile_ReadBlock](mfiles:MFiles.IRPCClientScript.DownloadScriptApplicationFile_ReadBlock)
	//   from offset `len(data)` until `file_size` bytes have been read. If the first block already
	//   holds the whole file, the download is finished and `download_id` cannot be used.
	// - `block_size` is at most 4194304 (4 MiB); larger values fail with "Block size exceeded the
	//   limit of 4194304 bytes.". 0 returns no data.
	rpc DownloadScriptApplicationFile_Begin( DownloadScriptApplicationFile_BeginRequest ) returns ( DownloadScriptApplicationFile_BeginResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Reads the next block of an application download.
	//
	// - Read the blocks in order. The download is removed after the read that reaches the end of the
	//   file; later reads fail with "Not found. (The specified download session ... does not exist.)".
	// - Also reads downloads started with
	//   [GetDownloadSessionIdOfScriptApplicationFile](mfiles:MFiles.IRPCClientScript.GetDownloadSessionIdOfScriptApplicationFile).
	rpc DownloadScriptApplicationFile_ReadBlock( DownloadScriptApplicationFile_ReadBlockRequest ) returns ( DownloadScriptApplicationFile_ReadBlockResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Uploads and installs an application package. Same as UploadScriptApplicationFileBlockEx
	// without the list of outdated dependencies.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - See [UploadScriptApplicationFileBlockEx](mfiles:MFiles.IRPCClientScript.UploadScriptApplicationFileBlockEx),
	//   which new code should use.
	rpc UploadScriptApplicationFileBlock( UploadScriptApplicationFileBlockRequest ) returns ( UploadScriptApplicationFileBlockResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Uninstalls an application from the vault.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - Applications that have this application as their master application are uninstalled too.
	// - An unknown GUID fails with "Not found.".
	// - To stop a vault application without uninstalling it, use
	//   [SetScriptApplicationServerEnable](mfiles:MFiles.IRPCClientScript.SetScriptApplicationServerEnable).
	rpc RemoveScriptApplication( RemoveScriptApplicationRequest ) returns ( RemoveScriptApplicationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Not implemented: always returns an empty `license`.
	//
	// - Use [GetVaultApplicationLicenseStatus](mfiles:MFiles.IRPCClientScript.GetVaultApplicationLicenseStatus)
	//   to check a license.
	rpc GetVaultApplicationLicense( GetVaultApplicationLicenseRequest ) returns ( GetVaultApplicationLicenseResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Installs or removes the license of a vault application.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - An empty `license` removes the license. A license that the application reports as malformed
	//   is rejected.
	// - The new license is passed to the running application. Check the result with
	//   [GetVaultApplicationLicenseStatus](mfiles:MFiles.IRPCClientScript.GetVaultApplicationLicenseStatus).
	rpc SetVaultApplicationLicense( SetVaultApplicationLicenseRequest ) returns ( SetVaultApplicationLicenseResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the license status of a vault application, or checks a license before installing it.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - The status comes from the running application. If the application is not running (for
	//   example, it is disabled), the status is `APPLICATION_LICENSE_STATUS_INSTALLED` or
	//   `APPLICATION_LICENSE_STATUS_NOT_INSTALLED` depending on whether a license is stored.
	// - With `use_new_license` the application evaluates `new_license` without storing it.
	rpc GetVaultApplicationLicenseStatus( GetVaultApplicationLicenseStatusRequest ) returns ( GetVaultApplicationLicenseStatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether an application is enabled in the vault.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - This is the real enabled state; `ExtApplication.is_enabled` is not.
	rpc GetScriptApplicationServerEnable( GetScriptApplicationServerEnableRequest ) returns ( GetScriptApplicationServerEnableResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Enables or disables an application in the vault.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - An application whose master application is disabled cannot be enabled.
	// - Disabling also disables the applications that have this application as their master.
	rpc SetScriptApplicationServerEnable( SetScriptApplicationServerEnableRequest ) returns ( SetScriptApplicationServerEnableResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Not implemented: fails with "Not implemented.".
	//
	// - Download a package with
	//   [DownloadScriptApplicationFile_Begin](mfiles:MFiles.IRPCClientScript.DownloadScriptApplicationFile_Begin).
	rpc DownloadScriptApplication( DownloadScriptApplicationRequest ) returns ( DownloadScriptApplicationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one application by its GUID.
	//
	// - An unknown GUID fails with "Not found. (Vault application not found. (ID: ...))".
	rpc GetScriptApplication( GetScriptApplicationRequest ) returns ( GetScriptApplicationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists the applications installed in the vault, optionally only one type or platform.
	//
	// - With `filter` `EXT_APPLICATION_TYPE_CLIENT` any vault session can call it. Other filters need
	//   the vault right `read_all_metadata_structure`; otherwise "Access denied.".
	// - With `filter` `EXT_APPLICATION_TYPE_UNSPECIFIED` all applications are returned, disabled ones
	//   included. With a type filter only enabled applications are returned; UI extension
	//   applications whose vault application is disabled are left out as well.
	// - `platform` returns the applications whose `platforms` include it.
	//   `EXT_APPLICATION_PLATFORM_NONE` and `EXT_APPLICATION_PLATFORM_ADMIN` do not filter.
	rpc GetScriptApplicationsEx( GetScriptApplicationsExRequest ) returns ( GetScriptApplicationsExResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Starts downloading one file of a UI extension application of the new M-Files clients.
	//
	// - Used by the M-Files clients to load UI extension applications; applications rarely call it.
	// - Only for client applications that support `EXT_APPLICATION_PLATFORM_VNEXT`; others fail with
	//   "The script application is not a client app or the platform is not supported.".
	// - `file_name` is relative to the application folder. Absolute paths and `..` components are
	//   rejected; a file that does not exist fails with "Not found.".
	// - Read the file with
	//   [DownloadScriptApplicationFile_ReadBlock](mfiles:MFiles.IRPCClientScript.DownloadScriptApplicationFile_ReadBlock).
	rpc GetDownloadSessionIdOfScriptApplicationFile( GetDownloadSessionIdOfScriptApplicationFileRequest ) returns ( GetDownloadSessionIdOfScriptApplicationFileResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Uploads an application package block by block and, with the last block, installs the
	// application.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - First call: `upload_id` 0 and `offset` 0; it returns the new ID in `upload_idret`. Send the
	//   following blocks with that ID and their offsets, and set `ready` on the last block. The
	//   package may be at most 500 MB.
	// - With `ready` the server validates and installs the package. It is rejected if the same
	//   version is already installed ("Already exists."), if it is older than the installed version,
	//   if it is not a valid application package, or if it is an unsigned vault application and the
	//   server requires a valid signature from the caller.
	// - `outdated_vault_apps` lists the vault applications that this application depends on and whose
	//   installed version is lower than it requires.
	// - Uninstall with [RemoveScriptApplication](mfiles:MFiles.IRPCClientScript.RemoveScriptApplication).
	rpc UploadScriptApplicationFileBlockEx( UploadScriptApplicationFileBlockExRequest ) returns ( UploadScriptApplicationFileBlockExResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists the enabled UI extension applications of the new M-Files clients with their modules,
	// files and dashboards.
	//
	// - Used by the M-Files clients to load UI extension applications; applications rarely call it.
	// - `platform` must be `EXT_APPLICATION_PLATFORM_VNEXT` or `EXT_APPLICATION_PLATFORM_ADMIN`; other
	//   values fail with "The given platform is not supported.".
	// - Only client applications that support `EXT_APPLICATION_PLATFORM_VNEXT` are returned.
	// - Download a file of an application with
	//   [GetDownloadSessionIdOfScriptApplicationFile](mfiles:MFiles.IRPCClientScript.GetDownloadSessionIdOfScriptApplicationFile).
	rpc GetClientScriptApplicationsDetails( GetClientScriptApplicationsDetailsRequest ) returns ( GetClientScriptApplicationsDetailsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Restarts a hot-swappable vault application on all servers of the vault.
	//
	// - Requires the vault right `change_metadata_structure`.
	// - Applies to applications with `ExtApplication.hot_swappable` true. The request is sent to the
	//   servers of the vault as a broadcast message; the call returns before the application has
	//   restarted.
	rpc ReloadApplication( ReloadApplicationRequest ) returns ( ReloadApplicationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of DownloadScriptApplicationFile_Begin.
message DownloadScriptApplicationFile_BeginRequest {

	// The GUID of the application.
	string script_application = 1;

	// The number of bytes to return in `data`, at most 4 MiB.
	uint32 block_size = 2;
}

// The response of DownloadScriptApplicationFile_Begin.
message DownloadScriptApplicationFile_BeginResponse {

	// The ID of the download, for the next blocks.
	int32 download_id = 1;

	// The size of the package in bytes.
	int64 file_size = 2;

	// The first block of the package.
	bytes data = 3;
}

// The request of DownloadScriptApplicationFile_ReadBlock.
message DownloadScriptApplicationFile_ReadBlockRequest {

	// The ID of the download.
	int32 download_id = 1;

	// The number of bytes to read, at most 4 MiB.
	uint32 block_size = 2;

	// The byte offset to read from.
	int64 offset = 3;
}

// The response of DownloadScriptApplicationFile_ReadBlock.
message DownloadScriptApplicationFile_ReadBlockResponse {

	// The bytes read; shorter than `block_size` at the end of the file.
	bytes data = 1;
}

// The request of UploadScriptApplicationFileBlock.
message UploadScriptApplicationFileBlockRequest {

	// 0 in the first call; then the `upload_idret` it returned.
	int32 upload_id = 1;

	// The total size of the file in bytes.
	int64 total_size_in_bytes = 2;

	// Starting position. NOTE: Always use multiples of 4096 bytes.
	int64 offset = 3;

	// The file block to append.
	bytes data = 4;

	// True on the last block, to install the uploaded package.
	bool ready = 5;
}

// The response of UploadScriptApplicationFileBlock.
message UploadScriptApplicationFileBlockResponse {

	// The ID of the upload, for the next blocks.
	int32 upload_idret = 1;
}

// The request of RemoveScriptApplication.
message RemoveScriptApplicationRequest {

	// The GUID of the application to uninstall.
	string script_application = 1;
}

// The response of RemoveScriptApplication.
message RemoveScriptApplicationResponse {
}

// The request of GetVaultApplicationLicense.
message GetVaultApplicationLicenseRequest {

	// The GUID of the application.
	string script_application = 1;
}

// The response of GetVaultApplicationLicense.
message GetVaultApplicationLicenseResponse {

	// Always empty.
	string license = 1;
}

// The request of SetVaultApplicationLicense.
message SetVaultApplicationLicenseRequest {

	// The GUID of the application.
	string script_application = 1;

	// The content of the license file; empty to remove the license.
	string license = 2;
}

// The response of SetVaultApplicationLicense.
message SetVaultApplicationLicenseResponse {
}

// The request of GetVaultApplicationLicenseStatus.
message GetVaultApplicationLicenseStatusRequest {

	// The GUID of the application.
	string application_guid = 1;

	// True to evaluate `new_license` instead of the installed license.
	bool use_new_license = 2;

	// The license to evaluate when `use_new_license` is true.
	string new_license = 3;

	// True to get a description of the status in `details`.
	bool return_details = 4;
}

// The response of GetVaultApplicationLicenseStatus.
message GetVaultApplicationLicenseStatusResponse {

	// The license status of the application.
	ApplicationLicenseStatus status = 1;

	// With `return_details`, a description of the status.
	string details = 2;
}

// The request of GetScriptApplicationServerEnable.
message GetScriptApplicationServerEnableRequest {

	// The GUID of the application.
	string script_application = 1;
}

// The response of GetScriptApplicationServerEnable.
message GetScriptApplicationServerEnableResponse {

	// True if the application is enabled.
	bool enabled = 1;
}

// The request of SetScriptApplicationServerEnable.
message SetScriptApplicationServerEnableRequest {

	// The GUID of the application.
	string script_application = 1;

	// True to enable, false to disable.
	bool enabled = 2;
}

// The response of SetScriptApplicationServerEnable.
message SetScriptApplicationServerEnableResponse {
}

// The request of DownloadScriptApplication.
message DownloadScriptApplicationRequest {

	// The client application ID to download.
	string script_application = 1;

	// Optional resource path inside the script application archive.
	string resource_path = 2;
}

// The response of DownloadScriptApplication.
message DownloadScriptApplicationResponse {
}

// The request of GetScriptApplication.
message GetScriptApplicationRequest {

	// The GUID of the application.
	string script_application = 1;
}

// The response of GetScriptApplication.
message GetScriptApplicationResponse {

	// The application. See [ExtApplication](mfiles:MFiles.ExtApplication).
	ExtApplication application = 1;
}

// The request of GetScriptApplicationsEx.
message GetScriptApplicationsExRequest {

	// The application type, or `EXT_APPLICATION_TYPE_UNSPECIFIED` for all types (disabled applications included).
	ExtApplicationType filter = 1;

	// The client platform, or `EXT_APPLICATION_PLATFORM_NONE` for all.
	ExtApplicationPlatform platform = 2;
}

// The response of GetScriptApplicationsEx.
message GetScriptApplicationsExResponse {

	// The applications. See [ExtApplication](mfiles:MFiles.ExtApplication).
	repeated ExtApplication applications = 1;
}

// The request of GetDownloadSessionIdOfScriptApplicationFile.
message GetDownloadSessionIdOfScriptApplicationFileRequest {

	// The GUID of the application.
	string script_application = 1;

	// The path of the file inside the application, for example `script\helper.js`.
	string file_name = 2;
}

// The response of GetDownloadSessionIdOfScriptApplicationFile.
message GetDownloadSessionIdOfScriptApplicationFileResponse {

	// The ID of the download.
	int32 download_id = 1;

	// The size of the file in bytes.
	int64 file_size = 2;
}

// The request of UploadScriptApplicationFileBlockEx.
message UploadScriptApplicationFileBlockExRequest {

	// 0 in the first call; then the `upload_idret` it returned.
	int32 upload_id = 1;

	// The size of the whole package.
	int64 total_size_in_bytes = 2;

	// The position of this block. Use multiples of 4096 bytes for all blocks but the last.
	int64 offset = 3;

	// The bytes of this block.
	bytes data = 4;

	// True on the last block, to install the uploaded package.
	bool ready = 5;
}

// The response of UploadScriptApplicationFileBlockEx.
message UploadScriptApplicationFileBlockExResponse {

	// The ID of the upload, for the next blocks.
	int32 upload_idret = 1;

	// After the last block, the dependencies whose installed version is too old. Empty otherwise.
	repeated VaultApplicationDependency outdated_vault_apps = 2;
}

// A structure that specifies applications detail request.
message GetClientScriptApplicationsDetailsRequest {

	// `EXT_APPLICATION_PLATFORM_VNEXT` or `EXT_APPLICATION_PLATFORM_ADMIN`.
	ExtApplicationPlatform platform = 1;
}

// A structure that specifies applications detail response.
message GetClientScriptApplicationsDetailsResponse {

	// The applications with their modules and dashboards. See [ExtApplicationDef](mfiles:MFiles.ExtApplicationDef).
	repeated ExtApplicationDef applications = 1;
}

// The request of ReloadApplication.
message ReloadApplicationRequest {

	// The GUID of the vault application.
	string application = 1;
}

// The response of ReloadApplication.
message ReloadApplicationResponse {
}