Share via

3.1.5.7 SyncUpdates

  • Article

Synopsis:

This is the main operation that supports the synchronization of update metadata to client computers (2). It is invoked to perform both software and driver metadata synchronization. Software update synchronization SHOULD be performed first, using a sequence of calls to this method as described below. Driver synchronization SHOULD then be performed using a single call to the method.

During the Software update synchronization phase, the client MUST call the SyncUpdates method with the SkipSoftwareSync field in the SyncUpdateParameters input parameter set to false. The client MUST make multiple calls to this method to retrieve all applicable software updates from the server. The client MUST follow the below rules to determine the input parameters for each call in the sequence and to determine when to stop:

The client MUST

  1. First call SyncUpdates with InstalledNonLeafUpdateIDs field set to empty.

  2. Check if the NewUpdates element in the result is empty. If it is empty, then the software update synchronization is complete.

  3. Otherwise, evaluate the applicability of updates in the result of the call and collect applicable updates into a list. The applicability evaluation is performed using the metadata contained in the XmlFragments provided by the server and is implementation-specific.<53>

  4. From the list compiled in step 3, select those updates that evaluated as installed and which are marked with the IsLeaf field as false in the UpdateInfo structure and append their IDs to the InstalledNonLeafUpdateIDs sent in the last call to SyncUpdates. From the remaining updates in the list, select those that are drivers and append their IDs to the CachedDriverIDs sent in the last call to SyncUpdates. For the remaining updates in the list, append their IDs to the OtherCachedUpdateIDs sent in the last call to SyncUpdates. Call SyncUpdates again and continue from step 2.

Request Validation:

Parameter

Validation conditions

Error code

cookie

MUST be a valid cookie, issued by this server, that has not expired.

InvalidCookie, ServerChanged, or CookieExpired

Parameters

MUST be specified.

InvalidParameters

Additional checks the server MUST perform:

  • If Parameters.SystemSpec is present and Parameters.SkipSoftwareSync is FALSE, throw an InvalidParameters ErrorCode.

Data Processing:

The data processing specified in this section references most of the elements of the abstract data model, as specified in section 3.1.1.

The server MUST check whether the configuration data returned from GetConfig (section 3.1.5.2) has changed since the last time the client synchronized and, if so, throw a ConfigChanged ErrorCode fault.

The server checks whether client registration is required but the client is not yet registered. If so, it SHOULD throw a RegistrationRequired ErrorCode.

The following rules for driver matching are implemented by the server. Given any two drivers in the driver table as specified in the Abstract Data Model (section 3.1.1), the server MUST conclude that one of the two is a better match for a device listed in the system specification if one of the following rules applies:

  • It is targeted to a more specific Computer HardwareId match for the client system that is listed earlier in the ComputerHardwareIDs section of the system spec XML.

  • Both Computer HardwareId matches are the same specificity, but it has a better feature score, meaning the feature score value was lower.

  • ComputerHardwareIDs and FeatureScores are the same, but it has a better HardwareID match: the one driver HardwareID matches on a device HardwareID or CompatibleID that is listed earlier in the device XML.

  • ComputerHardwareIDs, FeatureScores, and HardwareIDs are equal matches, but the one driver has a more recent DriverVerDate.

  • ComputerHardwareIDs, FeatureScores, HardwareIDs, and DriverVerDate are the same, but the one driver has a higher DriverVerVersion (after converting the four-part version string to a 64-bit integer.

Given a collection of drivers and a particular device listed in the system spec, the "best" driver for that device is determined by applying the above rules repeatedly to each pair-wise combination of drivers, discarding any driver not deemed "better" in a given pair-wise combination. The last remaining driver is the "best" match.

Given the above rules, the next step is for the server to compute the NeededRevisions list for the client. The server MUST do so as follows:

  1. Restrict the set of revisions to those that are deployed to the client computer's target group, combined with any dependencies (prerequisite or bundle) of such updates.

  2. Restrict the resulting set further to those revisions whose prerequisites are satisfied by the updates whose revision IDs are specified in Parameters.InstalledNonLeafUpdateIDs.

  3. Restrict the resulting set further to either:

    • If performing software update synchronization (SkipSoftwareSync = false): revisions with UpdateType = Software.

    • If performing driver synchronization (SkipSoftwareSync = true): revisions for which all the following conditions hold:

      • UpdateType = Driver, and

      • The revision has an entry in the driver table that MUST be the "best" match for one of the devices in the system spec, and

      • If there is already a driver installed on the device:

        • The revision has an entry in the driver table that MUST be a "better" match than the installed driver, and

        • If the installed driver is a printer (Class='Printer'), then the revision MUST have an entry in the driver table which matches the Provider and Manufacturer for the installed driver.

Next, the server MUST generate the list of CachedRevisions for the client as follows:

  • If performing software synchronization (SkipSoftwareSync = false), take the union of revisions in Parameters.InstalledNonLeafUpdateIDs and Parameters.OtherCachedUpdateIDs.

  • If performing driver synchronization (SkipSoftwareSync = true), take the revisions listed in Parameters.CachedDriverIDs.

Results:

If no faults occur during the operation, the server MUST return a SyncUpdatesResponse message to the client. It MUST generate the response as follows:

  • SyncUpdatesResponse.NewUpdates: Populated with entries for revision in the NeededRevisions list that are not in the CachedRevisions list:

    • ID: The revision ID.

    • Deployment:

      Information about the deployment to this revision. If this revision was not itself explicitly deployed to the client by an administrator (for example, it was included in the NeededRevisions list because it was a dependency of an explicitly deployed revision), the DeploymentAction MUST be set to "Evaluate". For driver updates (UpdateType = driver), when the client reports a protocolVersion of "1.6" or higher in the GetCookie call, the server SHOULD include all the HardwareIDs associated with this revision from the driver table that are selected as "best" matches.<54>

    • IsLeaf: Specifies whether the revision is a leaf on the prerequisite graph or not. In particular, that there are no entries in the abstract data model Prerequisite table (as specified in section 3.1.1) that have this revisions UpdateID specified as a PrerequisiteUpdateID.

    • Xml: The revision's associated "core" metadata (FragmentType = "Core").

    Note: The server implementation MUST send no more than one revision for a given Update. It is recommended that the implementation SHOULD, in the event of multiple matches, select only the latest revision (the one with the highest revision number).

  • SyncUpdatesResponse.OutOfScopeRevisionIDs: Populated with the IDs of revision that are in the CachedRevisions list that are not in the NeededRevisions list.

  • SyncUpdatesResponse.ChangedUpdates: Populated with entries for revisions in the NeededRevisions list that are also in the CachedRevisions list, but for which Deployment or IsLeaf data has changed since the last time the client synchronized with the server. The fields of these entries are populated according to the server's abstract data model (as specified in section 3.1.1) as follows:

    • Deployment: The entry in the deployment table that specifies how the revision is deployed to the client's target group.

    • IsLeaf: The entry in the Revision table that specifies whether the revision is a leaf in the prerequisite graph.

    • SyncUpdatesResponse.Truncated: The server MAY choose to return a subset of the updates that would normally be returned in the <NewUpdates> collection, in order to reduce the processing overhead incurred by a single call to the server. In such cases, the server MUST set Truncated = true.<55>

    • SyncUpdatesResponse.NewCookie: The server MUST return a new cookie for the client to use on subsequent SyncUpdates calls. The server SHOULD update the cookie with the highest (most recent) LastChangeTime stored in the deployment table. This allows the server to determine, on future calls to SyncUpdates, if a revision that stays in scope for the client needs to have its deployment returned in the ChangedUpdates list; if the current deployment's LastChangeTime is less than the value stored in this cookie, then the deployment need not be returned in the ChangedUpdates list, since the deployment data will already be cached on the client.