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

// Creates the access tokens with which Office for the web (WOPI) opens vault files, and returns the
// Office for the web actions that the vault can use.
//
// **For M-Files components only.** M-Files clients call this service with the user's own vault
// session to hand a file over to Office for the web. Applications should not call it.
//
// - **Callers:** M-Files Web and M-Files Desktop call
//   [CreateWOPIUserSession](mfiles:MFiles.IRPCWOPIOperations.CreateWOPIUserSession) when the user
//   opens a file in Office for the web or starts co-authoring, and
//   [GetWOPIDiscoveryData](mfiles:MFiles.IRPCWOPIOperations.GetWOPIDiscoveryData) to learn which
//   file types and actions are available. The M-Files WOPI service (the WOPI host that Office for
//   the web talks to) calls
//   [CreateContainerAccessToken](mfiles:MFiles.IRPCWOPIOperations.CreateContainerAccessToken) for
//   the Office mobile apps.
// - **Tokens:** a token is a Base64 string that holds the vault GUID and 64 random bytes. The server
//   stores it with the session ID of the caller, and the anonymous methods of
//   [IRPCWOPIOperationsPublic](mfiles:MFiles.IRPCWOPIOperationsPublic) act in that session. A token
//   therefore stops working when the session that created it ends, even before the token itself
//   expires.
// - **Session and rights:** a vault session; no special vault rights. Access to the object is
//   checked when the token is created and again on every file operation made with it.
// - On a server where the WOPI service is turned off, `CreateWOPIUserSession` fails with "Not
//   implemented." (0x80004001) and `GetWOPIDiscoveryData` returns an empty list.
service IRPCWOPIOperations {
	option (mfiles.api.service) = { book: "integration" level: LEVEL_SPECIALIZED title: "WOPI operations" };

	// Creates a WOPI user session for one file version and returns its token (or a one-time token that
	// can be exchanged for it).
	//
	// **For M-Files components only.** M-Files Web and M-Files Desktop call it before they open a file
	// in Office for the web. Applications should not call it.
	// - Requires a vault session. The caller needs read access to the object; for co-authoring of a
	//   checked-out object, also edit access.
	// - Creates an internal shared link for the file (`SHARED_LINK_TYPE_WOPIREADONLY`,
	//   `SHARED_LINK_TYPE_WOPIEDIT` or `SHARED_LINK_TYPE_CO_AUTHORING` by `action_type`; co-authoring
	//   reuses an existing co-authoring link) and a WOPI user session that refers to it.
	// - The WOPI user session expires 30 minutes after it was created or last used (the default; the
	//   server administrator can change it). A one-time token expires after 5 minutes and can be
	//   exchanged only once, with
	//   [GetWOPIUserSessionKey](mfiles:MFiles.IRPCWOPIOperationsPublic.GetWOPIUserSessionKey).
	// - For `WOPIACTION_TYPE_VIEW` of a checked-out object, the latest checked-in version is shared; an
	//   object that has never been checked in fails with access denied.
	rpc CreateWOPIUserSession( CreateWOPIUserSessionRequest ) returns ( CreateWOPIUserSessionResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}

	// Creates, or returns the existing, container access token with which the Office mobile apps
	// browse a vault location through the M-Files WOPI service.
	//
	// **For M-Files components only.** The M-Files WOPI service calls it after it has logged in for an
	// Office mobile app user. Applications should not call it.
	// - Requires a vault session. If the same session already has an unexpired token for the same
	//   path, that token is returned.
	// - The token expires 24 hours after it was created (the default; the server administrator can
	//   change it). Use it with
	//   [GetContainerInfo](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerInfo) and
	//   [GetContainerContent](mfiles:MFiles.IRPCWOPIOperationsPublic.GetContainerContent).
	rpc CreateContainerAccessToken( CreateContainerAccessTokenRequest ) returns ( CreateContainerAccessTokenResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}

	// Gets the Office for the web actions (action name and URL) that the vault's WOPI configuration
	// provides.
	//
	// **For M-Files components only.** M-Files Web and M-Files Desktop call it to decide which files
	// can be opened in Office for the web. Applications should not call it.
	// - Requires a vault session. Read-only; the server serves the data from a cache that it fills
	//   from the Office for the web discovery URL configured for the vault.
	// - Fails with "Not found. (Either WOPI is not enabled or the discovery URL is empty.)" when the
	//   vault has no WOPI configuration.
	// - Returns an empty list on a server where the WOPI service is turned off.
	rpc GetWOPIDiscoveryData( GetWOPIDiscoveryDataRequest ) returns ( GetWOPIDiscoveryDataResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION internal: true };
	}
}

// The request of CreateWOPIUserSession.
message CreateWOPIUserSessionRequest {

	// The file to open: `obj_ver`, `file_ver`, `action_type`, `user_account_id` (the session's own user ID), `external_username` (usually empty) and `additional_data` (the URLs and culture that the WOPI host passes on to Office for the web; the URLs are validated). The other fields are ignored.
	WOPIUserSession wopi_user_session = 1;

	// `WOPITOKEN_TYPE_WOPIVAULT_USER_SESSION_TOKEN` (the default) returns the session token itself; `WOPITOKEN_TYPE_ONE_TIME_TOKEN` returns a one-time token, for passing in a URL. `WOPITOKEN_TYPE_WOPICONTAINER_TOKEN` is rejected.
	WOPITokenType type = 2;
}

// The response of CreateWOPIUserSession.
message CreateWOPIUserSessionResponse {

	// The token of the requested type.
	string wopi_key = 1;
}

// The request of CreateContainerAccessToken.
message CreateContainerAccessTokenRequest {

	// The container path as the M-Files WOPI service forms it (at most 250 characters).
	string container_path = 1;
}

// The response of CreateContainerAccessToken.
message CreateContainerAccessTokenResponse {

	// The token, the session's user ID, user name and email address, and the expiration time (UTC).
	WOPIContainerTokenInfo wopi_container_token_info = 1;
}

// A structure that specifies get WOPI discovery data request.
message GetWOPIDiscoveryDataRequest {
}

// Struct for WOPI discovery data response.
message GetWOPIDiscoveryDataResponse {

	// One entry per action: `action_name` and the `action_url` template from the discovery data.
	repeated WOPIDiscovery values = 1;
}