3.2.4.1.14 InitializeFileTransferAsync (Opnum 13)

  • Article

The InitializeFileTransferAsync method is used by a client to start a file download. The client supplies an update to specify which file to download. The server provides its latest version of the update and initial file contents. The server returns information about the file currently being replicated and the first buffer of data from that file (if any).

 DWORD InitializeFileTransferAsync(
   [in] FRS_CONNECTION_ID connectionId,
   [in, out] FRS_UPDATE* frsUpdate,
   [in, range(0,1)] long rdcDesired,
   [in, out] FRS_REQUESTED_STAGING_POLICY* stagingPolicy,
   [out] PFRS_SERVER_CONTEXT* serverContext,
   [out] FRS_RDC_FILEINFO** rdcFileInfo,
   [out, size_is(bufferSize), length_is(*sizeRead)] 
     byte* dataBuffer,
   [in, range(0, CONFIG_TRANSPORT_MAX_BUFFER_SIZE)] 
     DWORD bufferSize,
   [out] DWORD* sizeRead,
   [out] long* isEndOfFile
 );

connectionId: The GUID of an outbound connection (see the objectGUID attribute specified in section 2.3.11) that the client established by a previous call to the EstablishConnection method.

frsUpdate:  The FRS_UPDATE structure that contains information about the file being replicated. The fields for the UID in frsUpdate MUST be set to the UID of the file to be downloaded. All other fields are cleared (zeroed out) or can have the values provided by the server in the response to a RequestUpdates call. On return, all fields of frsUpdate MUST contain the values that are held by the server.

rdcDesired: The value is TRUE if RDC has to be used when replicating this file; otherwise, the value is FALSE.

stagingPolicy: The FRS_REQUESTED_STAGING_POLICY enumeration value that indicates the type of staging requested.  If the client-supplied value of rdcDesired is TRUE and the client-supplied value of stagingPolicy is SERVER_DEFAULT, then the server MUST set stagingPolicy to STAGING_REQUIRED. If the client-supplied value of rdcDesired is FALSE and the client-supplied value of stagingPolicy is STAGING_REQUIRED, then the server MUST set stagingPolicy to STAGING_REQUIRED. If the client-supplied value of rdcDesired is FALSE and the client-supplied value of stagingPolicy is RESTAGING_REQUIRED, then the server MUST set stagingPolicy to RESTAGING_REQUIRED.

serverContext: The context handle that represents the requested file replication operation.

rdcFileInfo: The FRS_RDC_FILEINFO structure that describes the file whose replication is in progress.

dataBuffer: The file data received from the server.

bufferSize: The size, in bytes, of dataBuffer. CONFIG_TRANSPORT_MAX_BUFFER_SIZE is 262,144.

sizeRead: The size, in bytes, of the file data returned in dataBuffer.

isEndOfFile: The value is TRUE if the end of the specified file has been reached and there is no more file data to replicate to the client; otherwise, the value is FALSE.

Return Values: This method MUST return 0 on success or a nonzero error code on failure. For protocol purposes all nonzero values MUST be treated as equivalent failures unless otherwise specified.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

0x00002342

FRS_ERROR_CONNECTION_INVALID

The connection is invalid.

0x00002344

FRS_ERROR_CONTENTSET_NOT_FOUND

The content set was not found.

0x0000234B

FRS_ERROR_RDC_GENERIC

Unknown error in RDC.

0x00002358

FRS_ERROR_XPRESS_INVALID_DATA

The compressed data is invalid.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Validating the file transfer request: The server MUST validate the file transfer request by performing the following checks.

  • If an outbound connection for the specified connection is not established between the client and server (see the EstablishConnection method) then the server MUST fail the call with the FRS_ERROR_CONNECTION_INVALID failure value.

  • If a replicated folder session for the contentSetId specified in frsUpdate is not established between the client and server (see the EstablishSession method), then the server MUST fail the call with the FRS_ERROR_CONTENTSET_NOT_FOUND failure value.

  • If the file on the server has been deleted and if the corresponding file metadata has been updated with the present flag set to 0 then the server MUST fail the call with an implementation-defined failure value.

  • If the information stored in its database for the file associated with the requested UID in the supplied update is not in sync with the File Replication Store, or the server is performing operations on the database records that prevent the file from being replicated until those operations complete, then the server MUST fail the call with an implementation-defined failure value. <29>

  • If the server detects that the compressed data of the staged file is corrupted then the server MUST fail the call with FRS_ERROR_XPRESS_INVALID_DATA. Refer to section 3.3.4.7.1 for more information about the staging area.

Actions Triggered: Upon successfully validating the file transfer request, the server MUST retrieve the file data associated with the requested UID in the supplied update. The server MUST then send the file data in the way that the client has specified if possible (using RDC or not using RDC). The server sends file data by providing as much marshaled and compressed data as fits into the output buffer provided in the InitializeFileTransferAsync method call. The remaining marshaled and compressed file data is sent in response to subsequent client calls to retrieve file contents. The server MUST provide the file metadata that is associated with the file that it serves. It does so by providing its own view of the update associated with the requested UID in the return value of frsUpdate.

Remarks: File data in dataBuffer is transferred over the wire in a format that is composed of two layers.

  1. A stream of file data that consists of a custom marshaled format (as specified in section 3.2.4.1.14.1). The custom marshaled format encapsulates file data compatible with [MS-BKUP] and file metadata compatible with formats specified in [MS-FSCC].

  2. An encapsulation of the marshaled file data stream using the compressed data format (as specified in section 3.2.4.1.14.2) generated by the compression algorithm specified in section 3.1.1.1. Even if the marshaled file data stream is not compressed by the server, it is still encapsulated using the compressed data format.

The format of the backup stream is as specified in [MS-BKUP], and the format of the compressed marshaled stream is as specified in sections 3.2.4.1.14.1 and 3.2.4.1.14.2.

If bufferSize is zero then the server SHOULD complete the call successfully with sizeRead set to zero, or fail the call with an implementation-defined failure value.

In the case where the client requests an RDC transfer, the server informs the client of the RDC parameters that were used for the signatures for the file being transferred. Typically, the parameters are different for the first recursion level and for all other levels <30> The server limits the number of simultaneous outstanding file downloads and returns an implementation-defined failure value when a file download is attempted while a configured threshold<31> of simultaneous downloads has been reached.

If a client issues multiple simultaneous calls to any of the RPC methods taking a server context as an input parameter (RawGetFileData, RdcGetSignatures, RdcPushSourceNeeds, RdcGetFileData, RawGetFileDataAsync or RdcGetFileDataAsync) with the same server context, then the server MUST ensure that only the first call is processed and all other calls are failed with an implementation-defined failure value.