IRPCFileTransferStreaming.FileUploadWhole

Vault API / standard write session or assertion client streaming

Uploads a whole file by streaming its content.

The content is sent as a stream of chunks, so neither the client nor the server needs to have the whole content in one message.

The client sends the messages in the following order:

One header message.
Any number of file_data messages containing the file content in order.
One end message. The upload is complete only when the end message has been received. If the request stream ends without the end message, the upload is discarded.

The server streams the content forward with a single request while it is received, so the size of the file is limited by the maximum size of content Master Storage accepts in a single request (the MaxSingleOperationBlobSize setting, 25 MiB by default). The call fails with ERROR_FILE_TOO_LARGE before any content is stored if the declared size exceeds the limit. Larger files must be uploaded in blocks with FileUploadBegin, FileUploadBlock and FileUploadEnd.

The content should be sent in chunks of a few megabytes at most. Each file_data message is limited by the maximum gRPC message size of the server.

Service	Streaming file upload `MFiles.IRPCFileTransferStreaming`
gRPC method	`/MFiles.IRPCFileTransferStreaming/FileUploadWhole`
HTTP (mf-http-grpc)	`POST /grpc/v1/file-upload-whole`
Request	`FileUploadWholeRequest`
Response	`FileUploadWholeResponse`
Book and level	Vault API, standard
Kind	write
Session	Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
Idempotent	no
Returns metadata structure version	no
Streaming	client

Remarks

Without obj_id and file in the header, the result is an ended upload that you use by its file_ref, for example in AddObjectWithFiles or FileUploadAttach. With both, the content is attached to that file right away, as with FileUploadAttach, so the object must be checked out to the caller.

Request: FileUploadWholeRequest

A message of the FileUploadWhole request stream.

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
`header`	`FileUploadWholeHeader` (oneof item)	The first message of the stream. Describes the upload.
`header.obj_id`	`ObjID`	The id of the object to which the file is bound, if attaching immediately. If set, together with file, attach the content to this object's file immediately. If not set, the content is only stored as a stateless temp file, retrievable later via the returned file_ref, using a separate FileUploadAttach call. obj_id and file must either both be set or both be omitted.
`header.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).
`header.obj_id.item_id`	`ItemID`	The ID of the object within its type, in `item_id.internal_id`.
`header.file`	`File`	Information about the uploaded file, if attaching immediately.
`header.file.file_ver`	`FileVer`	The file and its version. Pass it unchanged in an `ObjFileVer` to download the file.
`header.file.title`	`string`	The file name without the extension.
`header.file.extension`	`string`	The file name extension without the dot, for example "pdf".
`header.file.size`	`int64`	The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`.
`header.file.size_precision`	`FileSizePrecision`	How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`.Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2).
`header.file.created_at_utc`	`google.protobuf.Timestamp`	The time in UTC the file was originally created.
`header.file.accessed_at_utc`	`google.protobuf.Timestamp`	The time in UTC the file was last accessed (e.g. read).
`header.file.written_at_utc`	`google.protobuf.Timestamp`	The time in UTC the file was last written to.
`header.file.changed_at_utc`	`google.protobuf.Timestamp`	The time in UTC the file was last written to or its attributes were changed.
`header.file.guid`	`string`	GUID of the file.
`header.file.md5_checksum`	`string`	The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available.
`header.file.is_missing`	`bool`	True, if the file is missing.
`header.file.is_content_volatile`	`bool`	True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only.
`header.file.flags`	`OBJECTFILEFLAGS`	Object file flags.
`header.file.master_storage_file_ref`	`string`	An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty.
`header.file_size`	`uint64`	The size of the whole file content in bytes. Required. The content must be exactly this size. Zero means an empty file. The server uses the size to reject a file that exceeds the maximum upload size before any content is sent, and to stream the content forward as it is received.
`file_data`	`bytes` (oneof item)	A chunk of the file content.
`end`	`FileUploadWholeEnd` (oneof item)	The last message of the stream. Marks the upload as complete.

Response: FileUploadWholeResponse

The response of the FileUploadWhole streaming method.

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
`file_ref`	`string`	The file_ref identifier of the now-ended content. If obj_id and file were not supplied, the content can be attached later with FileUploadAttach. If they were supplied, the content has already been attached and the file_ref can't be attached to another file.
`is_object_info_available`	`bool`	True if information about the object after the attach was provided. Always false if obj_id and file were not supplied, or if the user can't see the object after the attach.
`after_upload`	`ObjectVersionEx`	If is_object_info_available is true, information about the object after the attach.
`after_upload.version_info`	`ObjectVersion`	Object Version information.
`after_upload.version_info.version`	`ObjVerVersion`	The version number, as a specific version.
`after_upload.version_info.display_version`	`string`	The version label to show, if it differs from the version number; empty otherwise.
`after_upload.version_info.title`	`string`	The title (name) of the object in this version.
`after_upload.version_info.is_single_file_object`	`bool`	True if the object is a single-file document, which has exactly one file.
`after_upload.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.
`after_upload.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.
`after_upload.version_info.has_assignments`	`bool`	True if relationships from one or more assignments to this object version exist.
`after_upload.version_info.last_modified_at_utc`	`google.protobuf.Timestamp`	When the version was last modified, in UTC.
`after_upload.version_info.files[]`	repeated `File`	The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`.
`after_upload.version_info.object_version_flags`	`OBJVERFLAGS`	Bit flags that provide additional information on the object version.
`after_upload.version_info.class_id`	`int32`	The class ID of the version.
`after_upload.version_info.version_guid`	`string`	The GUID of this version.
`after_upload.version_info.base_properties[]`	repeated `PropertyValue`	Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`.
`after_upload.version_info.primary_file`	`FileID`	File ID of the primary file of a multi-file object, if the object is a multi-file object.
`after_upload.object_info`	`ObjectLevelInfo`	Object-level information.
`after_upload.object_info.obj_id`	`ObjID`	The object type and ID of the object.
`after_upload.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).
`after_upload.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.
`after_upload.object_info.checked_out_version`	`ObjVerVersion`	The version that is checked out. Version number 0 if the object is not checked out.
`after_upload.object_info.checked_out_to_user_id`	`int32`	The ID of the user who has the object checked out.
`after_upload.object_info.checked_out_to_user_name`	`string`	The user name of the user who has the object checked out.
`after_upload.object_info.checked_out_to_host_name`	`string`	The host name of the computer to which the object was checked out.
`after_upload.object_info.checked_out_at_utc`	`google.protobuf.Timestamp`	The timestamp of the moment the object was checked out.
`after_upload.object_info.checked_in_version`	`ObjVerVersion`	The latest checked-in version.
`after_upload.object_info.created_at_utc`	`google.protobuf.Timestamp`	The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue).
`after_upload.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.
`after_upload.object_info.guid`	`string`	The object GUID, in braces. The same value as `GetObjectGUID` returns.
`after_upload.object_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the object (e.g. is the object deleted or a stub).
`after_upload.object_info.original_vault_guid`	`string`	The GUID of the vault in which the object was originally created.
`after_upload.object_info.original_vault_obj_id`	`ObjID`	The original objid in the vault in which the object was originally created.
`after_upload.object_info.associated_view_id`	`ItemID`	Identifies the view associated with this object if any.
`after_upload.object_info.external_repository_icon_id`	`string`	If not null, identifies the icon of the object. Currently applicable only to unmanaged objects.
`after_upload.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.
`after_upload.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.
`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.

IRPCObjectOperations.AddObjectWithFiles -- Creates a new object, optionally with its files, and optionally checks it in.
IRPCFileTransfer.FileUploadAttach -- Stores an ended upload as the new content of an existing file of an object that is checked out to the caller.

IRPCFileTransferStreaming.FileUploadWhole

Remarks

Request: FileUploadWholeRequest

Response: FileUploadWholeResponse

Related methods