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

// Opens and downloads files through shared links, without logging in.
//
// The anonymous side of shared links: opens and downloads a file shared with
// [CreateSharedLink](mfiles:MFiles.IRPCSharedLinks.CreateSharedLink). No login and no session
// are needed; every call names the vault by its GUID and the link by its access key. Use it to
// build a download page for people outside the vault.
//
// **Public read-only link** (`SHARED_LINK_TYPE_READ_ONLY`, or an external link open to anyone):
//
// 1. [GetSharedLinkInfo](mfiles:MFiles.IRPCSharedLinksPublic.GetSharedLinkInfo) for the file name,
//    extension and size.
// 2. [DownloadSharedFile_Begin](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_Begin)
//    for a download ID, the size and the MD5 checksum.
// 3. [DownloadSharedFile_ReadBlock](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_ReadBlock)
//    in a loop until all bytes are read.
//
// **Link shared with named visitors** (visitor links, and external links that are not open to
// anyone): the visitor proves their email address first.
//
// 1. [AccessSharedLink](mfiles:MFiles.IRPCSharedLinksPublic.AccessSharedLink) with the visitor's
//    email address returns an access session value. If the address is a recipient of the link,
//    the server emails an access code to it.
// 2. Pass the address, the access code and the access session in `additional_data` of
//    [GetSharedLinkInfo](mfiles:MFiles.IRPCSharedLinksPublic.GetSharedLinkInfo) and
//    [DownloadSharedFile_Begin](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_Begin), as
//    [NamedValue](mfiles:MFiles.NamedValue) entries named `RECIPIENT_EMAIL`,
//    `RECIPIENT_ACCESSCODE` and `ACCESS_SESSION`. Without them, an external link that is not open
//    to anyone fails with "Authentication required to access the shared link.".
//
// Shared links must be enabled on the server and in the vault. An unknown, deleted or expired
// access key fails with "The link is either expired or invalid.". The upload and WOPI methods
// serve co-authoring and Office for the web in M-Files clients; applications rarely call them.
service IRPCSharedLinksPublic {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Shared links (anonymous access)" };

	// Reads one block of a file download started with DownloadSharedFile_Begin.
	//
	// - No session is needed. `access_key` must be the key that started the download; another key
	//   fails with "The link is either expired or invalid.".
	// - `block_size` can be at most 4 MiB (4 194 304 bytes). Read until you have `file_size` bytes; a
	//   block can be shorter than requested. See
	//   [Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/) for block sizes and
	//   message size limits.
	rpc DownloadSharedFile_ReadBlock( DownloadSharedFile_ReadBlockRequest ) returns ( DownloadSharedFile_ReadBlockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Starts downloading the file of a shared link, without logging in, and returns a download ID,
	// the file size and its MD5 checksum.
	//
	// - No session is needed. For links shared with named visitors, pass the visitor values in
	//   `additional_data` (see the service overview).
	// - Then read the content with
	//   [DownloadSharedFile_ReadBlock](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_ReadBlock),
	//   sending the same `vault` and `access_key`.
	// - The MD5 checksum is split in two: the 16 checksum bytes are the 8 bytes of `low_digest`
	//   followed by the 8 bytes of `high_digest`, each in little-endian order.
	// - Co-authoring links cannot be downloaded ("The parameter is incorrect.").
	rpc DownloadSharedFile_Begin( DownloadSharedFile_BeginRequest ) returns ( DownloadSharedFile_BeginResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Gets the name, extension and size of the file that a shared link points to, without logging in.
	//
	// - No session is needed. Set `vault` to the vault GUID and `access_key` to the
	//   link's key.
	// - External and visitor links always point to the latest version of the file; read-only links
	//   to the version they were created for.
	// - For links shared with named visitors, pass the visitor values in `additional_data` (see the
	//   service overview).
	// - For read-only links, the access is recorded in the vault's event log. Add a `CLIENT_IP` entry
	//   to `additional_data` to include the visitor's IP address in the event.
	rpc GetSharedLinkInfo( GetSharedLinkInfoRequest ) returns ( GetSharedLinkInfoResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Uploads a block of new content for a file opened for editing in Office for the web. Used by
	// M-Files clients; applications rarely call it.
	//
	// - Works only with links of type `SHARED_LINK_TYPE_WOPIEDIT`; other links fail with "The
	//   parameter is incorrect.".
	// - Start with `upload_id` 0 and `offset` 0, then send the following blocks with the returned
	//   `upload_id`. Finish with
	//   [UploadSharedFileCommit](mfiles:MFiles.IRPCSharedLinksPublic.UploadSharedFileCommit).
	rpc UploadSharedFile( UploadSharedFileRequest ) returns ( UploadSharedFileResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Completes an upload made with UploadSharedFile and stores the content in the checked-out file.
	// Used by M-Files clients; applications rarely call it.
	//
	// - The object must be checked out. The number of bytes uploaded must match the
	//   `total_size_in_bytes` given with the first block.
	rpc UploadSharedFileCommit( UploadSharedFileCommitRequest ) returns ( UploadSharedFileCommitResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Gets information about the file of a link for Office for the web (WOPI) operations. Used by
	// M-Files clients; applications rarely call it.
	rpc GetWOPIFileInfo( GetWOPIFileInfoRequest ) returns ( GetWOPIFileInfoResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Starts a visitor's access to a link shared with named visitors: returns an access session value
	// and, if the email address is a recipient of the link, emails an access code to it.
	//
	// - No session is needed. An email address that is not valid fails the call.
	// - The server returns an access session value whether or not the address is a recipient, so the
	//   response does not reveal who the recipients are.
	// - Pass the access session, the email address and the access code that the visitor received to
	//   [GetSharedLinkInfo](mfiles:MFiles.IRPCSharedLinksPublic.GetSharedLinkInfo) and
	//   [DownloadSharedFile_Begin](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_Begin) in
	//   `additional_data` (`ACCESS_SESSION`, `RECIPIENT_EMAIL`, `RECIPIENT_ACCESSCODE`).
	rpc AccessSharedLink( AccessSharedLinkRequest ) returns ( AccessSharedLinkResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}
}

// The request of DownloadSharedFile_ReadBlock.
message DownloadSharedFile_ReadBlockRequest {

	// The vault GUID.
	string vault = 1;

	// The access key that started the download.
	string access_key = 2;

	// The `download_id` from DownloadSharedFile_Begin.
	int32 download_id = 3;

	// The number of bytes to read, at most 4 194 304.
	uint32 block_size = 4;

	// The position in the file to read from.
	int64 offset = 5;
}

// The response of DownloadSharedFile_ReadBlock.
message DownloadSharedFile_ReadBlockResponse {

	// The bytes read.
	bytes data = 1;
}

// The request of DownloadSharedFile_Begin.
message DownloadSharedFile_BeginRequest {

	// The vault GUID.
	string vault = 1;

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

	// Optional named values; see [GetSharedLinkInfo](mfiles:MFiles.IRPCSharedLinksPublic.GetSharedLinkInfo).
	repeated NamedValue additional_data = 3;
}

// The response of DownloadSharedFile_Begin.
message DownloadSharedFile_BeginResponse {

	// The download session ID for [DownloadSharedFile_ReadBlock](mfiles:MFiles.IRPCSharedLinksPublic.DownloadSharedFile_ReadBlock).
	int32 download_id = 1;

	// The size of the file in bytes.
	int64 file_size = 2;

	// The first 8 bytes of the MD5 checksum, as a little-endian integer.
	int64 low_digest = 3;

	// The last 8 bytes of the MD5 checksum, as a little-endian integer.
	int64 high_digest = 4;
}

// The request of GetSharedLinkInfo.
message GetSharedLinkInfoRequest {

	// The vault GUID, for example `{7BBEA0BC-40D8-4BCB-A67D-8A3ACFBDB575}`.
	string vault = 1;

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

	// Optional named values: `RECIPIENT_EMAIL`, `RECIPIENT_ACCESSCODE` and `ACCESS_SESSION` for links shared with named visitors, and `CLIENT_IP` for the event log.
	repeated NamedValue additional_data = 3;
}

// The response of GetSharedLinkInfo.
message GetSharedLinkInfoResponse {

	// The file's title, extension, size and change time.
	SharedFileInfo result = 1;
}

// The request of UploadSharedFile.
message UploadSharedFileRequest {

	// The vault GUID.
	string guid_vault = 1;

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

	// 0 for the first block; then the `upload_id` that the first call returned.
	int32 upload_id = 3;

	// Optional named values. Can be empty.
	repeated NamedValue additional_data = 4;

	// The total size of the file. Read only with the first block (`offset` 0).
	int64 total_size_in_bytes = 5;

	// The position of this block in the file. Use multiples of 4096 bytes.
	int64 offset = 6;

	// The bytes of this block.
	bytes data = 7;
}

// The response of UploadSharedFile.
message UploadSharedFileResponse {

	// The upload ID to use for the following blocks and the commit.
	int32 upload_id = 1;
}

// The request of UploadSharedFileCommit.
message UploadSharedFileCommitRequest {

	// The vault GUID.
	string vault = 1;

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

	// The upload ID from UploadSharedFile.
	int32 upload_id = 3;

	// If not zero, the first 8 bytes of the MD5 checksum of the uploaded file, as a little-endian integer.
	int64 low_digest = 4;

	// If not zero, the last 8 bytes of the MD5 checksum, as a little-endian integer.
	int64 high_digest = 5;
}

// The response of UploadSharedFileCommit.
message UploadSharedFileCommitResponse {
}

// The request of GetWOPIFileInfo.
message GetWOPIFileInfoRequest {

	// The vault GUID.
	string vault = 1;

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

// The response of GetWOPIFileInfo.
message GetWOPIFileInfoResponse {

	// The file's title, extension, size, the account name of the link's creator, and the object and file version.
	WOPIFileInfo result = 1;
}

// Requests shared link access.
message AccessSharedLinkRequest {

	// The vault GUID.
	string guid_vault = 1;

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

	// The visitor's email address.
	string email = 3;
}

// Response for shared link access request.
message AccessSharedLinkResponse {

	// The access session value to pass as `ACCESS_SESSION`.
	string access_session = 1;
}