3.2.4.1.11 RdcPushSourceNeeds (Opnum 10)

  • Article

The RdcPushSourceNeeds method is used to register requests for file ranges on a server.

 DWORD RdcPushSourceNeeds(
   [in] PFRS_SERVER_CONTEXT serverContext,
   [in, size_is(needCount)] FRS_RDC_SOURCE_NEED* sourceNeeds,
   [in, range(0, CONFIG_RDC_NEED_QUEUE_SIZE)] 
     DWORD needCount
 );

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.

sourceNeeds: The pointer to a set of FRS_RDC_SOURCE_NEED structures that indicate the offsets and lengths of file data that is sent from the server to the client.

needCount: The number of FRS_RDC_SOURCE_NEED structures pointed to by sourceNeeds.

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.

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

Validating the RDC source needs 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.

Actions Triggered: Upon successfully validating the RDC source needs request, the server queues up the requested file offset/length pairs, also known as RDC source needs. The number of RDC source needs queued by the server MUST NOT exceed the value of CONFIG_RDC_NEED_QUEUE_SIZE. The client MAY send multiple RdcPushSourceNeeds requests. If the server receives a request that causes the total number of RDC source needs already in the queue plus the value of the needCount parameter to be greater than the value of CONFIG_RDC_NEED_QUEUE_SIZE, then the server MUST fail the request with an implementation-defined failure value.

The server uses the queued RDC source needs to form a stream of data from the marshaled source file. The format of this data stream is specified in section 3.2.4.1.12 and is returned in the buffer supplied by the RdcGetFileData method or the RdcGetFileDataAsync method.

Remarks: If the needSize parameter in FRS_RDC_SOURCE_NEED has a value of zero, then the server SHOULD fail the request to queue RDC source needs, with an implementation-defined failure value.

If the needCount parameter has a value of zero, then the server SHOULD complete the call successfully, or MAY fail the call with an implementation-defined failure value.

If any of the RDC source needs in the sourceNeeds buffer specifies a range of data that is not part of the marshaled source file, then the server completes this call successfully and will fail the call to the RdcGetFileData method or the RdcGetFileDataAsync method when the RDC source needs are processed.