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

// Calls vault extension methods: server-side code in the vault that takes a string and returns a
// string.
//
// A vault extension method is custom server code that a client calls by name. There are two kinds:
//
// - **Event handler methods**: event handlers of the type VaultExtensionMethod, written in
//   VBScript in M-Files Admin or registered by a vault application. They are identified by name
//   only. Call them with [RunExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.RunExtensionMethod)
//   with an all-zero `application_id`, or with
//   [ExecuteExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.ExecuteExtensionMethod).
// - **Application extension methods**: methods of an extension object of a vault application,
//   identified by the application GUID, the extension, the instance and the method name. Call
//   them with [RunExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.RunExtensionMethod) or
//   [ExecuteExtensionMethodEx](mfiles:MFiles.IRPCVaultExtensionMethods.ExecuteExtensionMethodEx).
//
// Prefer [RunExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.RunExtensionMethod): it
// covers both kinds and can compress large inputs and outputs. The input and output are free-form
// strings; their format is defined by the method. Each call runs in its own
// transaction.
//
// [ExecuteAnonymousExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.ExecuteAnonymousExtensionMethod)
// is for the web server that passes anonymous HTTP requests (webhooks) to a vault application.
//
// Errors: an unknown event handler method fails with "Not found. (<name>)"; an unknown application
// extension fails with `The specified application "<extension>" does not exist.`.
service IRPCVaultExtensionMethods {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Vault extension methods" };

	// Runs an event handler method by name. In new code use RunExtensionMethod.
	//
	// - Same as [RunExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.RunExtensionMethod) with
	//   an all-zero `application_id` and uncompressed input.
	// - An unknown name fails with "Not found. (<name>)".
	rpc ExecuteExtensionMethod( ExecuteExtensionMethodRequest ) returns ( ExecuteExtensionMethodResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Tells whether an event handler method with the given name exists and is active.
	//
	// - Checks only the VaultExtensionMethod event handlers of the vault. Application extension
	//   methods and the server's built-in methods are not reported.
	// - A name that does not exist returns `exists` false; the call does not fail.
	rpc IsExtensionMethodAvailable( IsExtensionMethodAvailableRequest ) returns ( IsExtensionMethodAvailableResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Runs an extension method of a vault application. In new code use RunExtensionMethod.
	//
	// - Same as [RunExtensionMethod](mfiles:MFiles.IRPCVaultExtensionMethods.RunExtensionMethod) with
	//   an application GUID and uncompressed input.
	// - `application`, `extension` and `method` are required; an empty or all-zero `application`
	//   fails with "The parameter is incorrect.".
	rpc ExecuteExtensionMethodEx( ExecuteExtensionMethodExRequest ) returns ( ExecuteExtensionMethodExResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Passes an anonymous HTTP request, such as a webhook call, to a vault application. Used by the
	// M-Files web server.
	//
	// - No session is needed. The server finds the vault by `vault_dns`, which must match a host name
	//   that the server administrator has mapped to a vault; otherwise the call fails with "The
	//   parameter is incorrect.".
	// - The method runs without a user. The receiving application must authenticate and validate the
	//   request itself.
	// - `http_path` must not be empty and is limited to 10240 characters. `http_method` must be one of
	//   CONNECT, DELETE, GET, HEAD, OPTIONS, POST or PUT. Other values fail with "The parameter is
	//   incorrect.".
	rpc ExecuteAnonymousExtensionMethod( ExecuteAnonymousExtensionMethodRequest ) returns ( ExecuteAnonymousExtensionMethodResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE returns_metadata_structure_version: true };
	}

	// Runs a vault extension method, either an event handler method or an application extension
	// method, with optional compression of the input and output.
	//
	// - Requires a vault session; no special vault rights. The method's own code decides what the
	//   caller may do.
	// - With an all-zero (or empty) `application_id`, `method_name` names an event handler method and
	//   `extension` and `instance` are ignored. Otherwise the call goes to the extension object of the
	//   application.
	// - **Compression.** Set either `input` or `compressed_input`. When `compressed_input` is set, the
	//   server returns the output in `compressed_output` and leaves `output` empty. The compressed
	//   format is not plain zlib: it is a 4-byte little-endian length of the uncompressed data,
	//   followed by the zlib stream (RFC 1950) of the UTF-8 text **with a terminating zero byte**; the
	//   length includes that byte. Data in another format fails with "The parameter is incorrect.".
	//   The uncompressed size is limited to 100 MiB.
	rpc RunExtensionMethod( RunExtensionMethodRequest ) returns ( RunExtensionMethodResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of ExecuteExtensionMethod.
message ExecuteExtensionMethodRequest {

	// The name of the VaultExtensionMethod event handler.
	string script_identifier = 1;

	// The input passed to the method.
	string input = 2;
}

// The response of ExecuteExtensionMethod.
message ExecuteExtensionMethodResponse {

	// The output of the method.
	string output = 1;
}

// The request of IsExtensionMethodAvailable.
message IsExtensionMethodAvailableRequest {

	// The name of the VaultExtensionMethod event handler.
	string method_identifier = 1;
}

// The response of IsExtensionMethodAvailable.
message IsExtensionMethodAvailableResponse {

	// True if an event handler with the name exists.
	bool exists = 1;

	// True if that event handler is active.
	bool is_active = 2;
}

// The request of ExecuteExtensionMethodEx.
message ExecuteExtensionMethodExRequest {

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

	// The identifier of the application's extension object.
	string extension = 2;

	// The identifier of the extension object instance.
	string instance = 3;

	// The name of the method.
	string method = 4;

	// The input passed to the method.
	string input = 5;
}

// The response of ExecuteExtensionMethodEx.
message ExecuteExtensionMethodExResponse {

	// The output of the method.
	string output = 1;
}

// The request of ExecuteAnonymousExtensionMethod.
message ExecuteAnonymousExtensionMethodRequest {

	// The host name of the vault, as mapped on the server.
	string vault_dns = 1;

	// The name of the anonymous extension method.
	string method_identifier = 2;

	// The path and query string of the HTTP request.
	string http_path = 3;

	// The HTTP method of the request, for example `POST`.
	string http_method = 4;

	// The headers of the HTTP request.
	repeated NamedValue http_headers = 5;

	// The body of the HTTP request.
	bytes request_body = 6;
}

// The response of ExecuteAnonymousExtensionMethod.
message ExecuteAnonymousExtensionMethodResponse {

	// The headers to return in the HTTP response.
	repeated NamedValue response_http_headers = 1;

	// The body of the HTTP response.
	bytes response_body = 2;
}

// Request data for running an extension method.
message RunExtensionMethodRequest {

	// The GUID of the vault application. All zeros or empty for an event handler method.
	string application_id = 1;

	// The identifier of the application's extension object; empty for an event handler method.
	string extension = 2;

	// The identifier of the extension object instance; empty for an event handler method.
	string instance = 3;

	// The name of the method. For an event handler method, the name of the VaultExtensionMethod event handler.
	string method_name = 4;

	// The input as text. Leave empty when `compressed_input` is used.
	string input = 5;

	// The compressed input: the 4-byte little-endian length of the UTF-8 text including a terminating zero byte, followed by the zlib stream of that text. Leave empty to use `input`.
	bytes compressed_input = 6;
}

// The request data for RunExtensionMethod method.
message RunExtensionMethodResponse {

	// The output as text, when the input was not compressed.
	string output = 1;

	// When `compressed_input` was used, the output in the same compressed format: a 4-byte little-endian length, then the zlib stream of the UTF-8 text with a terminating zero byte.
	bytes compressed_output = 2;
}