3.2.4.1.5 RequestVersionVector (Opnum 4)

  • Article

The RequestVersionVector method is used to obtain the version chain vector persisted on a server or to request notification when the server's version chain vector changes.

 DWORD RequestVersionVector(
   [in] DWORD sequenceNumber,
   [in] FRS_CONNECTION_ID connectionId,
   [in] FRS_CONTENT_SET_ID contentSetId,
   [in, range(REQUEST_NORMAL_SYNC,REQUEST_SUBORDINATE_SYNC)] 
     VERSION_REQUEST_TYPE requestType,
   [in, range(CHANGE_NOTIFY,CHANGE_ALL)] 
     VERSION_CHANGE_TYPE changeType,
   [in] ULONGLONG vvGeneration
 );

sequenceNumber: The sequence number for this request. The sequence number is used to pair the version vector request with the asynchronous response in AsyncPoll. During a given session, the client SHOULD supply a unique sequence number for each call to this function or else they will not be able to match server responses via the AsyncPoll method to the original version vector request.

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.

requestType: The value from the VERSION_REQUEST_TYPE enumeration that describes the type of replication sync to perform.

changeType: The value from the VERSION_CHANGE_TYPE enumeration that indicates whether to notify change only or send the entire version chain vector.

vvGeneration: The vvGeneration parameter is used to calibrate what incarnation of the server's version chain vector is known to the client. The client supplies the last generation number that it received from the server when the requestType parameter is set to REQUEST_NORMAL_SYNC. Otherwise the client MUST supply zero.

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.

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

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

  • If the value of the requestType parameter is REQUEST_SLOW_SYNC or REQUEST_SUBORDINATE_SYNC and the value of the vvGeneration parameter is not zero, then the server MUST fail the call with an implementation-defined failure value.

  • If the value of the requestType parameter is REQUEST_SLOW_SYNC or REQUEST_SUBORDINATE_SYNC and the value of the changeType parameter is not CHANGE_ALL, then the server MUST fail the call with an implementation-defined failure value.

  • If the value of the requestType parameter is REQUEST_SUBORDINATE_SYNC and the server's DFS-R protocol version is not FRS_COMMUNICATION_PROTOCOL_VERSION_LONGHORN_SERVER, then the server MUST fail the call with an implementation-defined failure value.

  • If the value of the changeType parameter is not CHANGE_NOTIFY or CHANGE_ALL, then the server fails the call with an implementation-defined failure value.

Actions Triggered when the requestType parameter is NORMAL_SYNC and the changeType parameter is CHANGE_NOTIFY:  The server MUST keep a time stamp on its own version vector. When the server modifies its version vector (in a way visible to clients), the time stamp is incremented. The server communicates its version vector time stamp information to the client when it responds to AsyncPoll requests.

The supplied vvGeneration parameter is used to control when an AsyncPoll request can be completed by the server. The AsyncPoll request MUST be completed by the server when its version vector time stamp supersedes the time stamp passed in as the vvGeneration parameter of the version vector request. The server MUST NOT provide any version vector with the callback.

Actions Triggered when the changeType parameter is CHANGE_ALL:  The client requests to receive the full version vector of the server. The server communicates its version vector information to the client when it responds to AsyncPoll requests.

Remarks:The client SHOULD have an outstanding call to AsyncPoll. If the client does not have an outstanding AsyncPoll request, then the server MUST queue up any response until an AsyncPoll is received such that a response can be sent.

Sequence number for this request: The sequence number is used to pair the version vector request with the asynchronous response in AsyncPoll. The asynchronous response from the server that corresponds to a version vector request MUST contain the same sequence number that was created by the client. A client SHOULD therefore not have two or more outstanding asynchronous requests with the same sequence number.