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

// File, lock and session operations for Office for the web (WOPI), authorized by a WOPI access token
// instead of an M-Files session.
//
// **For M-Files components only.** The M-Files WOPI service, the WOPI host that Office for the web
// and the Office mobile apps talk to, calls these methods with the access token it received from
// Office. M-Files Web also calls a few of them. Applications should not call this service.
//
// - **No session.** Every method is called without `mfiles-session-id-bin`. The token in the
//   request names the vault (it holds the vault GUID) and maps to the M-Files session that created
//   it with [CreateWOPIUserSession](mfiles:MFiles.IRPCWOPIOperations.CreateWOPIUserSession) or
//   [CreateContainerAccessToken](mfiles:MFiles.IRPCWOPIOperations.CreateContainerAccessToken). The
//   method then runs in that session, with that user's permissions; it fails with access denied
//   when the token is malformed, unknown or expired, or when that session has ended.
// - **Token kinds:** a WOPI user session token (most methods), a one-time token (only
//   [GetWOPIUserSessionKey](mfiles:MFiles.IRPCWOPIOperationsPublic.GetWOPIUserSessionKey)), and a
//   container access token ([GetContainerInfo](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerInfo),
//   [GetContainerContent](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerContent), and
//   [GetWOPIUserSession](mfiles:MFiles.IRPCWOPIOperationsPublic.GetWOPIUserSession) with
//   `WOPITOKEN_TYPE_WOPICONTAINER_TOKEN`).
// - **Tasks:**
//   - Open the editor: [GetWOPIUserSessionKey](mfiles:MFiles.IRPCWOPIOperationsPublic.GetWOPIUserSessionKey)
//     (M-Files Web exchanges a one-time token from the URL) and
//     [GetWOPIUserSession](mfiles:MFiles.IRPCWOPIOperationsPublic.GetWOPIUserSession).
//   - File content: [WOPIDownloadFile_Begin](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIDownloadFile_Begin),
//     [WOPIDownloadFile_ReadBlock](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIDownloadFile_ReadBlock),
//     [WOPIUploadFile](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIUploadFile),
//     [WOPIUploadFileCommit](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIUploadFileCommit).
//   - WOPI locks: [GetLockForWOPI](mfiles:MFiles.IRPCWOPIOperationsPublic.GetLockForWOPI),
//     [SetLockForWOPI](mfiles:MFiles.IRPCWOPIOperationsPublic.SetLockForWOPI),
//     [RemoveLockForWOPI](mfiles:MFiles.IRPCWOPIOperationsPublic.RemoveLockForWOPI).
//   - Check-out and check-in: [WOPIFileCheckOut](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIFileCheckOut),
//     [WOPIFileCheckIn](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIFileCheckIn).
//   - Co-authoring: [GetActiveParticipants](mfiles:MFiles.IRPCWOPIOperationsPublic.GetActiveParticipants).
//   - End: [EndWOPIUserSession](mfiles:MFiles.IRPCWOPIOperationsPublic.EndWOPIUserSession).
//   - Office mobile apps browsing: [GetContainerInfo](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerInfo),
//     [GetContainerContent](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerContent).
// - **Errors:** invalid tokens fail with plain "Access denied." (0x800407E4); a token
//   for a vault that does not exist on the server answers after a delay of about 0.5 s.
// - **Cloud:** an M-Files Cloud server answers these methods anonymously (a made-up token fails
//   with "Access denied.").
service IRPCWOPIOperationsPublic {
	option (mfiles.api.service) = { book: "integration" level: LEVEL_SPECIALIZED title: "WOPI operations (anonymous)" };

	// Exchanges a one-time token for the WOPI user session token it stands for.
	//
	// **For M-Files components only.** M-Files Web calls it when its WOPI page is opened with a
	// one-time token in the URL. Applications should not call it.
	// - Authorized by the one-time token, which expires 5 minutes after it was created. The token is
	//   cleared after a successful exchange and cannot be used again.
	rpc GetWOPIUserSessionKey( GetWOPIUserSessionKeyRequest ) returns ( GetWOPIUserSessionKeyResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Checks in the object of a WOPI user session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it when Office for the web
	// unlocks a file it edited. Applications should not call it.
	// - Changes the object: checks in the shared object version, as the user of the session that
	//   created the token.
	rpc WOPIFileCheckIn( WOPIFileCheckInRequest ) returns ( WOPIFileCheckInResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Checks out the object of a read-only WOPI user session and turns the session into an editing
	// session.
	//
	// **For M-Files components only.** M-Files clients call it when the user switches from viewing to
	// editing in Office for the web. Applications should not call it.
	// - Changes the object: checks it out to the user of the session that created the token, creates a
	//   `SHARED_LINK_TYPE_WOPIEDIT` link to the new version and points the WOPI user session at it.
	// - Works only for a session created with `WOPIACTION_TYPE_VIEW`; other sessions fail with access
	//   denied.
	rpc WOPIFileCheckOut( WOPIFileCheckOutRequest ) returns ( WOPIFileCheckOutResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Ends a WOPI user session: its token stops working at once.
	//
	// **For M-Files components only.** M-Files clients call it to end a WOPI user session that they
	// created. Applications should not call it.
	// - Sets the expiration time of the WOPI user session to now. It does not check the object in.
	rpc EndWOPIUserSession( EndWOPIUserSessionRequest ) returns ( EndWOPIUserSessionResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Uploads a block of the new content of the file of a WOPI editing or co-authoring session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it when Office for the web saves
	// the file. Applications should not call it.
	// - Works only with a token whose link is for editing or co-authoring; others fail with "The
	//   parameter is incorrect.". The token's user needs read and edit access to the object.
	// - The first call has `upload_id` 0 and `offset` 0 and returns the upload ID; later calls pass
	//   it. Complete the upload with
	//   [WOPIUploadFileCommit](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIUploadFileCommit). A failed
	//   call deletes the upload.
	rpc WOPIUploadFile( WOPIUploadFileRequest ) returns ( WOPIUploadFileResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Stores an upload made with WOPIUploadFile as the new content of the file of the WOPI session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it at the end of a save from
	// Office for the web. Applications should not call it.
	// - Changes the file content of the object. The object must be checked out, the token's link must
	//   be for editing or co-authoring, and the token's user needs read and edit access.
	// - Fails with "File size mismatch." when the uploaded byte count differs from
	//   `total_size_in_bytes` of the first upload call. The upload is deleted after the commit, also
	//   when the commit fails.
	rpc WOPIUploadFileCommit( WOPIUploadFileCommitRequest ) returns ( WOPIUploadFileCommitResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Starts downloading the file of a WOPI user session and returns its size and MD5 checksum.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it when Office for the web
	// reads the file. Applications should not call it.
	// - The token's user needs read access to the object. Read the content with
	//   [WOPIDownloadFile_ReadBlock](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIDownloadFile_ReadBlock).
	rpc WOPIDownloadFile_Begin( WOPIDownloadFile_BeginRequest ) returns ( WOPIDownloadFile_BeginResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Reads a block of the file of a WOPI download session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it. Applications should not
	// call it.
	// - `download_id` must belong to a download started with the same token's link; otherwise the call
	//   fails with an invalid shared link error.
	rpc WOPIDownloadFile_ReadBlock( WOPIDownloadFile_ReadBlockRequest ) returns ( WOPIDownloadFile_ReadBlockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Gets the WOPI lock string of the file of a WOPI user session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it to implement the WOPI lock
	// operations. Applications should not call it.
	// - The token's user needs read and edit access to the object. Read-only.
	// - The WOPI lock is a string that Office for the web sets; it is separate from the M-Files
	//   check-out state.
	rpc GetLockForWOPI( GetLockForWOPIRequest ) returns ( GetLockForWOPIResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Sets the WOPI lock string of the file of a WOPI user session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it for the WOPI Lock, RefreshLock
	// and UnlockAndRelock operations. Applications should not call it.
	// - The token's user needs read and edit access to the object.
	rpc SetLockForWOPI( SetLockForWOPIRequest ) returns ( SetLockForWOPIResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Removes the WOPI lock string of the file of a WOPI user session.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it for the WOPI Unlock operation.
	// Applications should not call it.
	// - The token's user needs read and edit access to the object. It does not check the object in.
	rpc RemoveLockForWOPI( RemoveLockForWOPIRequest ) returns ( RemoveLockForWOPIResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Lists the other users who currently have an open co-authoring session on the same file.
	//
	// **For M-Files components only.** M-Files clients call it during co-authoring. Applications should
	// not call it.
	// - Works only with a token of a co-authoring session; others fail with access denied.
	// - Lists the users of the unexpired WOPI user sessions on the same co-authoring link whose
	//   creating M-Files session is still valid, leaving out the user who created the link.
	rpc GetActiveParticipants( GetActiveParticipantsRequest ) returns ( GetActiveParticipantsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Gets the details of a WOPI user session: the shared object and file version, the action, the
	// user and whether editing is allowed.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it to validate each request from
	// Office for the web, and M-Files Web calls it when it opens the editor page. Applications should
	// not call it.
	// - Extends the expiration of the WOPI user session to 30 minutes (the default) from now.
	// - With a container access token (`type` `WOPITOKEN_TYPE_WOPICONTAINER_TOKEN`) and `objid` and
	//   `file_id`, it finds or creates a WOPI user session for that file; creating one checks the object
	//   out to the token's user and fails if the object is checked out to another user or computer.
	rpc GetWOPIUserSession( GetWOPIUserSessionRequest ) returns ( GetWOPIUserSessionResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Gets the name and path of the vault location (container) of a container access token.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it when an Office mobile app
	// browses the vault. Applications should not call it.
	// - Authorized by a container access token from
	//   [CreateContainerAccessToken](mfiles:MFiles.IRPCWOPIOperations.CreateContainerAccessToken). A
	//   container is a view (supported: the "Recently accessed by me" view) or an object that can have
	//   files.
	rpc GetContainerInfo( GetContainerInfoRequest ) returns ( GetContainerInfoResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}

	// Lists the subcontainers and files of the vault location (container) of a container access token.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it when an Office mobile app
	// browses the vault. Applications should not call it.
	// - Authorized by a container access token from
	//   [CreateContainerAccessToken](mfiles:MFiles.IRPCWOPIOperations.CreateContainerAccessToken). The
	//   content is listed with the permissions of the token's user.
	rpc GetContainerContent( GetContainerContentRequest ) returns ( GetContainerContentResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}
}

// The request of GetWOPIUserSessionKey.
message GetWOPIUserSessionKeyRequest {

	// The one-time token from [CreateWOPIUserSession](mfiles:MFiles.IRPCWOPIOperations.CreateWOPIUserSession) with `WOPITOKEN_TYPE_ONE_TIME_TOKEN`.
	string pwszkey = 1;
}

// The response of GetWOPIUserSessionKey.
message GetWOPIUserSessionKeyResponse {

	// The WOPI user session token.
	string wopi_key = 1;
}

// The request of WOPIFileCheckIn.
message WOPIFileCheckInRequest {

	// The WOPI user session token.
	string key = 1;
}

// The response of WOPIFileCheckIn.
message WOPIFileCheckInResponse {
}

// The request of WOPIFileCheckOut.
message WOPIFileCheckOutRequest {

	// The WOPI user session token.
	string key = 1;
}

// The response of WOPIFileCheckOut.
message WOPIFileCheckOutResponse {
}

// The request of EndWOPIUserSession.
message EndWOPIUserSessionRequest {

	// The WOPI user session token.
	string key = 1;
}

// The response of EndWOPIUserSession.
message EndWOPIUserSessionResponse {
}

// The request of WOPIUploadFile.
message WOPIUploadFileRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;

	// 0 to start a new upload, otherwise the ID returned by the first call.
	int32 upload_id = 2;

	// The total size of the file in bytes. Used only when `offset` is 0.
	int64 total_size_in_bytes = 3;

	// The position of `data` in the file. Use multiples of 4096 bytes.
	int64 offset = 4;

	// The block. Use multiples of 4096 bytes, except for the last block.
	bytes data = 5;
}

// The response of WOPIUploadFile.
message WOPIUploadFileResponse {

	// Receives the identifier of this upload operation.
	int32 upload_id = 1;
}

// The request of WOPIUploadFileCommit.
message WOPIUploadFileCommitRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;

	// The ID from [WOPIUploadFile](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIUploadFile).
	int32 upload_id = 2;

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

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

// The response of WOPIUploadFileCommit.
message WOPIUploadFileCommitResponse {
}

// The request of WOPIDownloadFile_Begin.
message WOPIDownloadFile_BeginRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;
}

// The response of WOPIDownloadFile_Begin.
message WOPIDownloadFile_BeginResponse {

	// The download session for `WOPIDownloadFile_ReadBlock`.
	int32 download_id = 1;

	// The size of the file.
	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 WOPIDownloadFile_ReadBlock.
message WOPIDownloadFile_ReadBlockRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;

	// The ID from [WOPIDownloadFile_Begin](mfiles:MFiles.IRPCWOPIOperationsPublic.WOPIDownloadFile_Begin).
	int32 download_id = 2;

	// The number of bytes wanted.
	uint32 block_size = 3;

	// The offset to start reading from.
	int64 offset = 4;
}

// The response of WOPIDownloadFile_ReadBlock.
message WOPIDownloadFile_ReadBlockResponse {

	// Receives the data block.
	bytes data = 1;
}

// The request of GetLockForWOPI.
message GetLockForWOPIRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;
}

// The response of GetLockForWOPI.
message GetLockForWOPIResponse {

	// The current lock string in `lock`; empty when there is no lock.
	WOPILock info = 1;
}

// The request of SetLockForWOPI.
message SetLockForWOPIRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;

	// The lock string that Office for the web sent.
	string lock = 2;
}

// The response of SetLockForWOPI.
message SetLockForWOPIResponse {
}

// The request of RemoveLockForWOPI.
message RemoveLockForWOPIRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;
}

// The response of RemoveLockForWOPI.
message RemoveLockForWOPIResponse {
}

// The request of GetActiveParticipants.
message GetActiveParticipantsRequest {

	// The WOPI user session token.
	string wopi_user_session_key = 1;
}

// The response of GetActiveParticipants.
message GetActiveParticipantsResponse {

	// The user names (`username`) of the participants.
	repeated WOPIActiveUsers wopi_active_users = 1;
}

// The request of GetWOPIUserSession.
message GetWOPIUserSessionRequest {

	// The token, of the kind that `type` names.
	string pwszkey = 1;

	// `WOPITOKEN_TYPE_WOPIVAULT_USER_SESSION_TOKEN` (the default) or `WOPITOKEN_TYPE_WOPICONTAINER_TOKEN`.
	WOPITokenType type = 2;

	// The object; used only with a container access token.
	ObjID objid = 3;

	// The file ID; used only with a container access token.
	int32 file_id = 4;
}

// The response of GetWOPIUserSession.
message GetWOPIUserSessionResponse {

	// The session. `is_edit_allowed` is false when the user's license is read-only, the user lacks edit access, the object is deleted or has no editable files, an older version is shared, or the object is checked out to someone else (except in co-authoring). `is_coauthor` is true for the user who started co-authoring; `is_shared_file` for the other co-authors.
	WOPIUserSession wopi_user_session = 1;
}

// The request of GetContainerInfo.
message GetContainerInfoRequest {

	// The container access token.
	string container_access_token = 1;
}

// The response of GetContainerInfo.
message GetContainerInfoResponse {

	// Receives the container information.
	WOPIContainerInfo wopi_container_info = 1;
}

// The request of GetContainerContent.
message GetContainerContentRequest {

	// The container access token.
	string container_access_token = 1;
}

// The response of GetContainerContent.
message GetContainerContentResponse {

	// Receives the container content.
	WOPIContainerContent wopi_container_content = 1;
}