Share via

3.2.4.1.12 RdcGetFileData (Opnum 11)

  • Article

The RdcGetFileData method is used to obtain file ranges whose requests have previously been queued on a server by calling the RdcPushSourceNeeds method.

 DWORD RdcGetFileData(
   [in] PFRS_SERVER_CONTEXT serverContext,
   [out, size_is(bufferSize), length_is(*sizeReturned)] 
     byte* dataBuffer,
   [in, range(0, CONFIG_TRANSPORT_MAX_BUFFER_SIZE)] 
     DWORD bufferSize,
   [out] DWORD* sizeReturned
 );

serverContext: The context handle that represents the requested file replication operation. The client MUST specify a server context that was retrieved by a previously successful call to the InitializeFileTransferAsync method in which the client set the rdcDesired parameter to TRUE.

dataBuffer: The file data received from the server.

bufferSize: The size, in bytes, of dataBuffer

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

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.

0x00000057

ERROR_INVALID_PARAMETER

The context is invalid.

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 RDC file data request: The server MUST validate the request by performing the following checks.

  • If the specified server context was not retrieved by a previously successful call to the InitializeFileTransferAsync method, then the server MUST fail the call with the ERROR_INVALID_PARAMETER failure value.

  • If the server has already completed transferring the file associated with the server context, the server MUST fail the call with an implementation-defined failure value.

  • If the specified server context was retrieved via a call to the InitializeFileTransferAsync method in which the client set the rdcDesired parameter to FALSE, then the server MUST fail the call with an implementation-defined failure value.

  • If the specified server context was retrieved via a call to the InitializeFileTransferAsync method in which the server set the rdcSignatureLevels field to zero in the rdcFileInfo output parameter (see section 2.2.1.4.11), then the server MUST fail the call with an implementation-defined failure value.

  • If the server is not currently participating in the replication of the replicated folder that is associated with the specified server context, then the server MUST fail the call with the FRS_ERROR_CONTENTSET_NOT_FOUND failure value.

  • If bufferSize is less than XPRESS_RDC_MIN_GET_DATA_BUFFER_SIZE_WITH_FILE_HEADER then the server MUST fail the call with an implementation-defined failure value

  • 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 RDC file data request, the server serves file data from the source needs that were queued by the RdcPushSourceNeeds method.

Remarks: If the RDC source needs requested by the client through one or multiple calls to the RdcPushSourceNeeds method have already been processed and retrieved by the client through a series of calls to the RdcGetFileData method, then the server MUST complete the call successfully and set the sizeReturned parameter to zero to indicate that the server has completed the transfer of the previously requested source needs.

If the client has not called the RdcPushSourceNeeds method before calling the RdcGetFileData method, then the server MUST complete the call successfully and set the sizeReturned parameter to zero to indicate that the server has completed the transfer of the file associated with the server context.

The dataBuffer parameter is large enough to hold at least the FileHeader and one data block as explained below in the dataBuffer format section. A data block cannot be partially returned in dataBuffer. The server stops filling up dataBuffer when there is not enough space left to write the next data block, or when there are no more data blocks to send.

Format of dataBuffer: The format of the dataBuffer parameter is as follows.

  • FileHeader

  • DataBlock1

  • DataBlock2

A data block is composed of the following.

  • Fragment Header

  • List of fragments <optional>

  • XPRESS Block

FileHeader: Consists of the four bytes 0x46, 0x52, 0x44, and 0x43 (in ASCII, that is 'F', 'R', 'D', and 'C').


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0x46

0x52

0x44

0x43

Fragment Header: Consists of a 4-byte number, numberOfFragments, which is the number of data fragments to follow. This value MUST be no greater than XPRESS_RDC_MAX_NB_NEEDS_FOR_COMPRESSION.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

numberOfFragments

Fragment: The list of fragments consists of 0 or more instances of the following structure.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

BlockOffset

FragmentSize

XPRESS_Block

BlockOffset: A starting offset into the uncompressed bytes from the XPRESS Block portion. The valid range of this field is 0 to X_CONFIG_XPRESS_BLOCK_SIZE-1.

FragmentSize: The number of uncompressed bytes that the server instructs the client to extract. The uncompressed bytes start from BlockOffset and include at most, X_CONFIG_XPRESS_BLOCK_SIZE-blockOffset-1 bytes. The valid range of this field is 1 to X_CONFIG_XPRESS_BLOCK_SIZE. Additionally, for each fragment, the sum of the BlockOffset field and the FragmentSize field MUST be less or equal to X_CONFIG_XPRESS_BLOCK_SIZE.

XPRESS Block: Following the optional list of fragments is a variable size XPRESS Block, as specified in section 2.2.1.4.15.

All the data is tightly packed—no padding bytes are added for alignment purposes.