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

// Gets thumbnail images of document files and the vault's thumbnail settings.
//
// Provides methods for getting thumbnail-spefific information and operations.
//
// Use [GetDocumentFileThumbnail](mfiles:MFiles.IRPCThumbnails.GetDocumentFileThumbnail) to show
// a small picture of a file in a listing or a larger preview of its first page. All images are
// PNG.
//
// - **Classic thumbnails** (`THUMBNAIL_TYPE_CLASSIC`) are square images that the server generates
//   once per file version with the file type handlers installed on the server, and then caches.
//   Whether one exists is reported in `thumbnail_status`; not every file type has one.
// - **Preview thumbnails** (`THUMBNAIL_TYPE_PREVIEW`) show the first page of the file in its own
//   aspect ratio, scaled to fit the size you ask for. When no preview can be made, the server
//   returns the file type's icon instead.
// - [GetThumbnailOptions](mfiles:MFiles.IRPCThumbnails.GetThumbnailOptions) tells whether
//   thumbnails are enabled in the vault and which file types are excluded. M-Files desktop
//   clients use it to decide whether to create classic thumbnails themselves.
//
// Both methods need a vault session and no special vault rights. To identify a file, take the
// `file_ver` of a [File](mfiles:MFiles.File) from the object version, for example from
// [GetObjectFiles](mfiles:MFiles.IRPCObjectOperations.GetObjectFiles) or from the `files` of a
// search result.
service IRPCThumbnails {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Thumbnails" };

	// Gets the vault's thumbnail settings.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - `is_thumbnail_feature_on` false means that the server returns no classic thumbnails
	//   (`THUMBNAIL_STATUS_DO_NOT_GENERATE`) and clients should not create them either.
	// - `size` is the size of the classic thumbnails that the server generates, 256 x 256 pixels by
	//   default.
	// - `denied_file_extensions` lists the file extensions (without the dot) for which thumbnails
	//   must not be generated.
	rpc GetThumbnailOptions( GetThumbnailOptionsRequest ) returns ( GetThumbnailOptionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets a classic thumbnail or a first-page preview of one file of an object version, as PNG.
	//
	// - Requires a vault session.
	// - **Classic** (`THUMBNAIL_TYPE_CLASSIC` or `THUMBNAIL_TYPE_CLASSIC_NO_ICON`; the server treats
	//   them the same): identify the file with a specific file version (`FILE_VER_TYPE_SPECIFIC`). The
	//   server generates the thumbnail on first request and caches it. Check `thumbnail_status`:
	//   - `THUMBNAIL_STATUS_GENERATED`: `thumbnail` holds the PNG.
	//   - `THUMBNAIL_STATUS_CANNOT_GENERATE`: the server has no thumbnail handler for the file type.
	//   - `THUMBNAIL_STATUS_FAILED_TO_GENERATE`, `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE`:
	//     generation failed, or the file's data is missing.
	//   - `THUMBNAIL_STATUS_DO_NOT_GENERATE`: thumbnails are turned off, or the file type is excluded
	//     (see [GetThumbnailOptions](mfiles:MFiles.IRPCThumbnails.GetThumbnailOptions)).
	//   - `THUMBNAIL_STATUS_NOT_GENERATED`: no thumbnail yet.
	//
	//   In every case other than `THUMBNAIL_STATUS_GENERATED`, `thumbnail` is empty: show an icon or
	//   ask for a preview instead.
	// - **Preview** (`THUMBNAIL_TYPE_PREVIEW`): `obj_ver` must name a specific version
	//   (`OBJ_VER_VERSION_TYPE_SPECIFIC`); a latest-version reference fails. The file must belong to
	//   that version. The server renders the first page and scales it to fit within `max_width` x
	//   `max_height`, keeping the aspect ratio; images are at most 999 pixels on the longer side.
	//   The response has `thumbnail_type` `THUMBNAIL_TYPE_PREVIEW`. If no preview can be made, the
	//   response holds the file type's icon instead, with `thumbnail_type` `THUMBNAIL_TYPE_CLASSIC`;
	//   `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED` in both cases.
	// - The first preview of a file can take a while, because the server first makes a PDF version
	//   of the file. Later calls reuse it.
	// - Previews work only for files stored in the vault; for files of external repositories the
	//   call fails with "Not implemented.".
	rpc GetDocumentFileThumbnail( GetDocumentFileThumbnailRequest ) returns ( GetDocumentFileThumbnailResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetThumbnailOptions.
message GetThumbnailOptionsRequest {
}

// The response of GetThumbnailOptions.
message GetThumbnailOptionsResponse {

	// The thumbnail settings of the vault. See [ThumbnailOptions](mfiles:MFiles.ThumbnailOptions).
	ThumbnailOptions pthumbops = 1;
}

// The request of GetDocumentFileThumbnail.
message GetDocumentFileThumbnailRequest {

	// The object version that has the file. For a preview, a specific version.
	ObjVer obj_ver = 1;

	// The file and its specific version, as in the [File](mfiles:MFiles.File) entries of the object version.
	FileVer file_ver = 2;

	// `THUMBNAIL_TYPE_CLASSIC` (default) for the cached square thumbnail, or `THUMBNAIL_TYPE_PREVIEW` for a first-page preview.
	ThumbnailType type = 3;

	// For a preview, the largest width in pixels. Ignored for classic thumbnails.
	uint32 max_width = 4;

	// For a preview, the largest height in pixels. Ignored for classic thumbnails. With both `max_width` and `max_height` 0, the server uses a default size.
	uint32 max_height = 5;
}

// The response of GetDocumentFileThumbnail.
message GetDocumentFileThumbnailResponse {

	// Whether a thumbnail was returned: `THUMBNAIL_STATUS_GENERATED` means `thumbnail` has data. See the remarks for the other values.
	ThumbnailStatus thumbnail_status = 1;

	// The kind of image returned: `THUMBNAIL_TYPE_PREVIEW` for a page preview, `THUMBNAIL_TYPE_CLASSIC` for a classic thumbnail or a file type icon.
	ThumbnailType thumbnail_type = 3;

	// The image as PNG bytes. Empty unless `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED`.
	bytes thumbnail = 2;
}