3.1.4.4 Receiving a SYNC_VOLUMES Message

  • Article

This message is received by the server as part of a LnkSvrMessage request, as defined in section 3.1.4.1.

This request is used to synchronize volume information between the client and the server. This allows the client to create, query, modify, find, or delete one or more entries in the ServerVolumeTable.

The message consists of a TRKSVR_CALL_SYNC_VOLUMES structure (defined in section 2.2.12.3). This structure contains an array of TRKSVR_SYNC_VOLUME structures, each of which is termed a subrequest in this protocol specification. The SyncType field in the TRKSVR_SYNC_VOLUME structure identifies the specific subrequest. The remaining fields in this structure have different uses, depending on the SyncType field value.

Generally, for each subrequest, the server reads some of the fields in the TRKSVR_SYNC_VOLUME structure and sets other fields for return to the client, depending on the subrequest, as specified in the remainder of this section (and its subsections).

Unless otherwise specified, the server MUST set the hr field of the TRKSVR_SYNC_VOLUME structure in each subrequest to a failure value, and MUST ignore all other fields in this structure.

However, the server need not return the updated TRKSVR_SYNC_VOLUME structures to the client by returning from the LnkSvrMessage request. Instead, the server MAY<7> send the updated structures directly to the client, during the LnkSvrMessage call by calling the LnkSvrMessageCallback callback method (defined in section 3.2.4.1) and passing the updated TRKSVR_SYNC_VOLUME structures via the TRKSVR_MESSAGE_UNION field. In this case, the following MUST be followed:

  • All subrequests MUST be processed by the server before calling the callback method.

  • All of the TRKSVR_SYNC_VOLUME structures in the request MUST be sent to the client in the callback method. That is, the server MUST NOT return some of the updated structures in the callback and other of these structures in the return from the LnkSvrMessage request. Because of this, regardless of the return value from the LnkSvrMessageCallback method, the cVolumes field of the TRKSVR_CALL_SYNC_VOLUMES structure MUST be set to zero by the server before returning from the LnkSvrMessage request.

  • The server MUST use the return value of the LnkSvrMessageCallback method as the return value for the LnkSvrMessage request.

In addition to the return value of the LnkSvrMessage method itself, there is an HRESULT type for each subrequest, in the hr field of the TRKSVR_SYNC_VOLUME structure.

The type of the hr field is HRESULT, but as defined in section 2.2.14, only zero is defined to be a successful return result. Unless otherwise specified in the following sections, the server MUST set the hr field of every subrequest to a value indicating failure.

The following sections define the handling by the server for each subrequest type. The subrequests MUST be processed in the order in which they appear in the TRKSVR_CALL_SYNC_VOLUMES structure. Except where otherwise noted in these sections, the server MUST ignore all fields of each TRKSVR_SYNC_VOLUME structure.