// 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 "google/protobuf/timestamp.proto";
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, exports and deletes the vault's event log, turns event logging on or off, and stores the
// caller's saved event log filters.
//
// MFAdmin uses this interface to admininistrate events.
//
// M-Files Admin uses this service for the vault's event log: viewing, exporting and clearing it.
// Every method needs a vault session and the vault right `manage_events` (part of full control);
// a normal user gets "Access denied." (0x800407E4 with reason 0x800400A9).
//
// - **Logging on or off**:
//   [IsEventLoggingEnabled](mfiles:MFiles.IRPCEventsAdmin.IsEventLoggingEnabled),
//   [EnableEventLogging](mfiles:MFiles.IRPCEventsAdmin.EnableEventLogging).
// - **Read events** ([Event](mfiles:MFiles.Event)): find the ID range with
//   [GetMinAndMaxEventIDs](mfiles:MFiles.IRPCEventsAdmin.GetMinAndMaxEventIDs), then read pages with
//   [GetEventsRange](mfiles:MFiles.IRPCEventsAdmin.GetEventsRange).
// - **Export and delete**: after saving the events elsewhere, record the export with
//   [EventsExported](mfiles:MFiles.IRPCEventsAdmin.EventsExported) and remove them with
//   [DeleteEventsRange](mfiles:MFiles.IRPCEventsAdmin.DeleteEventsRange);
//   [ClearEvents](mfiles:MFiles.IRPCEventsAdmin.ClearEvents) removes all events.
// - **Saved filters** of the event log viewer, private to each user:
//   [SaveEventLogFilter](mfiles:MFiles.IRPCEventsAdmin.SaveEventLogFilter),
//   [GetEventLogFilters](mfiles:MFiles.IRPCEventsAdmin.GetEventLogFilters),
//   [DeleteEventLogFilters](mfiles:MFiles.IRPCEventsAdmin.DeleteEventLogFilters),
//   [GetEventLogFilterRecord](mfiles:MFiles.IRPCEventsAdmin.GetEventLogFilterRecord),
//   [UpdateEventLogFilterDefaultValue](mfiles:MFiles.IRPCEventsAdmin.UpdateEventLogFilterDefaultValue).
//
// **Client version.** [GetEventsRange](mfiles:MFiles.IRPCEventsAdmin.GetEventsRange) and
// [GetEvents](mfiles:MFiles.IRPCEventsAdmin.GetEvents) fail with "The installed M-Files client
// version is older than the M-Files Server version." (0x80040930) unless the session was opened
// with `client_data.version` 12.0.5192.0 or newer. Log in with `client_data.version` set to the
// `server_version` from [QueryVersion](mfiles:MFiles.IRPCQueryVersion.QueryVersion).
//
// **-1 means "no filter".** Event ID bounds and object filters use -1 for "not set". The proto3
// default 0 is a real value: a request left at its defaults matches no events.
//
// **Advanced event log features** (21 CFR Part 11 compliance): when they are enabled in the vault,
// event logging cannot be turned off and [ClearEvents](mfiles:MFiles.IRPCEventsAdmin.ClearEvents)
// is refused; [DeleteEventsRange](mfiles:MFiles.IRPCEventsAdmin.DeleteEventsRange) still works.
service IRPCEventsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Event administration" };

	// Turns event logging of the vault on or off.
	//
	// - Requires a vault session and the vault right `manage_events`.
	// - Turning logging off fails with "This operation is not allowed when the advanced event log
	//   features are enabled." in vaults that use those features.
	// - Changes only future logging; existing events stay.
	rpc EnableEventLogging( EnableEventLoggingRequest ) returns ( EnableEventLoggingResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Tells whether event logging is on in the vault.
	//
	// - Requires a vault session and the vault right `manage_events` (a normal user is
	//   denied).
	rpc IsEventLoggingEnabled( IsEventLoggingEnabledRequest ) returns ( IsEventLoggingEnabledResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes all events of the vault.
	//
	// - **Destructive.** Removes the whole event log; export it first if you need it
	//   ([GetEventsRange](mfiles:MFiles.IRPCEventsAdmin.GetEventsRange)).
	// - Runs in the background: the server first creates the pending notifications, then deletes the
	//   events. The call returns after about five seconds, possibly before the log is empty.
	// - Requires a vault session and the vault right `manage_events`. Refused in vaults with the
	//   advanced event log features; use
	//   [DeleteEventsRange](mfiles:MFiles.IRPCEventsAdmin.DeleteEventsRange) there.
	rpc ClearEvents( ClearEventsRequest ) returns ( ClearEventsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes the events whose IDs are in the given range.
	//
	// - **Destructive.** Set both bounds to -1 to delete all events; the defaults (0 and 0) delete
	//   only an event with ID 0.
	// - Deletes only events for which notifications have been created. Before deleting, the server
	//   starts notification processing and waits about five seconds; events still waiting for it
	//   stay.
	// - Adds an "event log cleared" event (`EVENT_TYPE_EVENT_LOG_CLEARED`) with the range, when event
	//   logging is on.
	// - Requires a vault session and the vault right `manage_events`. Allowed also in vaults with the
	//   advanced event log features.
	rpc DeleteEventsRange( DeleteEventsRangeRequest ) returns ( DeleteEventsRangeResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Records in the event log that a range of events was exported.
	//
	// - Exports nothing itself: it adds an "event log exported" event
	//   (`EVENT_TYPE_EVENT_LOG_EXPORTED`) with the given range and filters, when event logging is on.
	//   Call it after you have saved the events, for the audit trail.
	// - Requires a vault session and the vault right `manage_events`.
	rpc EventsExported( EventsExportedRequest ) returns ( EventsExportedResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the smallest and largest event ID in the vault's event log.
	//
	// - Requires a vault session and the vault right `manage_events`.
	// - Both are 0 when the log is empty. IDs grow over time but are not contiguous: deleted events
	//   leave gaps.
	rpc GetMinAndMaxEventIDs( GetMinAndMaxEventIDsRequest ) returns ( GetMinAndMaxEventIDsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets all events of the vault.
	//
	// - Prefer [GetEventsRange](mfiles:MFiles.IRPCEventsAdmin.GetEventsRange): it pages and filters.
	// - In M-Files Server 26.11 the call fails with a database error ("Failed to prepare the SQL
	//   statement."). Use GetEventsRange.
	// - Requires a vault session, the vault right `manage_events`, and `client_data.version` set at
	//   login (see the service overview). Fails with "Your event log request exceeds the maximum data
	//   size." when the log is large.
	rpc GetEvents( GetEventsRequest ) returns ( GetEventsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets events by ID range and filters, oldest or newest first, with an optional maximum count.
	//
	// - Requires a vault session, the vault right `manage_events`, and `client_data.version` set at
	//   login (see the service overview).
	// - **Set -1 explicitly** in `oldest_event_to_get`, `newest_event_to_get`, `object_type_filter`
	//   and `object_id_filter` unless you filter on them; 0 is a real value, so a default request
	//   returns nothing.
	// - Filters are combined with AND. `object_title_filter` and `event_caused_by_user` must match
	//   exactly (`event_caused_by_user` is the account name, as in `Event.caused_by_user`). The time
	//   filter applies only when both `start_time_filter` and `end_time_filter` are set.
	// - Events are sorted by ID: ascending, or descending with `get_newest`. To page, repeat the call
	//   with `oldest_event_to_get` (or `newest_event_to_get` with `get_newest`) moved past the last ID
	//   you received. Internal notification-matching events are never returned.
	// - Fails with "Your event log request exceeds the maximum data size." when the matching events
	//   hold more data than the vault allows in one request (512 MiB by default); narrow the range.
	// - `Event.notification_object_info` is filled only in vaults with the advanced event log
	//   features.
	rpc GetEventsRange( GetEventsRangeRequest ) returns ( GetEventsRangeResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Saves a named event log filter for the calling user.
	//
	// - Requires a vault session with a user account in the vault and the vault right
	//   `manage_events`.
	// - Filters are private to the user who saves them. A name that the user already has fails with
	//   "There is already a filtered view with the same name.", so repeating the call is not safe.
	// - The server assigns the ID and records the caller as creator; `id` and
	//   `created_by_user_account` in the request are ignored. With `default_filter_view` true, the
	//   user's previous default filter stops being the default.
	rpc SaveEventLogFilter( SaveEventLogFilterRequest ) returns ( SaveEventLogFilterResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the event log filters saved by the calling user.
	//
	// - Requires a vault session and the vault right `manage_events`.
	// - Returns only the caller's own filters; empty if there are none.
	rpc GetEventLogFilters( GetEventLogFiltersRequest ) returns ( GetEventLogFiltersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes saved event log filters of the calling user by ID.
	//
	// - **Destructive.** Deletes the filters whose `id` is given; other fields are ignored.
	// - Requires a vault session and the vault right `manage_events`. Only the caller's own filters
	//   can be deleted: if any ID is unknown or belongs to another user, the call fails and nothing
	//   is deleted.
	rpc DeleteEventLogFilters( DeleteEventLogFiltersRequest ) returns ( DeleteEventLogFiltersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the conditions of the calling user's default event log filter.
	//
	// - Requires a vault session and the vault right `manage_events`.
	// - When the user has no default filter, the response has `object_type` -1, `object_class` -2 and
	//   everything else empty.
	rpc GetEventLogFilterRecord( GetEventLogFilterRecordRequest ) returns ( GetEventLogFilterRecordResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Makes a saved event log filter the user's default filter, or clears its default flag.
	//
	// - Requires a vault session and the vault right `manage_events`.
	// - Only `id` and `default_filter_view` are used. With `default_filter_view` true, the caller's
	//   previous default filter stops being the default. An unknown `id` is not reported as an error.
	rpc UpdateEventLogFilterDefaultValue( UpdateEventLogFilterDefaultValueRequest ) returns ( UpdateEventLogFilterDefaultValueResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of EnableEventLogging.
message EnableEventLoggingRequest {

	// True to turn event logging on, false to turn it off.
	bool enable = 1;
}

// The response of EnableEventLogging.
message EnableEventLoggingResponse {
}

// The request of IsEventLoggingEnabled.
message IsEventLoggingEnabledRequest {
}

// The response of IsEventLoggingEnabled.
message IsEventLoggingEnabledResponse {

	// True if the vault logs events.
	bool enabled = 1;
}

// The request of ClearEvents.
message ClearEventsRequest {
}

// The response of ClearEvents.
message ClearEventsResponse {
}

// The request of DeleteEventsRange.
message DeleteEventsRangeRequest {

	// The lowest event ID to delete, or -1 for no lower bound.
	int64 oldest_event_to_delete = 1;

	// The highest event ID to delete, or -1 for no upper bound.
	int64 newest_event_to_delete = 2;
}

// The response of DeleteEventsRange.
message DeleteEventsRangeResponse {
}

// The request of EventsExported.
message EventsExportedRequest {

	// The lowest exported event ID, or -1 for no lower bound.
	int64 oldest_exported_event = 1;

	// The highest exported event ID, or -1 for no upper bound.
	int64 newest_exported_event = 2;

	// The object type the export was limited to, or -1 for none.
	int32 object_type_filter = 3;

	// The object ID the export was limited to, or -1 for none.
	int32 object_idfilter = 4;
}

// The response of EventsExported.
message EventsExportedResponse {
}

// The request of GetMinAndMaxEventIDs.
message GetMinAndMaxEventIDsRequest {
}

// The response of GetMinAndMaxEventIDs.
message GetMinAndMaxEventIDsResponse {

	// The ID of the oldest event, or 0 if there are no events.
	int64 min_event_id = 1;

	// The ID of the newest event, or 0 if there are no events.
	int64 max_event_id = 2;
}

// The request of GetEvents.
message GetEventsRequest {
}

// The response of GetEvents.
message GetEventsResponse {

	// The events, newest first. See [Event](mfiles:MFiles.Event).
	repeated Event values = 1;
}

// Gets the specified range of events from the vault.
message GetEventsRangeRequest {

	// The lowest event ID to return, or -1 for no lower bound.
	int64 oldest_event_to_get = 1;

	// The highest event ID to return, or -1 for no upper bound. The default 0 returns nothing.
	int64 newest_event_to_get = 2;

	// The maximum number of events to return; 0 for no limit. With `get_newest` the newest matching events are returned, otherwise the oldest.
	uint32 max_events_to_return = 3;

	// True to return the newest matching events first (descending IDs), false for the oldest first.
	bool get_newest = 4;

	// Only events of objects of this object type, or -1 for all.
	int32 object_type_filter = 5;

	// Only events of the object with this ID, or -1 for all.
	int32 object_id_filter = 6;

	// Only events of objects with exactly this title; empty for all.
	string object_title_filter = 7;

	// Only events of objects of this class; used only when `has_class_filter` is true.
	int32 object_class_filter = 8;

	// True to apply `object_class_filter`.
	bool has_class_filter = 9;

	// Only events at or after this time (UTC). Used only together with `end_time_filter`.
	google.protobuf.Timestamp start_time_filter = 10;

	// Only events at or before this time (UTC). Used only together with `start_time_filter`.
	google.protobuf.Timestamp end_time_filter = 11;

	// Only events of these types; empty for all types.
	EventTypeArray event_types = 12;

	// Only events caused by this account name; empty for all.
	string event_caused_by_user = 13;
}

// Gets the specified range of events from the vault.
message GetEventsRangeResponse {

	// The matching events. See [Event](mfiles:MFiles.Event).
	repeated Event events = 1;

	// True when `disabled_event_types` is filled; always true on current servers.
	bool has_disabled_event_types_info = 2;

	// The event types that the vault's settings exclude from logging, so their absence from the results does not mean nothing happened.
	EventTypeArray disabled_event_types = 3;
}

// The request of SaveEventLogFilter.
message SaveEventLogFilterRequest {

	// The filter to save: `name`, `condition` and `default_filter_view`. See [EventLogFilter](mfiles:MFiles.EventLogFilter).
	EventLogFilter event_log_filter = 1;
}

// The response of SaveEventLogFilter.
message SaveEventLogFilterResponse {
}

// The request of GetEventLogFilters.
message GetEventLogFiltersRequest {
}

// The response of GetEventLogFilters.
message GetEventLogFiltersResponse {

	// The caller's saved filters.
	EventLogFilterArray event_log_filters = 1;
}

// The request of DeleteEventLogFilters.
message DeleteEventLogFiltersRequest {

	// The filters to delete, identified by `id`.
	EventLogFilterArray event_log_filters = 1;
}

// The response of DeleteEventLogFilters.
message DeleteEventLogFiltersResponse {
}

// A structure that specifies GetEventLogFilterRecord request payload.
message GetEventLogFilterRecordRequest {
}

// This is copy of EventLogFilterCondition for backwards compatibility.
// Cannot use alias because alias that would require service proto to depend directly on struct proto.
message GetEventLogFilterRecordResponse {

	// Object Type in Filter View.
	int32 object_type = 1;

	// Object ID in Filter View.
	string object_id = 2;

	// Object Name in Filter View.
	string object_name = 3;

	// Object Class in Filter View.
	int32 object_class = 4;

	// Event Types in Filter View.
	EventTypeArray event_types = 5;

	// User name in Filter View.
	string event_caused_by_user = 6;

	// Start time in Filter View.
	google.protobuf.Timestamp start_time = 7;

	// End time in Filter View.
	google.protobuf.Timestamp end_time = 8;
}

// This is copy of EventLogFilter for backwards compatibility.
// Cannot use alias because alias that would require service proto to depend directly on struct proto.
message UpdateEventLogFilterDefaultValueRequest {

	// The ID of one of your saved filters, from [GetEventLogFilters](mfiles:MFiles.IRPCEventsAdmin.GetEventLogFilters).
	int64 id = 1;

	// Ignored.
	string name = 2;

	// Ignored.
	int32 created_by_user_account = 3;

	// Ignored.
	EventLogFilterCondition condition = 4;

	// True to make the filter the default, false to clear its default flag.
	bool default_filter_view = 5;
}

// A structure that specifies UpdateEventLogFilterDefaultValue response payload.
message UpdateEventLogFilterDefaultValueResponse {
}