// 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 "google/protobuf/timestamp.proto";
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_";

// Reads objects, value list items and property value history in bulk, in batches ordered by ID,
// for exporting vault data to another system.
//
// The methods are built for bulk reading with stable paging: each batch continues after the last
// ID the caller received. M-Files Reporting uses them to fill reporting databases (see
// [IRPCExportedDataSets](mfiles:MFiles.IRPCExportedDataSets)), but they work for any session and
// always apply the caller's permissions.
//
// A typical export of one object type:
//
// 1. Page through the objects with
//    [SearchExportedObjects](mfiles:MFiles.IRPCDataExport.SearchExportedObjects): conditions that
//    select one object type, `last_received_obj_id` 0 first, then the ID of the last object
//    received, until a batch comes back empty.
// 2. Read the properties of each batch with
//    [GetExportedObjectProperties](mfiles:MFiles.IRPCDataExport.GetExportedObjectProperties).
// 3. Optionally read how a property changed over time with
//    [GetPropertyValueHistory](mfiles:MFiles.IRPCDataExport.GetPropertyValueHistory).
// 4. Page through the value lists that the properties refer to with
//    [GetExportedValueListItems](mfiles:MFiles.IRPCDataExport.GetExportedValueListItems), or fetch
//    single items with
//    [GetExportedValueListItemsByID](mfiles:MFiles.IRPCDataExport.GetExportedValueListItemsByID).
//
// All methods need a vault session and no special vault rights; objects, values and items the
// user cannot see are left out. For interactive searches use
// [SearchObjects](mfiles:MFiles.IRPCSearch.SearchObjects) instead.
service IRPCDataExport {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Data export" };

	// Searches objects in batches ordered by object ID, for paging through all objects that match.
	//
	// - Returns the latest checked-in version of each matching object, ordered by object ID. Objects
	//   that have only an initial checked-out version are not returned.
	// - The server adds the condition "object ID greater than `last_received_obj_id`" to your
	//   conditions. Paging is by object ID only, and IDs repeat across object types, so **include a
	//   condition on one object type** (`STATUS_TYPE_OBJECT_TYPE`) when you page; without it, objects
	//   of other types with smaller IDs are skipped or repeated.
	// - Stop when a batch is empty. Results are not ranked by relevance.
	rpc SearchExportedObjects( SearchExportedObjectsRequest ) returns ( SearchExportedObjectsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the items of a value list in batches ordered by item ID.
	//
	// - Returns items whose ID is greater than `last_received_item_id`, ascending by ID. Deleted items
	//   are left out. Parents of matching items are not added.
	// - Works for value lists and object types. An unknown list fails with "Not found.".
	// - Stop when a batch is empty.
	rpc GetExportedValueListItems( GetExportedValueListItemsRequest ) returns ( GetExportedValueListItemsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the given items of a value list.
	//
	// - IDs that do not exist, and items the user cannot see, are left out of the response, so it
	//   can be shorter than `ids`.
	rpc GetExportedValueListItemsByID( GetExportedValueListItemsByIDRequest ) returns ( GetExportedValueListItemsByIDResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the version information and property values of many objects in one call.
	//
	// - The response has one entry per requested object, in request order, in both
	//   `object_version_ex` and `prop_val_arrays`.
	// - A version with `OBJ_VER_VERSION_TYPE_LATEST` reads the latest checked-in version.
	// - An object that does not exist, has no checked-in version, or that the user cannot see gets
	//   an empty entry. For a destroyed object, only `object_version_ex.object_info.obj_id` is set,
	//   so you can tell it apart from a hidden one; if Name or title (0) was requested its last name
	//   is returned too.
	// - Each object may appear only once: a repeated object fails the call with "Already exists.".
	rpc GetExportedObjectProperties( GetExportedObjectPropertiesRequest ) returns ( GetExportedObjectPropertiesResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets how one property of each given object changed over the object's versions.
	//
	// - The history of an object is a list of samples, oldest first. A new sample starts only when
	//   the value changes, so unchanged versions do not repeat it. When the property was removed from
	//   a version, the sample has an unset value.
	// - Each sample's `timestamp` is the Last modified (21) value of the version where the value
	//   appeared.
	// - With `from` set, older samples are dropped, except the last one at or before `from`, so the
	//   value in effect at `from` is known. Unset `from` returns the full history.
	// - The response has one entry per requested object, in request order; objects the user cannot
	//   see get an empty history. Each object may appear only once ("Already exists." otherwise).
	rpc GetPropertyValueHistory( GetPropertyValueHistoryRequest ) returns ( GetPropertyValueHistoryResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of SearchExportedObjects.
message SearchExportedObjectsRequest {

	// Search conditions, combined with AND. See [SearchCondition](mfiles:MFiles.SearchCondition) and [Search](https://developer.m-files.com/APIs/gRPC-API/concepts/search/).
	repeated SearchCondition condition_array = 1;

	// The ID of the last object received in the previous batch; 0 for the first batch.
	uint32 last_received_obj_id = 2;

	// The maximum number of objects to return; 0 returns all matching objects.
	uint32 batch_size = 3;
}

// The response of SearchExportedObjects.
message SearchExportedObjectsResponse {

	// The matching objects as [ObjVer](mfiles:MFiles.ObjVer)s with a specific version (the latest checked-in version), in ascending object ID order.
	repeated ObjVer pexportedobjects = 1;
}

// The request of GetExportedValueListItems.
message GetExportedValueListItemsRequest {

	// The ID of the value list or object type.
	int32 value_list = 1;

	// The ID of the last item received in the previous batch; 0 for the first batch.
	uint32 last_received_item_id = 2;

	// The maximum number of items to return; 0 returns all.
	uint32 batch_size = 3;
}

// The response of GetExportedValueListItems.
message GetExportedValueListItemsResponse {

	// The items. See [ValueListItem](mfiles:MFiles.ValueListItem).
	repeated ValueListItem pexportedvlitems = 1;
}

// The request of GetExportedValueListItemsByID.
message GetExportedValueListItemsByIDRequest {

	// The ID of the value list or object type.
	int32 value_list = 1;

	// The IDs of the items to get.
	repeated int32 ids = 2;
}

// The response of GetExportedValueListItemsByID.
message GetExportedValueListItemsByIDResponse {

	// The items found. See [ValueListItem](mfiles:MFiles.ValueListItem).
	repeated ValueListItem pexportedvlitems = 1;
}

// The request of GetExportedObjectProperties.
message GetExportedObjectPropertiesRequest {

	// The objects to read. Each object at most once.
	repeated ObjVer exportedobjects = 1;

	// The IDs of the property definitions to return. Empty returns all properties.
	repeated int32 property_defs = 2;
}

// The response of GetExportedObjectProperties.
message GetExportedObjectPropertiesResponse {

	// The version information of each object, in request order. Empty for objects that were not found or not visible.
	repeated ObjectVersionEx object_version_ex = 1;

	// The property values of each object, in request order.
	repeated PropertyValueArray prop_val_arrays = 2;
}

// The request of GetPropertyValueHistory.
message GetPropertyValueHistoryRequest {

	// The ID of the property definition whose history is wanted.
	int32 property_def = 1;

	// The objects. Each object at most once.
	repeated ObjID obj_ids = 2;

	// The oldest point in time of interest; unset for the full history.
	google.protobuf.Timestamp from = 3;
}

// The response of GetPropertyValueHistory.
message GetPropertyValueHistoryResponse {

	// One history per requested object, in request order. See [HistoricalTypedValue](mfiles:MFiles.HistoricalTypedValue).
	repeated HistoricalTypedValueArray historical_typed_value_arrays = 1;
}