3.2.4.1.4 RequestUpdates (Opnum 3)

  • Article

The RequestUpdates method is used to obtain a specified set of updates (replicated file metadata) from a server.

 DWORD RequestUpdates(
   [in] FRS_CONNECTION_ID connectionId,
   [in] FRS_CONTENT_SET_ID contentSetId,
   [in, range(0,256)] DWORD creditsAvailable,
   [in, range(0,1)] long hashRequested,
   [in, range(UPDATE_REQUEST_ALL, UPDATE_REQUEST_LIVE)] 
     UPDATE_REQUEST_TYPE updateRequestType,
   [in] unsigned long versionVectorDiffCount,
   [in, size_is(versionVectorDiffCount)] 
     FRS_VERSION_VECTOR* versionVectorDiff,
   [out, size_is(creditsAvailable), length_is(*updateCount)] 
     FRS_UPDATE* frsUpdate,
   [out] DWORD* updateCount,
   [out] UPDATE_STATUS* updateStatus,
   [out] GUID* gvsnDbGuid,
   [out] DWORDLONG* gvsnVersion
 );

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.

contentSetId: The GUID of the replicated folder (see the objectGUID attribute specified in section 2.3.7) in the specified connection's replication group.

creditsAvailable: The maximum number of updates that the client can receive in the frsUpdate buffer.

hashRequested: The client sets the hashRequested parameter to TRUE to request that the server compute the hash (see the hash field of the FRS_UPDATE structure specified in section 2.2.1.4.4) for each update that it sends, or FALSE if the hashes are not desired. The server SHOULD compute hashes when hashes are requested, although it is not required to do so. Computing a file's hash requires DFS-R to read the file's data. It is possible that another process has already opened the file for exclusive access, which prevents DFS-R from computing the file hash. In this scenario, the DFS-R server does not compute the hash even if the client requested that it does.

updateRequestType: The value from the UPDATE_REQUEST_TYPE enumeration that indicates the type of replication updates requested.

versionVectorDiffCount: The number of items specified in the versionVectorDiff parameter.

versionVectorDiff: The set of FRS_VERSION_VECTOR structures that specifies what updates the client requires from the server. This parameter specifies the difference between the client's version vector and the client's most recent copy of the server's version vector obtained from a previous call to the RequestVersionVector method.

frsUpdate: The set of FRS_UPDATE structures that describes the update that occurred to each of the files to be replicated.

updateCount: The number of updates that the server wrote into the frsUpdate buffer.

updateStatus: The value from the UPDATE_STATUS enumeration that specifies if all of the requested updates have been sent by the server.

gvsnDbGuid: The GVSN GUID (as specified in [MS-DTYP] section 2.3.4) for the last field in the versionVectorDiff that was processed.

gvsnVersion: The version of the gvsnDbGuid.

Return Values: The 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.

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 updates request: The server validates the updates 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 an implementation-defined failure value.

  • If a replicated folder session for the specified replicated folder 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 contents of the versionVectorDiff parameter are invalid (see section 2.2.1.4.1 for the FRS_VERSION_VECTOR structure requirements) then the server MUST fail the call with an implementation-defined failure value.

Actions Triggered: Upon successfully validating the update request, the server MUST send as many of the requested updates as fit in the frsUpdate buffer. The server sends records for the GVSNs that are known to the server, appear in the specified versionVectorDiff parameter, and are of the type specified by the updateRequestType parameter.

The server MUST scan through the database for the updates.

If the value of the updateRequestType parameter is UPDATE_REQUEST_TOMBSTONES, the server SHOULD<23> send version vector tombstone updates as follows:

  • When a particular update is not stale,<24> set the present field of the FRS_UPDATE structure specified in section 2.2.1.4.4 to 1.

  • When a particular update is stale,<25> set the present field of the FRS_UPDATE structure specified in section 2.2.1.4.4 to 0.

If the value of the updateRequestType parameter is UPDATE_REQUEST_ALL and there are tombstone updates to send, the server MUST place the tombstone updates ahead of the live updates in the frsUpdate buffer.

The server MUST indicate to the client if there are more of the requested updates to be retrieved by setting the updateStatus parameter to one of the following values.

  • UPDATE_STATUS_DONE: There are no more updates in the scope of the supplied version chain vector.

  • UPDATE_STATUS_MORE:  There are potentially more updates from the supplied version chain vector.

If all of the requested updates could not be sent to the client because of credit limitations, the gvsnDbGuid and gvsnVersion parameters allow the server to indicate to the client how much of the versionVectorDiff has been processed during this call. The returned GVSN (formed by the parameter pair gvsnDbGuid / gvsnVersion) is a cursor into the versionVectorDiff. The cursor MUST be set to the last GVSN covered by versionVectorDiff that was considered for populating the frsUpdate buffer. The cursor is used by the client to determine which remaining updates it requests during subsequent calls to the RequestUpdates method.