188.8.131.52.7 RequestRecords (Opnum 6)
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 184.108.40.206).
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 );
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 may 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.<25>
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 DFS-R compression algorithm specified in section 220.127.116.11.
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 18.104.22.168.3.9 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.
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
The method completed successfully.
The content set was not found.
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 must validate 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.<26>
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.