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

// Runs server-side OCR: converts files to searchable PDF and recognizes text in page areas.
//
// OCR runs on the server as a background operation of the calling session. A job is started,
// polled and ended:
//
// 1. Check that server OCR is available with
//    [GetScanningAndOCROptions](mfiles:MFiles.IRPCScanningAndOCR.GetScanningAndOCROptions)
//    (`allow_server_ocr`, `allowed_file_extensions`).
// 2. Start the job:
//    - on a file you upload:
//      [OCROperation_BeginAfterUpload](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_BeginAfterUpload),
//      or
//    - on a file of a checked-out document in the vault:
//      [OCROperation_Begin](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_Begin).
// 3. Poll [OCROperation_Status](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_Status) until `done`.
// 4. End the job, which also releases it:
//    - [OCROperation_EndWithDownload](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_EndWithDownload)
//      returns the recognized texts and a download of the resulting PDF, or
//    - [OCROperation_End](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_End) replaces the
//      document's file in the vault with the resulting PDF.
//
// The `background_op_id` exists only in the memory of the server that started the job: poll and
// end the job on the same server. After the job has ended, or after
// it failed and the failure was reported, the ID is no longer valid and calls fail with "The
// parameter is incorrect.".
//
// **Operation types** ([OCROperationType](mfiles:MFiles.OCROperationType)):
// `..._CONVERT_TO_SEARCHABLE_PDF` and `..._CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` (PDF/A-1b) produce a
// PDF; `..._RECOGNIZE_SPECIFIC_BLOCKS` reads the text of the areas given in `pages`; `..._RECOGNIZE_ANY_BLOCKS` returns the text areas it
// finds; the combined types do both.
//
// All methods need a vault session. Files are covered in
// [Files](https://developer.m-files.com/APIs/gRPC-API/runtime/files/).
service IRPCScanningAndOCR {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Scanning and OCR" };

	// Gets the progress of an OCR job, and optionally cancels it.
	//
	// - Poll until `done` is true, then end the job.
	// - If the job failed, the call fails with the job's error and the job is released.
	// - An unknown or already ended job fails with "The parameter is incorrect.".
	rpc OCROperation_Status( OCROperation_StatusRequest ) returns ( OCROperation_StatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets whether scanning and client- and server-side OCR are enabled for the vault, and for
	// which file types.
	//
	// - Requires a vault session; no special vault rights.
	// - `allow_server_ocr` is true only when server OCR is enabled in the vault settings, the license
	//   includes OCR and the OCR engine could be started; otherwise the Begin methods fail with "OCR
	//   feature is disabled by license or settings.". `ocr_setup_error_code` is non-zero when the
	//   engine could not be started.
	// - `allowed_file_extensions` defaults to TIF, TIFF, JPG, JPEG and PDF.
	rpc GetScanningAndOCROptions( GetScanningAndOCROptionsRequest ) returns ( GetScanningAndOCROptionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Starts an OCR job on a file that the caller uploaded with UploadTempFile.
	//
	// - Upload the file with [UploadTempFile](mfiles:MFiles.IRPCObjectOperations.UploadTempFile) and
	//   pass its `upload_id` and size here. **Do not commit the upload** with
	//   [UploadTempFileCommit](mfiles:MFiles.IRPCObjectOperations.UploadTempFileCommit): this call
	//   commits it itself, and an upload that is already committed fails with "File size mismatch.".
	// - The upload is consumed, also when the call fails.
	// - Fails with "OCR feature is disabled by license or settings." when server OCR is not
	//   available.
	// - Returns at once; poll [OCROperation_Status](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_Status)
	//   and finish with
	//   [OCROperation_EndWithDownload](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_EndWithDownload).
	rpc OCROperation_BeginAfterUpload( OCROperation_BeginAfterUploadRequest ) returns ( OCROperation_BeginAfterUploadResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Starts an OCR job on a file of a document that the caller has checked out.
	//
	// - The document must be checked out to the caller, and the caller needs read and edit access to
	//   it. The initial checked-out version of a new document (version 1) is rejected: it has no
	//   checked-in version.
	// - Nothing is uploaded: the content is read from the file in the latest checked-in version of
	//   the document.
	// - Finish with [OCROperation_End](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_End) to replace
	//   the file in the checked-out version with the PDF, then check the document in.
	rpc OCROperation_Begin( OCROperation_BeginRequest ) returns ( OCROperation_BeginResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Ends an OCR job started with OCROperation_Begin and replaces the document's file with the
	// resulting PDF.
	//
	// - Only for jobs started with
	//   [OCROperation_Begin](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_Begin); other jobs fail
	//   with "OCR processing has not been started.".
	// - For the types that produce a PDF, the file in the checked-out version is replaced with the
	//   PDF and its extension changes to `pdf`. Check the document in to save the change.
	// - The job is released; the ID cannot be used again. If the job failed, the call fails with the
	//   job's error.
	rpc OCROperation_End( OCROperation_EndRequest ) returns ( OCROperation_EndResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Ends an OCR job and returns its results: the recognized texts and a download of the PDF.
	//
	// - Call after [OCROperation_Status](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_Status)
	//   reports `done`. The job is released; the ID cannot be used again.
	// - For the types that produce a PDF, read the file with
	//   [DownloadFile_ReadBlock](mfiles:MFiles.IRPCObjectOperations.DownloadFile_ReadBlock) using
	//   `download_session`, and release the download with
	//   [DownloadFile_Stop](mfiles:MFiles.IRPCObjectOperations.DownloadFile_Stop). For the
	//   recognize-only types `download_file_size` is 0.
	// - If the job failed, the call fails with the job's error.
	rpc OCROperation_EndWithDownload( OCROperation_EndWithDownloadRequest ) returns ( OCROperation_EndWithDownloadResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Starts an OCR job that converts the file of a stateless upload to a searchable PDF.
	//
	// - Not available on current servers: the call fails with "Not implemented.". Use
	//   [OCROperation_BeginAfterUpload](mfiles:MFiles.IRPCScanningAndOCR.OCROperation_BeginAfterUpload)
	//   instead.
	// - Takes the `file_ref` of an upload ended with
	//   [FileUploadEnd](mfiles:MFiles.IRPCFileTransfer.FileUploadEnd). Only
	//   `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` and
	//   `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF` are accepted.
	// - Follow the job with
	//   [GetOCRUploadedFileStatus](mfiles:MFiles.IRPCScanningAndOCR.GetOCRUploadedFileStatus).
	rpc OCRUploadedFile( OCRUploadedFileRequest ) returns ( OCRUploadedFileResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the state of an OCR job started with OCRUploadedFile and, when it has completed, its
	// result as a `file_ref`. Optionally requests the cancellation of the job.
	//
	// - Not available on current servers: the call fails with "Not implemented.".
	// - The job belongs to the login session that started it; other sessions get "The OCR job was not
	//   found in this session.". Once a completed, failed or canceled state has been returned, the
	//   job is released.
	rpc GetOCRUploadedFileStatus( GetOCRUploadedFileStatusRequest ) returns ( GetOCRUploadedFileStatusResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of OCROperation_Status.
message OCROperation_StatusRequest {

	// The ID of the job.
	uint32 background_op_id = 1;

	// True to cancel the job.
	bool cancel = 2;
}

// The response of OCROperation_Status.
message OCROperation_StatusResponse {

	// The number of pages to process; 0 until known.
	uint32 items = 1;

	// The number of pages processed.
	uint32 items_completed = 2;

	// True when the job has stopped.
	bool done = 3;
}

// The request of GetScanningAndOCROptions.
message GetScanningAndOCROptionsRequest {
}

// The response of GetScanningAndOCROptions.
message GetScanningAndOCROptionsResponse {

	// The scanning and OCR options of the vault. See [ScanningAndOCROptions](mfiles:MFiles.ScanningAndOCROptions).
	ScanningAndOCROptions putf8szscanocrops = 1;
}

// The request of OCROperation_BeginAfterUpload.
message OCROperation_BeginAfterUploadRequest {

	// What to produce. See the service overview.
	OCROperationType type = 1;

	// Recognition languages and automatic language detection. Unset uses the defaults.
	OCROptions options = 2;

	// The `upload_id` of an uploaded, not committed file.
	int32 upload_session = 3;

	// The size of the uploaded file in bytes; must match the uploaded bytes.
	int64 upload_file_size = 4;

	// The file name extension of the uploaded file, without the dot, for example `pdf` or `tif`.
	string source_file_extension = 5;

	// For `..._RECOGNIZE_SPECIFIC_BLOCKS` types, the areas to recognize, per page. Otherwise leave unset.
	OCRPageArray pages = 6;
}

// The response of OCROperation_BeginAfterUpload.
message OCROperation_BeginAfterUploadResponse {

	// The ID of the job.
	uint32 background_op_id = 1;
}

// The request of OCROperation_Begin.
message OCROperation_BeginRequest {

	// What to produce. See the service overview.
	OCROperationType type = 1;

	// Recognition languages and automatic language detection. Unset uses the defaults.
	OCROptions options = 2;

	// The checked-out version (`obj_ver`) and the file (`file_ver`) to process.
	ObjOrFileVer obj_or_file_ver = 3;

	// The file name extension, without the dot.
	string source_file_extension = 4;

	// For `..._RECOGNIZE_SPECIFIC_BLOCKS` types, the areas to recognize. Otherwise unset.
	OCRPageArray pages = 5;
}

// The response of OCROperation_Begin.
message OCROperation_BeginResponse {

	// The ID of the job.
	uint32 background_op_id = 1;
}

// The request of OCROperation_End.
message OCROperation_EndRequest {

	// The ID of the job.
	uint32 background_op_id = 1;
}

// The response of OCROperation_End.
message OCROperation_EndResponse {

	// The recognized areas and their texts, per page. Empty if the type did not recognize areas.
	repeated OCRPageResult page_results = 1;
}

// The request of OCROperation_EndWithDownload.
message OCROperation_EndWithDownloadRequest {

	// The ID of the job.
	uint32 background_op_id = 1;
}

// The response of OCROperation_EndWithDownload.
message OCROperation_EndWithDownloadResponse {

	// The recognized areas and their texts, per page. Empty for the types that only produce a PDF.
	repeated OCRPageResult page_results = 1;

	// The download ID of the resulting PDF.
	int32 download_session = 2;

	// The size of the resulting PDF in bytes; 0 if none.
	int64 download_file_size = 3;
}

// The request of OCRUploadedFile.
message OCRUploadedFileRequest {

	// The file_ref of a stateless upload ended with FileUploadEnd, to be used as input for the OCR job.
	string file_ref = 1;

	// The filename extension (without dot) of the source file. Required, as a file_ref has no file name.
	string source_file_extension = 2;

	// `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_PDF` or `OCROPERATION_TYPE_CONVERT_TO_SEARCHABLE_ARCHIVE_PDF`; other types fail.
	OCROperationType type = 3;

	// OCR options to be used for this job. If unset, default settings are used.
	OCROptions options = 4;
}

// The response of OCRUploadedFile.
message OCRUploadedFileResponse {

	// The ID of the job, for [GetOCRUploadedFileStatus](mfiles:MFiles.IRPCScanningAndOCR.GetOCRUploadedFileStatus).
	string job_id = 1;
}

// The request of GetOCRUploadedFileStatus.
message GetOCRUploadedFileStatusRequest {

	// The ID of the job from [OCRUploadedFile](mfiles:MFiles.IRPCScanningAndOCR.OCRUploadedFile).
	string job_id = 1;

	// True to request the cancellation of the job. The returned state can still be queued or running until the job has stopped.
	bool cancel = 2;
}

// The response of GetOCRUploadedFileStatus.
message GetOCRUploadedFileStatusResponse {

	// The state of the job.
	OCRUploadedFileState state = 1;

	// The number of pages to process. Zero if not known yet.
	uint32 pages_total = 2;

	// The number of pages processed.
	uint32 pages_completed = 3;

	// If the state is completed, the file_ref of the searchable PDF, as a stateless upload that can be attached like an upload ended with FileUploadEnd. Otherwise empty.
	string result_file_ref = 4;

	// If the state is completed, the size of the searchable PDF in bytes. Otherwise zero.
	int64 result_file_size = 5;

	// If the state is failed, the M-Files error code of the job; otherwise 0.
	int32 error_code = 6;

	// If the state is failed, the error message of the job. Otherwise empty.
	string error_message = 7;
}