IRPCObjectOperations.DownloadFile_Begin

Vault API / core read session or assertion idempotent returns metadata structure version

Opens a download session for a file version and returns its ID, the content size and, on request, its MD5 checksum.

Service	Objects, versions, properties and files `MFiles.IRPCObjectOperations`
gRPC method	`/MFiles.IRPCObjectOperations/DownloadFile_Begin`
HTTP (mf-http-grpc)	`POST /grpc/v1/download-file_-begin`
Request	`DownloadFile_BeginRequest`
Response	`DownloadFile_BeginResponse`
Book and level	Vault API, core
Kind	read
Session	Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
Idempotent	yes
Returns metadata structure version	yes (in the mfiles-metadata-version-bin trailer)
Streaming	none (unary)

Remarks

Downloading a file takes three calls:

DownloadFile_Begin with the file's obj_file_ver and prepare_file_for_downloading true.
DownloadFile_ReadBlock with the returned download_id, from offset 0, until a block shorter than requested comes back. Blocks are at most 4 MiB.
DownloadFile_Stop. When the whole file was read in order from the start, the server has already closed the session; the call still succeeds, so always make it.

Take obj_file_ver.file_ver from the version information of the object (File file_ver). It must be a specific file version: FILE_VER_TYPE_LATEST fails with "Not found. (File <id>-0 not found.)".

Formats. FILE_FORMAT_NATIVE downloads the file as stored. FILE_FORMAT_PDF and FILE_FORMAT_DISPLAY_ONLY_PDF download a PDF rendition that the server creates if needed (for example from Office files); file_outline.size is then the size of the PDF. FILE_FORMAT_PLAIN_TEXT and FILE_FORMAT_MARKDOWN are not supported here ("The requested file format ... is not supported."); use GetTextContentForFileWithFormat.

Checksum. file_outline.md5_checksum is filled only when need_checksum is true; otherwise it is 32 zeros. For the PDF formats the server currently returns the checksum of the native file, not of the PDF, so do not verify a PDF download against it.

Session. A download session belongs to the login session that opened it, on the server that opened it. An unused session is closed after about 10 minutes (server default).

Request: DownloadFile_BeginRequest

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Field	Type	Description
`obj_file_ver`	`ObjFileVer`	The object and the specific file version, as in `File.file_ver`.
`obj_file_ver.obj_id`	`ObjID`	The object that owns the file.
`obj_file_ver.obj_id.type`	`int32`	The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID).
`obj_file_ver.obj_id.item_id`	`ItemID`	The ID of the object within its type, in `item_id.internal_id`.
`obj_file_ver.file_ver`	`FileVer`	The specific file version, as in `File.file_ver`.
`obj_file_ver.file_ver.file_id`	`FileID`	The file.
`obj_file_ver.file_ver.type`	`FileVerType`	`FILE_VER_TYPE_SPECIFIC` for a file version number.Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3).
`obj_file_ver.file_ver.internal_version`	`int32`	The file version number.
`obj_file_ver.file_ver.external_repository_version`	`string`	Used only for files in external repositories. Leave empty.
`obj_file_ver.file_ver.external_repository_sort_key`	`int64`	Used only for files in external repositories. Leave 0.
`format`	`FileFormat`	`FILE_FORMAT_NATIVE` (default), `FILE_FORMAT_PDF` or `FILE_FORMAT_DISPLAY_ONLY_PDF`.Values: `FILE_FORMAT_NATIVE` (0), `FILE_FORMAT_PDF` (1), `FILE_FORMAT_DISPLAY_ONLY_PDF` (2), `FILE_FORMAT_PLAIN_TEXT` (3), `FILE_FORMAT_MARKDOWN` (4).
`prepare_file_for_downloading`	`bool`	Must be true to download. False only checks the caller's access and records the file as accessed; `download_id` is then 0.
`need_checksum`	`bool`	True to get the MD5 checksum of the native file in `file_outline.md5_checksum`.

Response: DownloadFile_BeginResponse

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Field	Type	Description
`download_id`	`int32`	The download session for `DownloadFile_ReadBlock` and `DownloadFile_Stop`. 0 if `prepare_file_for_downloading` was false.
`file_outline`	`FileOutline`	The size of the content to download, in the requested format, and the checksum if requested.
`file_outline.size`	`int64`	The size of the content in bytes, in the downloaded format.
`file_outline.size_precision`	`FileSizePrecision`	The file size precision. If the file size precision is 'exact', the size can be used for reading the file content. If the precision is 'unknown', the size field should not be used at all.Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2).
`file_outline.md5_checksum`	`string`	The MD5 checksum as 32 hexadecimal digits, if requested; 32 zeros otherwise.
`ov_ex`	`ObjectVersionEx`	The version information of the object that owns the file.
`ov_ex.version_info`	`ObjectVersion`	Object Version information.
`ov_ex.version_info.version`	`ObjVerVersion`	The version number, as a specific version.
`ov_ex.version_info.display_version`	`string`	The version label to show, if it differs from the version number; empty otherwise.
`ov_ex.version_info.title`	`string`	The title (name) of the object in this version.
`ov_ex.version_info.is_single_file_object`	`bool`	True if the object is a single-file document, which has exactly one file.
`ov_ex.version_info.has_relationships_from_this`	`bool`	Note: this field is deprecated. True if relationships from this object version to one or more documents exist.
`ov_ex.version_info.has_relationships_to_this`	`bool`	Note: this field is deprecated. True if relationships from one or more documents to this object version exist.
`ov_ex.version_info.has_assignments`	`bool`	True if relationships from one or more assignments to this object version exist.
`ov_ex.version_info.last_modified_at_utc`	`google.protobuf.Timestamp`	When the version was last modified, in UTC.
`ov_ex.version_info.files[]`	repeated `File`	The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`.
`ov_ex.version_info.object_version_flags`	`OBJVERFLAGS`	Bit flags that provide additional information on the object version.
`ov_ex.version_info.class_id`	`int32`	The class ID of the version.
`ov_ex.version_info.version_guid`	`string`	The GUID of this version.
`ov_ex.version_info.base_properties[]`	repeated `PropertyValue`	Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`.
`ov_ex.version_info.primary_file`	`FileID`	File ID of the primary file of a multi-file object, if the object is a multi-file object.
`ov_ex.object_info`	`ObjectLevelInfo`	Object-level information.
`ov_ex.object_info.obj_id`	`ObjID`	The object type and ID of the object.
`ov_ex.object_info.external_id_status`	`ExtIDStatus`	The status of this object's external ID.Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5).
`ov_ex.object_info.external_id`	`string`	The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID.
`ov_ex.object_info.checked_out_version`	`ObjVerVersion`	The version that is checked out. Version number 0 if the object is not checked out.
`ov_ex.object_info.checked_out_to_user_id`	`int32`	The ID of the user who has the object checked out.
`ov_ex.object_info.checked_out_to_user_name`	`string`	The user name of the user who has the object checked out.
`ov_ex.object_info.checked_out_to_host_name`	`string`	The host name of the computer to which the object was checked out.
`ov_ex.object_info.checked_out_at_utc`	`google.protobuf.Timestamp`	The timestamp of the moment the object was checked out.
`ov_ex.object_info.checked_in_version`	`ObjVerVersion`	The latest checked-in version.
`ov_ex.object_info.created_at_utc`	`google.protobuf.Timestamp`	The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue).
`ov_ex.object_info.accessed_by_me_utc`	`google.protobuf.Timestamp`	Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back.
`ov_ex.object_info.guid`	`string`	The object GUID, in braces. The same value as `GetObjectGUID` returns.
`ov_ex.object_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the object (e.g. is the object deleted or a stub).
`ov_ex.object_info.original_vault_guid`	`string`	The GUID of the vault in which the object was originally created.
`ov_ex.object_info.original_vault_obj_id`	`ObjID`	The original objid in the vault in which the object was originally created.
`ov_ex.object_info.associated_view_id`	`ItemID`	Identifies the view associated with this object if any.
`ov_ex.object_info.external_repository_icon_id`	`string`	If not null, identifies the icon of the object. Currently applicable only to unmanaged objects.
`ov_ex.object_info.primary_view_id`	`ItemID`	If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects.
`ov_ex.object_info.capabilities`	`OBJECTCAPABILITYFLAGS`	Bit flags that provide information on the object capabilities.
`updated_objects[]`	repeated `ObjectVersionEx`	Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.)
`updated_objects[].version_info`	`ObjectVersion`	Object Version information.
`updated_objects[].version_info.version`	`ObjVerVersion`	The version number, as a specific version.
`updated_objects[].version_info.display_version`	`string`	The version label to show, if it differs from the version number; empty otherwise.
`updated_objects[].version_info.title`	`string`	The title (name) of the object in this version.
`updated_objects[].version_info.is_single_file_object`	`bool`	True if the object is a single-file document, which has exactly one file.
`updated_objects[].version_info.has_relationships_from_this`	`bool`	Note: this field is deprecated. True if relationships from this object version to one or more documents exist.
`updated_objects[].version_info.has_relationships_to_this`	`bool`	Note: this field is deprecated. True if relationships from one or more documents to this object version exist.
`updated_objects[].version_info.has_assignments`	`bool`	True if relationships from one or more assignments to this object version exist.
`updated_objects[].version_info.last_modified_at_utc`	`google.protobuf.Timestamp`	When the version was last modified, in UTC.
`updated_objects[].version_info.files[]`	repeated `File`	The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`.
`updated_objects[].version_info.object_version_flags`	`OBJVERFLAGS`	Bit flags that provide additional information on the object version.
`updated_objects[].version_info.class_id`	`int32`	The class ID of the version.
`updated_objects[].version_info.version_guid`	`string`	The GUID of this version.
`updated_objects[].version_info.base_properties[]`	repeated `PropertyValue`	Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`.
`updated_objects[].version_info.primary_file`	`FileID`	File ID of the primary file of a multi-file object, if the object is a multi-file object.
`updated_objects[].object_info`	`ObjectLevelInfo`	Object-level information.
`updated_objects[].object_info.obj_id`	`ObjID`	The object type and ID of the object.
`updated_objects[].object_info.external_id_status`	`ExtIDStatus`	The status of this object's external ID.Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5).
`updated_objects[].object_info.external_id`	`string`	The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID.
`updated_objects[].object_info.checked_out_version`	`ObjVerVersion`	The version that is checked out. Version number 0 if the object is not checked out.
`updated_objects[].object_info.checked_out_to_user_id`	`int32`	The ID of the user who has the object checked out.
`updated_objects[].object_info.checked_out_to_user_name`	`string`	The user name of the user who has the object checked out.
`updated_objects[].object_info.checked_out_to_host_name`	`string`	The host name of the computer to which the object was checked out.
`updated_objects[].object_info.checked_out_at_utc`	`google.protobuf.Timestamp`	The timestamp of the moment the object was checked out.
`updated_objects[].object_info.checked_in_version`	`ObjVerVersion`	The latest checked-in version.
`updated_objects[].object_info.created_at_utc`	`google.protobuf.Timestamp`	The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue).
`updated_objects[].object_info.accessed_by_me_utc`	`google.protobuf.Timestamp`	Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back.
`updated_objects[].object_info.guid`	`string`	The object GUID, in braces. The same value as `GetObjectGUID` returns.
`updated_objects[].object_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the object (e.g. is the object deleted or a stub).
`updated_objects[].object_info.original_vault_guid`	`string`	The GUID of the vault in which the object was originally created.
`updated_objects[].object_info.original_vault_obj_id`	`ObjID`	The original objid in the vault in which the object was originally created.
`updated_objects[].object_info.associated_view_id`	`ItemID`	Identifies the view associated with this object if any.
`updated_objects[].object_info.external_repository_icon_id`	`string`	If not null, identifies the icon of the object. Currently applicable only to unmanaged objects.
`updated_objects[].object_info.primary_view_id`	`ItemID`	If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects.
`updated_objects[].object_info.capabilities`	`OBJECTCAPABILITYFLAGS`	Bit flags that provide information on the object capabilities.

DownloadFile_ReadBlock -- Reads a block of a file from a download session.
DownloadFile_Stop -- Closes a download session.
GetTextContentForFileWithFormat -- Gets the text content of a file version as plain text or Markdown, and reports which format was produced.
DownloadFile -- Not available over native gRPC: the server answers "Not implemented.". Used by the M-Files HTTP gateway.

IRPCObjectOperations.DownloadFile_Begin

Remarks

Request: DownloadFile_BeginRequest

Response: DownloadFile_BeginResponse

Related methods