2.2.2.3.1 ReportEventBatch

• 11/23/2020
• 10 minutes to read

Synopsis:

This method is invoked by a client to report the occurrence of one or more software-update–related events.

 <wsdl:operation name="ReportEventBatch" />

The SOAP operation is defined as follows.

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

Request:

 <s:element name="ReportEventBatch">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="cookie" 
          type="s1:Cookie" />
       <s:element minOccurs="1" maxOccurs="1" name="clientTime" 
          type="s:dateTime" />
       <s:element minOccurs="0" maxOccurs="1" name="eventBatch" 
          type="s1:ArrayOfReportingEvent" />
     </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 (section 2.2.2.2.4). This element MUST be present.

clientTime: The current time (when this method was called) on the client in Coordinated Universal Time (UTC).

eventBatch: An array of ReportingEvents. Its format MUST be as follows.

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

ReportingEvent: Specifies information of an update-related event. Its format MUST be as follows.

 <s:complexType name="ReportingEvent">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="BasicData" 
        type="s1:BasicData" />
     <s:element minOccurs="0" maxOccurs="1" name="ExtendedData" 
        type="s1:ExtendedData" />
     <s:element minOccurs="0" maxOccurs="1" name="PrivateData" 
        type="s1:PrivateData" />
   </s:sequence>
 </s:complexType>

BasicData: Generic data provided for all events. Its format (BasicData) MUST be as follows.

 <s:complexType name="BasicData">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="TargetID" 
        type="s1:ComputerTargetIdentifier" />
     <s:element minOccurs="1" maxOccurs="1" name="SequenceNumber" 
        type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="TimeAtTarget" 
        type="s:dateTime" />
     <s:element minOccurs="1" maxOccurs="1" name="EventInstanceID" 
        type="s2:guid" />
     <s:element minOccurs="1" maxOccurs="1" name="NamespaceID" 
        type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="EventID" 
        type="s:short" />
     <s:element minOccurs="1" maxOccurs="1" name="SourceID" 
        type="s:short" />
     <s:element minOccurs="0" maxOccurs="1" name="UpdateID" 
        type="s1:UpdateRevisionIdentifier" />
     <s:element minOccurs="1" maxOccurs="1" name="Win32Hresult" 
        type="s:int" />
     <s:element minOccurs="0" maxOccurs="1" name="AppName" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

TargetID: The identity of the client computer (same as the clientID parameter to GetAuthorizationCookie (section 2.2.2.1.1)). Its format (ComputerTargetIdentifier) MUST be as follows.

 <s:complexType name="ComputerTargetIdentifier">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="Sid" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

Sid: A ClientIdString that MUST match the string used as the clientId parameter to GetAuthorizationCookie (section 2.2.2.1.1).

SequenceNumber: Unused. MUST be set to 0, and MUST be ignored upon receipt.

TimeAtTarget: The time in Coordinated Universal Time (UTC) when the event was recorded by the client.

EventInstanceID: A GUID generated by the client to uniquely identify this occurrence of this event.

NamespaceID: MUST be set to 1 by all clients. The server MAY ignore events with other values.

EventID: This SHOULD be set to a numeric value that identifies the type of the event that occurred on the client. This numeric value SHOULD be one of the EventID numbers specified in the EventID Table in this section.

SourceID: Defines the subcomponent within the client that generated the event.

UpdateID: Optionally specifies the ID of the update related to this occurrence of this event, for events related to a particular update. If the event is not associated with any particular update, it MUST be specified as {00000000-0000-0000-0000-000000000000}. Its format (UpdateRevisionIdentifier) MUST be as given below.

 <s:complexType name="UpdateRevisionIdentifier">
   <s:sequence>
     <s:element minOccurs="1" maxOccurs="1" name="UpdateID" 
        type="s2:guid" />
     <s:element minOccurs="1" maxOccurs="1" name="RevisionNumber" 
        type="s:int" />
   </s:sequence>
 </s:complexType>

UpdateID: A GUID that uniquely identifies an update.

RevisionNumber: A number that specifies the version of the update identified by this revision.

Win32Hresult: Optionally specifies a Win32 HRESULT code for events that correspond to a failure. Win32 HRESULT codes are specified in [MS-ERREF].

AppName: The name of the application that triggered the client to perform the operation.

ExtendedData: Additional data associated with an event. Its format (ExtendedData) MUST be as given below.

 <s:complexType name="ExtendedData">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="ReplacementStrings" 
        type="s1:ArrayOfString" />
     <s:element minOccurs="0" maxOccurs="1" name="MiscData" 
        type="s1:ArrayOfString" />
     <s:element minOccurs="0" maxOccurs="1" name="ComputerBrand" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="ComputerModel" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="BiosRevision" 
        type="s:string" />
     <s:element minOccurs="1" maxOccurs="1" name="ProcessorArchitecture" 
        type="s1:ProcessorArchitecture" />
     <s:element minOccurs="1" maxOccurs="1" name="OSVersion" 
        type="s1:DetailedVersion" />
     <s:element minOccurs="1" maxOccurs="1" name="OSLocaleID" 
        type="s:int" />
     <s:element minOccurs="0" maxOccurs="1" name="DeviceID" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

ReplacementStrings: Specifies an array of strings to be used as parameters in expanding parameterized message strings. Parameterized message strings are message strings that contain placeholders into which instance-specific strings are inserted to obtain an expanded message string. Its format MUST be as follows.

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

MiscData: Additional data not covered by the properties listed here. These MUST be specified in the form "x=value" where x is called a tag.<21> See the MiscData table below for information on such well-known tags.

ComputerBrand: Client computer manufacturer.

ComputerModel: Client computer model name.

BiosRevision: Client BIOS firmware revision.

ProcessorArchitecture: Client CPU architecture. The value MUST be one of those enumerated. Note that this differs from the ProcessorArchitecture element used in the RegisterComputer method, described in section 2.2.2.2.3.

 <s:simpleType name="ProcessorArchitecture">
   <s:restriction base="s:string">
     <s:enumeration value="Unknown" />
     <s:enumeration value="X86Compatible" />
     <s:enumeration value="IA64Compatible" />
     <s:enumeration value="Amd64Compatible" />
   </s:restriction>
 </s:simpleType>

OSVersion: Client operating system version. Its format (DetailedVersion) MUST be as follows.

 <s:complexType name="DetailedVersion">
   <s:sequence>
     <s:element minOccurs="1" maxOccurs="1" name="Major" type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="Minor" type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="Build" type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="Revision" type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="ServicePackMajor" 
        type="s:int" />
     <s:element minOccurs="1" maxOccurs="1" name="ServicePackMinor" 
        type="s:int" />
   </s:sequence>
 </s:complexType>

The values provided by the client are implementation-specific.<22>

OSLocaleID: The client operating system locale.

DeviceID: An event-dependent string.

• MUST be a zero-length string if the associated update is not a driver. How the client can determine if an update is a driver is specified in section 3.1.1.

• If EventID indicates a download driver success/failure event, MUST be set to "1".

• If EventID indicates a driver install success/failure event, MUST be set to a non-empty string whose format is opaque to the server.

• Else, MUST be a zero-length string.

PrivateData: This field MUST be present and empty, and MUST be ignored upon receipt. Its format (PrivateData) is as follows.

 <s:complexType name="PrivateData">
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="ComputerDnsName" 
        type="s:string" />
     <s:element minOccurs="0" maxOccurs="1" name="UserAccountName" 
        type="s:string" />
   </s:sequence>
 </s:complexType>

ComputerDnsName: This field MUST be a zero-length string.

UserAccountName: This field MUST be a zero-length string.

MiscData Table

This table defines the tags, their descriptions, and the events for which such tags are used by WUA to populate the MiscData element within a ReportingEvent.

EventID Table

This table specifies the list of events that WUA reports to a Windows Server Update Services (WSUS) server. The Name column is a friendly name for the event type, EventID is the numeric identifier used in ReportingEvent, and the English message template is the message that could be shown to the end user for this event type. Where a message template is parameterized (%1, %2, and so on), the WSUS server populates the placeholders with content from the ReplacementStrings element of the ReportingEvent. The placeholders are specified starting with %1 and are not recursively evaluated. The <ReplacementStrings> array MUST contain the same number of elements as the number of placeholders specified in the parameterized message.

Response:

 <s:element name="ReportEventBatchResponse">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="1" maxOccurs="1" name="ReportEventBatchResult" 
          type="s:boolean" />
     </s:sequence>
   </s:complexType>
 </s:element>

ReportEventBatchResult: Upon successful completion of this operation, this MUST be returned. Its value MUST be TRUE if the events were successfully received by the server. Otherwise, it MUST be FALSE.