3.2.4.1.10 RdcGetSignatures (Opnum 9)

  • Article

The RdcGetSignatures method is used to obtain a file's RDC signature data from the server.

 DWORD RdcGetSignatures(
   [in] PFRS_SERVER_CONTEXT serverContext,
   [in, range(1, CONFIG_RDC_MAX_LEVELS)] 
     byte level,
   [in] DWORDLONG offset,
   [out, size_is(length), length_is(*sizeRead)] 
     byte* buffer,
   [in, range(1, CONFIG_RDC_MAX_NEEDLENGTH)] 
     DWORD length,
   [out] DWORD* sizeRead
 );

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 InitializeFileTransferAsync method in which the client set the rdcDesired parameter to TRUE.

level: The RDC recursion level being requested. A client MUST specify a number in the range of 1 to x, where x is the value of the rdcSignatureLevels field of the rdcInfo structure that was returned by the InitializeFileTransferAsync method call associated with the specified server context.

offset: The zero-based offset, in bytes, at which to retrieve data from the file.

buffer: The file signature data received from the server.

length: The size, in bytes, of buffer.

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

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.

0x00002344

FRS_ERROR_CONTENTSET_NOT_FOUND

The content set was not found.

0x0000234B

FRS_ERROR_RDC_GENERIC

Unknown error in RDC.

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

This method uses the Remote Differential Compression Algorithm, as specified in [MS-RDC], when replicating a changed file.

Validating the signature request: The server MUST validate the signature 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 the value of the level parameter is not in the range 1 to x, where x is the value of the rdcSignatureLevels field of the rdcFileInfo output parameter (see section 2.2.1.4.11) that was returned by the InitializeFileTransferAsync method call associated with the specified server context, then the server MUST fail the call with an implementation-defined failure value.

  • If offset is beyond the end of the file then the server MUST fail the call with an implementation-defined failure value.

Actions Triggered: Upon successfully validating the signature request, the server returns a buffer of RDC signature information for the specified level and the specified file. The server MUST return as many bytes as requested, except when the end of file is reached. In this case, the server MUST return as many bytes as remain in the file from the specified offset, which can be zero bytes.

Remarks: The server MUST allow the client to read randomly from all available signature streams.

The format of the signature data is as specified in [MS-RDC].