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

// Reads and sets the user's notification switch, checks whether a user can receive
// notifications, and sends requests and custom notifications to users.
//
// Everything here ends in an e-mail notification, so it works only when notifications are enabled
// on the server and in the vault. Several methods are used mainly by M-Files clients.
//
// - **The caller's own on/off switch** for notifications:
//   [GetNotificationConfiguration](mfiles:MFiles.IRPCEvents.GetNotificationConfiguration),
//   [SetNotificationConfiguration](mfiles:MFiles.IRPCEvents.SetNotificationConfiguration).
// - **Check that a user can receive notifications**:
//   [TestMessageToUser](mfiles:MFiles.IRPCEvents.TestMessageToUser).
// - **Send an e-mail** with your own subject and body:
//   [SendCustomNotification](mfiles:MFiles.IRPCEvents.SendCustomNotification).
// - **Send a request** to users:
//   [CreateEventFreeRequest](mfiles:MFiles.IRPCEvents.CreateEventFreeRequest),
//   [CreateEventCheckInRequest](mfiles:MFiles.IRPCEvents.CreateEventCheckInRequest).
//
// Which events notify whom is defined by notification rules: see
// [IRPCNotificationRules](mfiles:MFiles.IRPCNotificationRules). All methods need a vault session.
// Users and groups are identified by their IDs in the vault.
service IRPCEvents {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Events and notifications" };

	// Turns notifications on or off for the caller.
	//
	// - Requires a vault session. No special vault rights are needed. Affects only the caller.
	// - Only `is_enabled` may be set; any other flag fails with "The parameter is incorrect.".
	rpc SetNotificationConfiguration( SetNotificationConfigurationRequest ) returns ( SetNotificationConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Tells whether the caller has notifications turned on.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Only `is_enabled` is used; the other flags are always false here.
	rpc GetNotificationConfiguration( GetNotificationConfigurationRequest ) returns ( GetNotificationConfigurationResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Sends a request with a free-text message to users and groups. Used by M-Files clients;
	// applications rarely call it.
	//
	// - Requires a vault session; anonymous sessions get "Access denied.".
	// - The request is recorded as an `EVENT_TYPE_FREE_REQUEST` event addressed to the recipients
	//   (groups are expanded to their members), only if the vault's event log configuration records
	//   that event type. The recipients are notified by e-mail when notifications are enabled.
	rpc CreateEventFreeRequest( CreateEventFreeRequestRequest ) returns ( CreateEventFreeRequestResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Checks whether a user can receive notifications, and fails with the reason when not.
	//
	// - Requires a vault session; anonymous sessions get "Access denied.".
	// - Checks, in this order: notifications are enabled on the server, notifications are enabled in
	//   the vault, event logging is enabled in the vault, the user has not turned notifications off
	//   (only with `test_notifications_disabled_by_user`), and the user has a valid e-mail address.
	//   The first failed check is the error, for example "Please ask your M-Files admin to enable
	//   notifications on the M-Files server.".
	// - Nothing is sent. `send_message` true fails with "Not implemented.".
	rpc TestMessageToUser( TestMessageToUserRequest ) returns ( TestMessageToUserResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Sends an e-mail with the given subject and body to users, groups and e-mail addresses.
	//
	// - Requires a vault session of a user. Adding `external_recipients`, or setting
	//   `send_with_server_email_identity`, also requires the server right `send_server_messages`
	//   ([ServerAccess](mfiles:MFiles.ServerAccess)); without it the call fails with "Access
	//   denied.".
	// - Groups are expanded to their members. Each user and each external address gets its own
	//   e-mail. Messages are queued when the call commits.
	// - The call succeeds and sends nothing when notifications are disabled on the server or in the
	//   vault, or when the vault does not allow custom notifications.
	// - Sent as the caller's e-mail address, which must then be valid; or, with
	//   `send_with_server_email_identity`, from the server's notification address with the caller's
	//   address as reply-to.
	// - An external address that is not a valid e-mail address fails the whole call.
	rpc SendCustomNotification( SendCustomNotificationRequest ) returns ( SendCustomNotificationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Asks the user who has an object checked out to check it in. Used by M-Files clients;
	// applications rarely call it.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - The request goes to the user who has the latest version checked out. If the object is not
	//   checked out, or event logging is disabled in the vault, the call succeeds and does nothing.
	// - The recipient is notified by e-mail when notifications are enabled.
	rpc CreateEventCheckInRequest( CreateEventCheckInRequestRequest ) returns ( CreateEventCheckInRequestResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Not available: fails with "Not implemented.".
	//
	// Kept for compatibility. To assign work to users, create an assignment object with
	// [AddObject](mfiles:MFiles.IRPCObjectOperations.AddObject).
	rpc CreateEventAssignRequest( CreateEventAssignRequestRequest ) returns ( CreateEventAssignRequestResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of SetNotificationConfiguration.
message SetNotificationConfigurationRequest {

	// Set `is_enabled` to true to receive notifications, or leave all flags unset to stop them.
	NOTIFICATIONFLAGS flags = 1;
}

// The response of SetNotificationConfiguration.
message SetNotificationConfigurationResponse {
}

// The request of GetNotificationConfiguration.
message GetNotificationConfigurationRequest {
}

// The response of GetNotificationConfiguration.
message GetNotificationConfigurationResponse {

	// The caller's notification switch. `is_enabled` is true when the caller receives notifications.
	NOTIFICATIONFLAGS pflags = 1;
}

// The request of CreateEventFreeRequest.
message CreateEventFreeRequestRequest {

	// The message of the request.
	string text = 1;

	// The IDs of the recipient user accounts.
	repeated int32 users = 2;

	// The IDs of the recipient user groups.
	repeated int32 groups = 3;
}

// The response of CreateEventFreeRequest.
message CreateEventFreeRequestResponse {
}

// The request of TestMessageToUser.
message TestMessageToUserRequest {

	// The ID of the user account to check, or -1 for the caller.
	int32 user_id = 1;

	// True to also fail when the user has turned notifications off. Leave false to check only whether requests can reach the user.
	bool test_notifications_disabled_by_user = 2;

	// Must be false; sending a test message is not supported.
	bool send_message = 3;
}

// The response of TestMessageToUser.
message TestMessageToUserResponse {
}

// The request of SendCustomNotification.
message SendCustomNotificationRequest {

	// The recipient users and user groups.
	repeated UserOrUserGroupID uugidarr = 1;

	// True to also send to the substitute users of the recipient users.
	bool include_substitute_users = 2;

	// Additional recipients as e-mail addresses, for example `name@example.com`. Requires the server right `send_server_messages`.
	repeated string external_recipients = 3;

	// True to send from the server's notification address instead of the caller's own address. Requires the server right `send_server_messages`.
	bool send_with_server_email_identity = 4;

	// The subject of the e-mail.
	string subject = 5;

	// The body of the e-mail.
	string body = 6;
}

// The response of SendCustomNotification.
message SendCustomNotificationResponse {
}

// The request of CreateEventCheckInRequest.
message CreateEventCheckInRequestRequest {

	// The object that should be checked in.
	ObjID objid = 1;
}

// The response of CreateEventCheckInRequest.
message CreateEventCheckInRequestResponse {
}

// The request of CreateEventAssignRequest.
message CreateEventAssignRequestRequest {

	// The document that is concerned by this request.
	ObjID objid = 1;

	// The users who receive the request.
	repeated int32 users = 2;

	// The groups who receive the request.
	repeated int32 groups = 3;
}

// The response of CreateEventAssignRequest.
message CreateEventAssignRequestResponse {
}