2.2.2.2.4 SyncUpdates

Article
04/11/2023

Synopsis:

This method is invoked to perform synchronization of metadata describing software update content. The syntax of this method refers to the following concepts as specified in sections 3.1.1 and 3.2.1.

The integer-valued revision ID used to identify an update revision.
The string-valued HardwareID, which identifies a hardware device installed on the client machine.
The integer-valued deployment ID, which identifies a deployment.
The prerequisite relationship between updates.

The client metadata cache.

 <wsdl:operation name="SyncUpdates" />

The SOAP operation is defined as follows.

 <soap:operation soapAction="http://www.microsoft.com/
    SoftwareDistribution/Server/ClientWebService/SyncUpdates" 
    style="document" />

Request:

 <s:element name="SyncUpdates">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="cookie" 
          type="s1:Cookie" />
       <s:element minOccurs="0" maxOccurs="1" name="parameters" 
          type="s1:SyncUpdateParameters" />
     </s:sequence>
   </s:complexType>
 </s:element>

cookie: Specifies a cookie that MUST have been obtained from a previous call to GetCookie (section 2.2.2.2.2), GetFileLocations (section 2.2.2.2.7), or SyncUpdates. This element MUST be present.

Parameters: Additional parameters to this method. This element MUST be present. Its format is as follows.<15>

 <s:complexType name="SyncUpdateParameters">
   <s:sequence>
     <s:element minOccurs="1" maxOccurs="1" name="ExpressQuery" type="s:boolean" />
     <s:element minOccurs="0" maxOccurs="1" name="InstalledNonLeafUpdateIDs" 
        type="s1:ArrayOfInt" />
     <s:element minOccurs="0" maxOccurs="1" name="OtherCachedUpdateIDs" 
        type="s1:ArrayOfInt" />
     <s:element minOccurs="0" maxOccurs="1" name="SystemSpec" type="s1:ArrayOfDevice" />
     <s:element minOccurs="0" maxOccurs="1" name="CachedDriverIDs" 
        type="s1:ArrayOfInt" />
     <s:element minOccurs="1" maxOccurs="1" name="SkipSoftwareSync" type="s:boolean" />
     <s:element minOccurs="0" maxOccurs="1" name="FilterCategoryIds" 
        type="s1:ArrayOfCategoryIdentifier" />
     <s:element minOccurs="0" maxOccurs="1" name="NeedTwoGroupOutOfScopeUpdates" 
        type="s:boolean" />
     <s:element minOccurs="0" maxOccurs="1" name="ComputerSpec" 
        type="s1:ComputerHardwareSpecification" />
     <s:element minOccurs="0" maxOccurs="1" name="FeatureScoreMatchingKey" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

ExpressQuery: This parameter MUST be absent or set to FALSE by the client. It MUST be ignored by the update server.

InstalledNonLeafUpdateIDs: Contains an array of revision IDs of all non-leaf (in the prerequisite graph) revisions in the client cache that are installed on the client. These IDs MUST have been obtained from the UpdateInfo.ID returned from previous calls to this method.

OtherCachedUpdateIDs: Contains an array of revision IDs of other revisions in the client cache. These IDs MUST have been obtained from the UpdateInfo.ID returned from previous calls to this method.

SystemSpec: Specifies the client's existing hardware devices and installed drivers. This information is used in the driver synchronization query to determine if a more closely-matching driver is available on the server. Its format (ArrayOfDevice) is as follows:

 <s:complexType name="ArrayOfDevice">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="unbounded" name="Device" 
        nillable="true" type="s1:Device" />
   </s:sequence>
 </s:complexType>

Device: The SystemSpec is an array of devices. Its format is as follows:

 <s:complexType name="Device">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="HardwareIDs" 
        type="s1:ArrayOfString" />
     <s:element minOccurs="0" maxOccurs="1" name="CompatibleIDs" 
        type="s1:ArrayOfString" />
     <s:element minOccurs="0" maxOccurs="1" name="installedDriver" 
        type="s1:InstalledDriver" />
     <s:element minOccurs="0" maxOccurs="1" name="extensionDriver"
        type="s1:ArrayOfExtensionDriver" />
     <s:element minOccurs="0" maxOccurs="1" name="DriverRecoveryIDs"
        type="s1:ArrayOfDriverRecoveryID" />
     <s:element minOccurs="0" maxOccurs="1" name="DeviceFlags" type="xs:unsignedByte"/>
   </s:sequence>
 </s:complexType>

HardwareIDs: An array of HardwareID values that identify the devices hardware supported by this driver.

CompatibleIDs: An array of HardwareID values that identify the compatible hardware for this device driver.

InstalledDriver: If a driver is already installed for this device, this describes properties of that driver. Its format is as follows:<16>

 <s:complexType name="InstalledDriver">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="MatchingID" 
        type="s:string" />
     <s:element minOccurs="1" maxOccurs="1" name="DriverVerDate" 
        type="s:dateTime" />
     <s:element minOccurs="1" maxOccurs="1" name="DriverVerVersion" 
        type="s:long" />
     <s:element minOccurs="0" maxOccurs="1" name="Class" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="Manufacturer" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="Provider" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="Model" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="MatchingComputerHWID" nillable="true" 
        type="s2:guid" />
     <s:element minOccurs="1" maxOccurs="1" name="DriverRank" type="s:int" />
   </s:sequence>
 </s:complexType>

§ MatchingID: The HardwareID or compatibleID corresponding to the installed driver.

§ DriverVerDate: The release date of the driver.

§ DriverVerVersion: The software version of the driver.

§ Class: The driver class (for example, Printer, Display, and so on), as specified by the driver during installation (typically in the driver INF file).

§ Manufacturer: The company that created the driver.

§ Provider: The company providing the driver.

§ Model: The hardware model that the driver targets.

§ MatchingComputerHWID: The computer HardwareId to which the driver matches.

§ DriverRank: The rank of the driver against a device.

extensionDriver: An extension of a base driver. A base driver MAY have 0 or more associated extension drivers.<17>

 <s:complexType name="extensionDriver">
   <s:sequence>
     <s:element name="ExtensionId" type="s:string" minOccurs="1" maxOccurs="1" /> 
     <s:element name="DriverVerDate" type="s:dateTime" minOccurs="1" maxOccurs="1" /> 
     <s:element name="DriverVerVersion" type="s:long" minOccurs="1" maxOccurs="1" /> 
     <s:element name="Class" type="s:string" minOccurs="1" maxOccurs="1" /> 
     <s:element name="DriverRank" type="xs:int" minOccurs="1" maxOccurs="1" />
     <s:element name="MatchingComputerHWID" type="q4:guid" nillable="true" 
          xmlns:q4="http://microsoft.com/wsdl/types/" minOccurs="0" maxOccurs="1" />
   </s:sequence> 
 </s:complexType>

ExtensionId: Specifies the GUID identifier for the extension driver.
DriverVerDate: The release date of the extension driver.
DriverVerVersion: The software version of the extension driver.
Class: The driver class (for example, Printer, Display, and so on), as specified by the driver during installation (typically in the driver INF file).
DriverRank: The rank of the extension driver against a device.<18>
MatchingComputerHWID: The computer HardwareId to which the driver matches.

ArrayofDriverRecoveryID: An optional array of driver IDs that allow the service to deploy a driver to be uninstalled (set the revision Action to Uninstall) only for drivers originally installed by the WUA agent.

 <s:complexType name="ArrayOfDriverRecoveryID">
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="unbounded" name="DriverRecoveryID" nillable="true" type="s:string" />
     </s:sequence>
   </s:complexType>

§ DriverRecoveryID: A string that indicates that the driver originated from WU. The WUA agent maintains a record of each driver it installs, so that it can be passed up to the server. The format of the string is the update ID of the driver that was installed. The WUA agent SHOULD omit this field for drivers that were installed via other mechanisms <19>.

§ DeviceFlags: A bitmap of various flags for a device. Bit position 0 indicates enumerated by PNP. A value of 0 means a PNP device. A value of 1 indicates not enumerated by PNP device, for example, a printer device.<20>

CachedDriverIDs: The revision IDs of all driver revisions in the client cache. These IDs MUST have been obtained from the UpdateInfo.ID returned from previous calls to this method.

SkipSoftwareSync: Specifies if this request is for a software or driver metadata sync.

FilterCategoryIds: Specifies the list of categories to which the server limits the synchronization. The client MUST NOT send this parameter unless it has specified a protocolVersion greater than or equal to 1.7 during the GetCookie request (section 2.2.2.2.2) and the server specified a ProtocolVersion greater than or equal to 3.2 in the Properties returned in the response to the GetConfig method call (section 2.2.2.2.1). If the client is performing a category scan (as discussed in section 2.2.2.2.8), then the category identifiers in this list MUST be obtained from the response to a call to the StartCategoryScan method (section 2.2.2.2.8). If the client is not performing a category scan, then this list MUST be empty. If this parameter is specified and is not empty, the server MUST return only updates that are related to these categories. Its format is as follows:

       <s:complexType name="ArrayOfCategoryIdentifier">
         <s:sequence>
           <s:element minOccurs="0" maxOccurs="unbounded" name="CategoryIdentifier"
              nillable="true" type="s1:CategoryIdentifier" />
         </s:sequence>
       </s:complexType>

CategoryIdentifier: A GUID identifying a category:

       <s:complexType name="CategoryIdentifier">
         <s:sequence>
           <s:element minOccurs="1" maxOccurs="1" name="Id" type="s2:guid" />
         </s:sequence>
       </s:complexType>

NeedTwoGroupOutOfScopeUpdates: Specifies that the client requires the server to return two sets of out-of-scope updates in the response (documented in the response below). The client MUST NOT send this parameter unless it has specified a protocolVersion greater than or equal to 1.7 during the GetCookie request (section 2.2.2.2.2) and the server specified a ProtocolVersion greater than or equal to 3.2 in the Properties returned in the response to the GetConfig method call (section 2.2.2.2.1).

ComputerSpec: Specifies HardwareIDs for a computer. The HardwareID of a computer contains a list of GUIDs as defined here.

   <s:complexType name="ComputerHardwareSpecification">
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="HardwareIDs" type="s1:ArrayOfGuid" />
     </s:sequence>
   </s:complexType>

FeatureScoreMatchingKey: Each driver package can have different feature scores corresponding to processor architecture and OS version. The key has the format of "Architecture.OSMajorVersion.OSMinorVersion" (for example "AMD64.10.0"), so the service can select the correct feature score from driver packages and decide the best match.

Response:

 <s:element name="SyncUpdatesResponse">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="SyncUpdatesResult" 
          type="s1:SyncInfo" />
     </s:sequence>
   </s:complexType>
 </s:element>

SyncUpdatesResult: Upon successful completion of this operation, this element MUST be returned. The client SHOULD interpret this result, as specified in section 3.1.5.7. Its format is as follows.

 <s:complexType name="SyncInfo">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="NewUpdates"
        type="s1:ArrayOfUpdateInfo" />
     <s:element minOccurs="0" maxOccurs="1" name="OutOfScopeRevisionIDs"
        type="s1:ArrayOfInt" />
     <s:element minOccurs="0" maxOccurs="1" name="ChangedUpdates" 
        type="s1:ArrayOfUpdateInfo" />
     <s:element minOccurs="1" maxOccurs="1" name="Truncated" type="s:boolean" />
     <s:element minOccurs="0" maxOccurs="1" name="NewCookie" type="s1:Cookie" />
     <s:element minOccurs="0" maxOccurs="1" name="DeployedOutOfScopeRevisionIds" 
        type="s1:ArrayOfInt" />
     <s:element minOccurs="0" maxOccurs="1" name="DriverSyncNotNeeded" type="s:string" /> 
   </s:sequence>
 </s:complexType>

NewUpdates: An array of revisions to be added to the client cache. Its format is as follows.

 <s:complexType name="ArrayOfUpdateInfo">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="unbounded" name="UpdateInfo" 
        nillable="true" type="s1:UpdateInfo" />
   </s:sequence>
 </s:complexType>

UpdateInfo: Information about an update revision. Its format is as follows.

 <s:complexType name="UpdateInfo">
   <s:sequence>
     <s:element minOccurs="1" maxOccurs="1" name="ID" type="s:int" />
     <s:element minOccurs="0" maxOccurs="1" name="Deployment" 
        type="s1:Deployment" />
     <s:element minOccurs="1" maxOccurs="1" name="IsLeaf" 
        type="s:boolean" />
     <s:element minOccurs="0" maxOccurs="1" name="Xml" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

ID: Specifies the revision ID of this update revision. This ID will be passed as Parameters.InstalledNonLeafUpdateIDs, Parameters.OtherCachedUpdateIDs, or Parameters.CachedDriverIDs in subsequent calls to this method.

Deployment: Information about how this revision was deployed to this client. Its format SHOULD <21> be as follows.

 <s:complexType name="Deployment">
   <s:sequence>
     <s:element minOccurs="1" maxOccurs="1" name="ID" type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="Action" 
        type="s1:DeploymentAction" />
     <s:element minOccurs="0" maxOccurs="1" name="Deadline" 
        type="s:string" />
     <s:element minOccurs="1" maxOccurs="1" name="IsAssigned" 
        type="s:boolean" />
     <s:element minOccurs="1" maxOccurs="1" name="LastChangeTime" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="DownloadPriority" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="HardwareIds" 
        type="s1:ArrayOfString" />
     <s:element minOccurs="0" maxOccurs="1" name="AutoSelect" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="AutoDownload" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="SupersedenceBehavior" 
       type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="FlagBitmask" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="ClientBehaviors"
        type="tns:ArrayOfClientBehavior" />
   </s:sequence>
 </s:complexType>

ID: The server-assigned ID for this deployment.

Action: The action the client performs on this revision: OptionalInstall, Install, Uninstall, PreDeploymentCheck (which means do not offer the update, just report back on the status), Block (which means that the update MUST NOT be deployed, and is used to override another deployment), Evaluate (which means do not offer the update and do not report back on the status), or Bundle (which means that the update is not be offered for install—it is only deployed because it is bundled by some other explicitly deployed update). Revisions whose assigned Action is OptionalInstall SHOULD NOT be downloaded and installed automatically by the WUA agent, but are expected to be available to end users for explicit approval.<22> For revisions whose assigned Action is Block, the server SHOULD send the revision to the client with an Action value of PreDeploymentCheck. Alternately, the server MAY refrain from sending the revision to the client at all.

The enumeration (DeploymentAction) for this element is as follows:

 <s:simpleType name="DeploymentAction">
   <s:restriction base="s:string">
     <s:enumeration value="OptionalInstall" />
     <s:enumeration value="Install" />
     <s:enumeration value="Uninstall" />
     <s:enumeration value="PreDeploymentCheck" />
     <s:enumeration value="Block" />
     <s:enumeration value="Evaluate" />
     <s:enumeration value="Bundle" />
   </s:restriction>
 </s:simpleType>

Deadline: Optionally specifies the time by which the deployment action SHOULD occur, in the syntax specified for s:dateTime (as specified in [XMLSCHEMA2] section 3.2.7). This field MAY be omitted if there is no deadline.

IsAssigned: If set to TRUE, the revision SHOULD be installed automatically by the client. If set to FALSE, the revision SHOULD be offered to users of the client computer (2) but not automatically installed.

LastChangeTime: Specifies when the deployment was created, in the syntax specified for s:date (as specified in [XMLSCHEMA2] section 3.2.9). This element MUST be present.

DownloadPriority: Specifies a value indicating how the client SHOULD prioritize its downloads of content for this update relative to other updates.

HardwareIds: An optional array of HardwareId values that identify the device hardware supported by this update revision. This SHOULD be present when the deployment is of a device driver and when the protocolVersion reported by the client in the GetCookie call is "1.6" or higher.<23>

AutoSelect: The server MUST NOT send this field if the client protocol version is less than 1.8. If this field is sent, it MUST be set to 0.

AutoDownload: The server MUST NOT send this field if the client protocol version is less than 1.8. If this field is sent, it MUST be set to 0.

SupersedenceBehavior: The server MUST NOT send this field if the client protocol version is less than 1.8. If this field is sent, it MUST be set to 0.

FlagBitmask: The server MUST NOT send this field if the client protocol version is less than 1.8. If this field is sent, it MUST be set to 0.

ClientBehaviors: An optional array of ClientBehavior values that identify the metadata a publisher intended for the client.<24>

 <s:complexType name="ArrayOfClientBehavior"> 
        <s:sequence> 
          <s:element minOccurs="0" maxOccurs="unbounded" name="ClientMetadata"
               nillable="true" type="tns:ClientMetadata" /> 
        </s:sequence> 
      </s:complexType>

IsLeaf: Specifies whether this revision is a leaf in the prerequisite graph.

Xml: The core metadata associated with this revision. The server MUST populate this with metadata. These fragments are created as specified in section 3.1.1. The format of the fragment is opaque to the server.

OutOfScopeRevisionIDs: An array of RevisionIDs that identify revisions to be removed from the client cache. If the client is performing a category scan by specifying a list of FilterCategoryIds and by specifying True for NeedTwoGroupOutOfScopeUpdates in the request, this list shall contain only updates that are no longer deployed by the server.

ChangedUpdates: Changes that SHOULD be applied to the deployment or IsLeaf status for revisions in the client cache.

Truncated: Specifies that the server has truncated the set of new revisions returned. If the results have been truncated, it MUST be set to TRUE to indicate that the client SHOULD call this method again. If the results have not been truncated, it MUST be set to FALSE to indicate that the results have not been truncated, so the client SHOULD only call this method again if the method returns a new UpdateInfo with IsLeaf = FALSE.

NewCookie: An updated cookie that the client SHOULD use in subsequent calls.

DeployedOutOfScopeRevisionIds: A list of updates that are still deployed by the server but that are no longer in scope for the current synchronization. The server MUST NOT return this parameter unless it specified a ProtocolVersion of greater than or equal to 3.2 in the Properties returned in the response to the GetConfig method call (section 2.2.2.2.1) and the client specified that it supports a protocolVersion greater than or equal to 1.7 in the GetCookie request (section 2.2.2.2.2), and only if the client specified True for the NeedTwoGroupOutOfScopeUpdates parameter in the SyncUpdates request.

DriverSyncNotNeeded: Specifies that there are no drivers in scope for the current synchronization and so it is not necessary for the client to perform a driver sync pass. The server MUST NOT return this parameter unless it specified a ProtocolVersion of greater than or equal to 3.2 in the Properties returned in the response to the GetConfig method call (section 2.2.2.2.1) and if the client specified that it supports a protocolVersion greater than or equal to 1.7 in the GetCookie request (section 2.2.2.2.2).

Share via

2.2.2.2.4 SyncUpdates

Additional resources