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

// Creates and manages shared links to files for people outside the vault.
//
// Creates and manages shared links: links that give people outside the vault access to one file of
// a document. A link is identified by its **access key**, a 64-character random string that the
// server generates. Anyone who has the access key and the vault GUID can use the link through
// [IRPCSharedLinksPublic](mfiles:MFiles.IRPCSharedLinksPublic) without logging in, so treat access
// keys as secrets.
//
// Link types ([SharedLinkType](mfiles:MFiles.SharedLinkType)):
//
// - `SHARED_LINK_TYPE_READ_ONLY`: a public download link. Anyone with the key can download the
//   file. Points to a specific checked-in object version.
// - `SHARED_LINK_TYPE_EXTERNAL`: an external link, shared with named visitors (recipients) that
//   each have an expiration time and access type, or with anyone who has the link
//   (`is_anyone_access_granted`). Points to the latest version.
// - `SHARED_LINK_TYPE_VISITOR`: the older form of a link shared with named visitors. Points to
//   the latest version.
// - `SHARED_LINK_TYPE_CO_AUTHORING`, `SHARED_LINK_TYPE_WOPIREADONLY`, `SHARED_LINK_TYPE_WOPIEDIT`:
//   internal links for co-authoring and Office for the web, used by M-Files clients.
//
// Typical flows:
//
// - **Public download link**:
//   [CreateSharedLink](mfiles:MFiles.IRPCSharedLinks.CreateSharedLink) with
//   `SHARED_LINK_TYPE_READ_ONLY`; list with
//   [GetSharedLinks](mfiles:MFiles.IRPCSharedLinks.GetSharedLinks) or
//   [GetSharedLinksByObject](mfiles:MFiles.IRPCSharedLinks.GetSharedLinksByObject); remove with
//   [DeleteSharedLink](mfiles:MFiles.IRPCSharedLinks.DeleteSharedLink).
// - **External link**: check
//   [GetExternalSharingSettings](mfiles:MFiles.IRPCSharedLinks.GetExternalSharingSettings), create
//   the link with `SHARED_LINK_TYPE_EXTERNAL`, add visitors with
//   [AddSharedLinkRecipients](mfiles:MFiles.IRPCSharedLinks.AddSharedLinkRecipients), and manage
//   them with [GetSharedLinkRecipients](mfiles:MFiles.IRPCSharedLinks.GetSharedLinkRecipients),
//   [SetSharedLinkRecipients](mfiles:MFiles.IRPCSharedLinks.SetSharedLinkRecipients) and
//   [RemoveSharedLinkRecipients](mfiles:MFiles.IRPCSharedLinks.RemoveSharedLinkRecipients). Grant
//   or revoke access for anyone with the link with
//   [SetSharedLinks](mfiles:MFiles.IRPCSharedLinks.SetSharedLinks). List an object's external
//   links with [GetExternalLinks](mfiles:MFiles.IRPCSharedLinks.GetExternalLinks).
//
// Prerequisites: sharing must be enabled on the server and in the vault; otherwise the methods fail
// with "Access denied." (except for the internal link types). Read-only links, and external links
// open to anyone, also need the vault setting that allows sharing with anyone who has the link.
// Anonymous sessions cannot use this service.
//
// **Times.** An unset expiration time means "never expires"; the server returns it as
// 1601-01-01T00:00:00Z. A recipient added without an expiration time is returned with
// 1753-01-01T00:00:00Z.
//
// **Errors.** An unknown, deleted or expired access key fails with "The link is either expired or
// invalid.".
service IRPCSharedLinks {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Shared links" };

	// Creates a shared link to one file of an object and returns it with its new access key.
	//
	// - Requires read access to the object version. Read-only, external and visitor links can be
	//   created by users whose license does not allow modifications; the other types need
	//   `license_allows_modifications`. When print prevention is enabled in the vault, the user also
	//   needs the right to download the file.
	// - Leave `access_key`, `created_at_utc` and `created_by_user` unset (or set `created_by_user` to
	//   the caller's own ID); otherwise the call fails with "The parameter is incorrect.". `file_ver`
	//   must name one file; sharing all files of an object is not supported.
	// - `SHARED_LINK_TYPE_READ_ONLY`: `obj_ver` must be a specific, checked-in version and
	//   `file_ver.type` must be `FILE_VER_TYPE_ANY` (other file version types fail with "The parameter
	//   is incorrect. (FileVersion)"). Links to the latest version fail with "Access denied." unless
	//   the vault allows them, and links to a checked-out version fail.
	// - `SHARED_LINK_TYPE_EXTERNAL` and `SHARED_LINK_TYPE_VISITOR`: `obj_ver` and `file_ver` must
	//   refer to the latest version; a specific version fails with "Access denied.". Add visitors
	//   afterwards with [AddSharedLinkRecipients](mfiles:MFiles.IRPCSharedLinks.AddSharedLinkRecipients).
	// - The creation is recorded in the vault's event log.
	rpc CreateSharedLink( CreateSharedLinkRequest ) returns ( CreateSharedLinkResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Deletes a shared link, so that its access key stops working.
	//
	// - Read-only and other non-visitor links: the creator, or a user with the vault right
	//   `see_all_objects`, can delete them; others get "Access denied.".
	// - External links: any user who can see the full list of visitors (see
	//   `visitor_list_restricted` in
	//   [GetExternalSharingSettings](mfiles:MFiles.IRPCSharedLinks.GetExternalSharingSettings)) can
	//   delete the link, including links that other users created. The link and its recipients are
	//   removed.
	// - Visitor links: only the recipients are removed; the link itself remains.
	// - An unknown or already deleted key fails with "The link is either expired or invalid.".
	rpc DeleteSharedLink( DeleteSharedLinkRequest ) returns ( DeleteSharedLinkResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Gets one shared link by its access key.
	//
	// - Only the creator of the link, or a user with the vault right `see_all_objects`, can read it,
	//   and the caller must be able to read the linked object version.
	// - An unknown, deleted or expired key fails with "The link is either expired or invalid.".
	rpc GetSharedLink( GetSharedLinkRequest ) returns ( GetSharedLinkResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Lists the shared links that the caller created, or all links for users who can see all objects.
	//
	// - `by_user` must be -1 or the caller's own user ID. Any other value, including the default 0,
	//   fails with "The parameter is incorrect. (CreatedByUser)".
	// - Users with the vault right `see_all_objects` get the links of all users; other users get
	//   their own links. Links to objects that the caller cannot see are left out.
	// - Visitor and external links are included only when the server supports visitor links; then a
	//   link appears once per sharing user, with `description` replaced by the comma-separated
	//   recipients. Otherwise list external links with
	//   [GetExternalLinks](mfiles:MFiles.IRPCSharedLinks.GetExternalLinks).
	rpc GetSharedLinks( GetSharedLinksRequest ) returns ( GetSharedLinksResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Lists the shared links to one object.
	//
	// - Same rules as [GetSharedLinks](mfiles:MFiles.IRPCSharedLinks.GetSharedLinks): users with the
	//   vault right `see_all_objects` get every user's links, other users only their own.
	rpc GetSharedLinksByObject( GetSharedLinksByObjectRequest ) returns ( GetSharedLinksByObjectResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Not supported: always fails with "Not implemented.".
	rpc GetWOPILock( GetWOPILockRequest ) returns ( GetWOPILockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Not supported: always fails with "Not implemented.".
	rpc SetWOPILock( SetWOPILockRequest ) returns ( SetWOPILockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Not supported: always fails with "Not implemented.".
	rpc RemoveWOPILock( RemoveWOPILockRequest ) returns ( RemoveWOPILockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Adds visitors (email recipients) to an external or visitor link and returns all its recipients.
	//
	// - The link must be an external or visitor link; other types fail with "The parameter is
	//   incorrect.". `emails` must not be empty.
	// - Each entry is an email address, optionally in mailbox form (`Name <address@example.com>`). An
	//   invalid address fails the call with the invalid email address error (0x80040811), which has no
	//   description text.
	// - Recipients that the caller has already added are skipped. This call does not email the
	//   recipients.
	// - The creator of the link must still have read access to the object.
	// - Side effect: the expiration time of the link itself is set to 23:59 UTC on the Sunday about 12
	//   weeks ahead. Recipients keep their own expiration times.
	// - The response lists all recipients that the caller can see, not just the added ones.
	rpc AddSharedLinkRecipients( AddSharedLinkRecipientsRequest ) returns ( AddSharedLinkRecipientsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Lists the visitors (email recipients) of an external or visitor link.
	//
	// - Users who cannot see the full list of visitors (see `visitor_list_restricted` in
	//   [GetExternalSharingSettings](mfiles:MFiles.IRPCSharedLinks.GetExternalSharingSettings)) get
	//   only the recipients they added themselves.
	// - Recipients with a name are returned in mailbox form (`Name <address>`).
	// - Reading the visitors of an external link is recorded in the vault's event log.
	rpc GetSharedLinkRecipients( GetSharedLinkRecipientsRequest ) returns ( GetSharedLinkRecipientsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Removes visitors from an external or visitor link.
	//
	// - Give the plain email addresses (without a name). Addresses that are not recipients are
	//   ignored.
	// - Users who cannot see the full list of visitors can remove only the recipients they added.
	rpc RemoveSharedLinkRecipients( RemoveSharedLinkRecipientsRequest ) returns ( RemoveSharedLinkRecipientsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}

	// Updates the access type of shared links, and grants or revokes access for anyone who has the
	// link.
	//
	// - For each link, the server sets `external_shared_link_access_type` and the anyone-with-the-link
	//   state from the request. Every call writes both: a link sent without
	//   `is_anyone_access_granted` loses its anyone access.
	// - With `is_anyone_access_granted` true, `expires_at_utc` must be in the future (otherwise "The
	//   parameter is incorrect.") and becomes the link's expiration time; the vault must allow sharing
	//   with anyone who has the link. Without it, `expires_at_utc` is ignored; visitors have their own
	//   expiration times.
	// - Other fields of the links are ignored. Duplicate access keys are processed once.
	// - The response contains the updated links. The caller must be able to read the linked objects.
	rpc SetSharedLinks( SetSharedLinksRequest ) returns ( SetSharedLinksResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Updates the expiration time and access type of visitors of external links.
	//
	// - Each entry names a link (`access_key`) and a recipient (`recipient.email`, the plain
	//   address). `recipient.expires_at_utc` must be in the future; otherwise the call fails with
	//   "The parameter is incorrect.".
	// - Users who cannot see the full list of visitors can update only the recipients they added;
	//   other entries are left unchanged.
	rpc SetSharedLinkRecipients( SetSharedLinkRecipientsRequest ) returns ( SetSharedLinkRecipientsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Tells whether sharing is enabled in the vault and what the caller may do with external links.
	//
	// - Requires a vault session. Does not fail when sharing is disabled; check `sharing_enabled`.
	rpc GetExternalSharingSettings( GetExternalSharingSettingsRequest ) returns ( GetExternalSharingSettingsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}

	// Lists the external links of an object.
	//
	// - Users with the vault right `see_all_objects`, and users with access to the latest version of
	//   the object, get all external links of the object; other users get the links they created.
	rpc GetExternalLinks( GetExternalLinksRequest ) returns ( GetExternalLinksResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION returns_metadata_structure_version: true };
	}
}

// The request of CreateSharedLink.
message CreateSharedLinkRequest {

	// The link to create: `shared_link_type`, `obj_ver`, `file_ver`, and optionally `description`, `expires_at_utc` (unset for no expiration) and, for external links, `external_shared_link_access_type` and `is_anyone_access_granted`.
	SharedLinkInfo sl_info = 1;
}

// The response of CreateSharedLink.
message CreateSharedLinkResponse {

	// The created link, including its `access_key`.
	SharedLinkInfo sl_info_result = 1;
}

// The request of DeleteSharedLink.
message DeleteSharedLinkRequest {

	// The access key of the link.
	string access_key = 1;
}

// The response of DeleteSharedLink.
message DeleteSharedLinkResponse {
}

// The request of GetSharedLink.
message GetSharedLinkRequest {

	// The access key of the link.
	string access_key = 1;
}

// The response of GetSharedLink.
message GetSharedLinkResponse {

	// The link.
	SharedLinkInfo sl_info_result = 1;
}

// The request of GetSharedLinks.
message GetSharedLinksRequest {

	// Set -1. The caller's own user ID gives the same result for normal users.
	int32 by_user = 1;
}

// The response of GetSharedLinks.
message GetSharedLinksResponse {

	// The links, including their access keys.
	repeated SharedLinkInfo shared_links = 1;
}

// The request of GetSharedLinksByObject.
message GetSharedLinksByObjectRequest {

	// The object.
	ObjID obj_id = 1;
}

// The response of GetSharedLinksByObject.
message GetSharedLinksByObjectResponse {

	// The links to the object.
	repeated SharedLinkInfo shared_links = 1;
}

// The request of GetWOPILock.
message GetWOPILockRequest {

	// The vault identifier.
	string vault = 1;

	// Specifies the access key.
	string access_key = 2;
}

// The response of GetWOPILock.
message GetWOPILockResponse {

	// WOPI lock data.
	WOPILock info = 1;
}

// The request of SetWOPILock.
message SetWOPILockRequest {

	// The vault identifier.
	string vault = 1;

	// Specifies the access key.
	string access_key = 2;

	// Specifies the WOPI lock key.
	string lock = 3;
}

// The response of SetWOPILock.
message SetWOPILockResponse {
}

// The request of RemoveWOPILock.
message RemoveWOPILockRequest {

	// The vault identifier.
	string vault = 1;

	// Specifies the access key.
	string access_key = 2;
}

// The response of RemoveWOPILock.
message RemoveWOPILockResponse {
}

// The request of AddSharedLinkRecipients.
message AddSharedLinkRecipientsRequest {

	// The access key of an external or visitor link.
	string access_key = 1;

	// The recipient addresses, optionally as `Name <address>`.
	repeated string emails = 2;

	// The expiration time for the added recipients. Unset for no expiration.
	google.protobuf.Timestamp expires_at_utc = 3;

	// What the added recipients may do with the file.
	ExternalSharedLinkAccessType external_shared_link_access_type = 4;
}

// The response of AddSharedLinkRecipients.
message AddSharedLinkRecipientsResponse {

	// All recipients of the link that the caller can see.
	repeated SharedLinkRecipient recipients = 1;
}

// The request of GetSharedLinkRecipients.
message GetSharedLinkRecipientsRequest {

	// The access key of the link.
	string access_key = 1;
}

// The response of GetSharedLinkRecipients.
message GetSharedLinkRecipientsResponse {

	// The recipients, with their expiration time and access type.
	repeated SharedLinkRecipient recipients = 1;
}

// The request of RemoveSharedLinkRecipients.
message RemoveSharedLinkRecipientsRequest {

	// The access key of the link.
	string access_key = 1;

	// The email addresses to remove.
	repeated string recipients = 2;
}

// The response of RemoveSharedLinkRecipients.
message RemoveSharedLinkRecipientsResponse {
}

// The request of SetSharedLinks.
message SetSharedLinksRequest {

	// The links to update, identified by `access_key`, with the new `external_shared_link_access_type`, `is_anyone_access_granted` and `expires_at_utc`.
	repeated SharedLinkInfo shared_links = 1;
}

// The response of SetSharedLinks.
message SetSharedLinksResponse {

	// The links after the update.
	repeated SharedLinkInfo shared_links = 1;
}

// The request of SetSharedLinkRecipients.
message SetSharedLinkRecipientsRequest {

	// The recipients to update, each with the link's `access_key` and the new `expires_at_utc` and `external_shared_link_access_type`.
	repeated SetSharedLinkRecipient recipients = 1;
}

// The response of SetSharedLinkRecipients.
message SetSharedLinkRecipientsResponse {

	// The updated recipients.
	repeated SetSharedLinkRecipient recipients = 1;
}

// The request of GetExternalSharingSettings.
message GetExternalSharingSettingsRequest {
}

// The response of GetExternalSharingSettings.
message GetExternalSharingSettingsResponse {

	// True if links may be opened by anyone who has them (read-only links and external links with anyone access).
	bool allow_sharing_to_anyone_with_the_link = 1;

	// True if sharing is enabled on the server and in the vault.
	bool sharing_enabled = 2;

	// True if the caller sees only the visitors they added, not all visitors of a link.
	bool visitor_list_restricted = 3;
}

// The request of GetExternalLinks.
message GetExternalLinksRequest {

	// The object.
	ObjID obj_id = 1;
}

// The response of GetExternalLinks.
message GetExternalLinksResponse {

	// The external links, including their access keys.
	repeated SharedLinkInfo external_shared_links = 1;

	// True if the latest version of the object also has read-only or visitor links.
	bool legacy_shared_link_exist = 2;
}