3.2.4.1.7 RequestRecords (Opnum 6)

  • Article

The RequestRecords method is used to request all (UID, GVSN) pairs that correspond to live (non-tombstone) records on the server for a specified replicated folder during slow sync (see section 3.3.1.3).

 DWORD RequestRecords(
   [in] FRS_CONNECTION_ID connectionId,
   [in] FRS_CONTENT_SET_ID contentSetId,
   [in] FRS_DATABASE_ID uidDbGuid,
   [in] DWORDLONG uidVersion,
   [in, out] DWORD* maxRecords,
   [out] DWORD* numRecords,
   [out] DWORD* numBytes,
   [out, size_is(,*numBytes)] byte** compressedRecords,
   [out] RECORDS_STATUS* recordsStatus
 );

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.

uidDbGuid: A UID database GUID. This parameter, along with the uidVersion parameter, specifies an iterator into the server's records. A value of zero specifies a request for all of a replicated folder's records from the server.

uidVersion: A UID version. The parameter, along with uidDbGuid parameter, specifies an iterator into the server's records. A value of zero specifies a request for all of a replicated folder's records from the server.

maxRecords: The maximum number of records that the server can send to the client. The server returns the lesser of the client-specified value and the maximum number of records that the server is capable of sending.<26>

numRecords: The number of records written into the compressedRecords buffer by the server.

numBytes: The size, in bytes, of the compressedRecords buffer.

compressedRecords: The data records, compressed using the algorithm specified in section 3.1.1.1.

The compressedRecords bytes correspond to an array of FRS_ID_GVSN entries. DFS-R uses custom marshaling in this RPC call to compress the set of transmitted records. The size of the FRS_ID_GVSN array is given by the numRecords parameter. The decompression algorithm specified in section 3.1.1.2 can be used to decompress the received data into a buffer of sizeof(FRS_ID_GVSN)*numRecords bytes, which can be re-interpreted as an array of FRS_ID_GVSN entries.

recordsStatus: The value from the RECORDS_STATUS enumeration that indicates whether more update records are available.

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.

0x00002344

FRS_ERROR_CONTENTSET_NOT_FOUND

The content set was not found.

0x000024FE

FRS_ERROR_CSMAN_OFFLINE

The server is not currently participating in the replication of the specified replicated folder.

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

Validating the asynchronous records request: The server validates the records 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 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 server is no longer participating in the replication of the specified replicated folder, then the server SHOULD fail the call the FRS_ERROR_CSMAN_OFFLINE failure value.<27>

Actions Triggered: Upon successfully validating the records request the server MUST send as many of the requested records as possible, up to a limit of the lesser of the client-specified maxRecords parameter value and the maximum number of records the server is capable of sending.

The server MUST send records starting at the record immediately following the record whose UID iterator is formed by the pair (uidDbGuid, uidVersion). If the iterator is zero then the server MUST begin returning records from the first of the replicated folder's records.

If the iterator, formed by the pair (uidDbGuid, uidVersion), is not zero and there are no more records to send following the cursor, then the server MUST return 0 records. If there are no more records to send, the server MUST set the value of the recordsStatus parameter to RECORDS_STATUS_DONE. If there are more records to send, the server MUST set the value of the recordsStatus parameter to RECORDS_STATUS_MORE.

Remarks: Provided that the persistent store on a server is unchanged between calls to RequestRecords, a server MUST be able to fill in all updates present in its persistent store in the course of repeated calls to RequestRecords. When all updates have been supplied in the RequestRecords call, the server MUST be able to resend all updates again if another round of RequestRecords arrives.