// 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 and replaces the event handlers of a vault or of the server: VBScript code that the server
// runs when an event occurs.
//
// MFAdmin uses this interface to admininistrate event handlers.
//
// M-Files Admin uses this service for its event handler editor, and vault applications use it to
// register their own handlers. An event handler is an
// [InternalEventHandler](mfiles:MFiles.InternalEventHandler): the event it reacts to
// (`event_type`), its position among the handlers of the same event (`sort_index`), `is_active`, a
// `description`, and the `code` that the server runs.
//
// - **Vault event handlers** run in one vault:
//   [GetVaultEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.GetVaultEventHandlers),
//   [SetVaultEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.SetVaultEventHandlers). They need
//   a vault session.
// - **Server event handlers** are stored once for the whole server:
//   [GetServerEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.GetServerEventHandlers),
//   [SetServerEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.SetServerEventHandlers). A
//   server-level session is enough.
//
// The `Set` methods replace the whole list: read it, change it, and write all handlers back. To
// keep a handler, send it back with its `guid`; a handler left out is removed.
//
// **Rights.** Handler code runs on the server, so writing it needs the right to run code there:
//
// - Server right `run_code` (message `ServerAccess`). Logins with the system administrator server
//   role have it. Users with full control of the vault have it only when the server is configured
//   to let vault administrators run code. Without it, writing fails with "Editing vault
//   application bindings or VBScript code requires system administrator rights.".
// - When the server is configured to accept signed scripts, a vault administrator can write vault
//   event handlers without `run_code`: each new or changed `code` must then carry a valid digital
//   signature, and the caller needs the vault right `run_signed_code` (part of full control).
// - Reading vault handlers, including their code, needs only the vault right
//   `change_metadata_structure`. Reading server handlers needs `run_code`.
service IRPCEventHandlersAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Event handlers" };

	// Gets all event handlers of the vault, with their code.
	//
	// - Requires a vault session and the vault right `change_metadata_structure`; a normal user gets
	//   "Access denied.".
	// - Returns active and inactive handlers, including those registered by vault applications.
	// - Returns an empty list when the server license does not include event handlers.
	rpc GetVaultEventHandlers( GetVaultEventHandlersRequest ) returns ( GetVaultEventHandlersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces all event handlers of the vault with the given list.
	//
	// - **Replaces the whole list**: handlers that are not in `event_handlers` are removed. Get the
	//   current list with [GetVaultEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.GetVaultEventHandlers)
	//   first and send unchanged handlers back with their `guid`.
	// - Requires a vault session, the vault right `change_metadata_structure`, and the right to run
	//   code: `run_code`, or signed scripts and `run_signed_code` (see the service overview).
	// - Validation: every `event_type` must be a vault event, `description` must not be empty, the
	//   `code` of active handlers must compile ("The VBScript code for the event handler ... is
	//   invalid."), and the `sort_index` values of each event type must be 0, 1, 2, ... without gaps.
	// - The session language must be the vault's default language; a session in another vault
	//   language fails with "Not implemented.". Fails also when the server license does not include
	//   event handlers.
	// - Takes effect for the vault after the call commits; when full event logging is on, the server
	//   logs each added, changed and removed handler.
	rpc SetVaultEventHandlers( SetVaultEventHandlersRequest ) returns ( SetVaultEventHandlersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all server-level event handlers, with their code.
	//
	// - Requires the server right `run_code`. A server-level session is enough. A vault administrator
	//   without `run_code` gets "Access denied. You do not have the server-level access rights
	//   required by this operation." (0x800400A8).
	rpc GetServerEventHandlers( GetServerEventHandlersRequest ) returns ( GetServerEventHandlersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Replaces all server-level event handlers with the given list.
	//
	// - **Replaces the whole list**: handlers that are not in `event_handlers` are removed.
	// - Requires the server right `run_code`; signed scripts do not replace it here. A server-level
	//   session is enough.
	// - Validation as in [SetVaultEventHandlers](mfiles:MFiles.IRPCEventHandlersAdmin.SetVaultEventHandlers),
	//   except that every `event_type` must be a server event. Fails when the server license does not
	//   include event handlers.
	rpc SetServerEventHandlers( SetServerEventHandlersRequest ) returns ( SetServerEventHandlersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of GetVaultEventHandlers.
message GetVaultEventHandlersRequest {
}

// The response of GetVaultEventHandlers.
message GetVaultEventHandlersResponse {

	// The event handlers of the vault. See [InternalEventHandler](mfiles:MFiles.InternalEventHandler).
	repeated InternalEventHandler values = 1;
}

// The request of SetVaultEventHandlers.
message SetVaultEventHandlersRequest {

	// The complete new list of the vault's event handlers. Include existing handlers with their `guid`; leave `guid` empty for a new handler.
	repeated InternalEventHandler event_handlers = 1;
}

// The response of SetVaultEventHandlers.
message SetVaultEventHandlersResponse {
}

// The request of GetServerEventHandlers.
message GetServerEventHandlersRequest {
}

// The response of GetServerEventHandlers.
message GetServerEventHandlersResponse {

	// The server-level event handlers. See [InternalEventHandler](mfiles:MFiles.InternalEventHandler).
	repeated InternalEventHandler values = 1;
}

// The request of SetServerEventHandlers.
message SetServerEventHandlersRequest {

	// The complete new list of the server's event handlers.
	repeated InternalEventHandler event_handlers = 1;
}

// The response of SetServerEventHandlers.
message SetServerEventHandlersResponse {
}