2.2.2.3.1 ReportEventBatch

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.<18> 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.<19>

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.

 Friendly Name

 Misc Data Tag

 Data Type

 Description

 Associated Event IDs

OSServicePackBuildNumber

A

Int

Client operating system service pack build number.

All events

ByteCount

B

Int

Number of bytes downloaded.

Download success events

RepeatFailFlag

C

Int

Number of times the update has failed to install in the past.

Install failure events

NumberApplicable

D

Int

Number of updates that were explicitly deployable, installable on the client (Needed), and deployed for install.

Detection events

LastError

F

Int

Secondary error code when Win32HResult is not sufficient to diagnose the problem.

Install and download events

ClientVersion

G

Int

Client version.

All events

ClientSamplingValue

J

Int

Random number between 0 and 999 inclusive, chosen once per computer.

All events

BiosName

K

String

Client BIOS name.

All events

BiosReleaseDate

L

DateTime

Client BIOS release date.

All events

EventType

Q

Int

If this is an install or download event, and the update being reported on is a bundle, then 2. Else 1.

All events

TargetClientVersion

S

String

WUA agent version that the agent is self-updating to.

Self-update events

InstallableUpdateIDs

U

List of GUIDs separated by ;

IDs of updates that were deployed for install, uninstall, or scan, that were found to be installable (Needed).

Status events

InstalledUpdateIDs

V

List of GUIDs separated by ;

IDs of updates that were deployed for install, uninstall, or scan, that were found to be installed.

Status events

InstalledPendingRebootIDs

W

List of GUIDs separated by ;

IDs of updates that were deployed for install, uninstall, or scan, that were found to be installed, but require reboot before taking effect.

Status events

FailedUpdateIDs

g

List of GUIDs separated by ;

IDs of updates that were deployed for install, uninstall, or scan, that were found to need installing or uninstalling, but the attempt to download, install, or uninstall the update has failed.

Status events

DownloadedUpdateIDs

h

List of GUIDs separated by ;

IDs of updates that were deployed for install, that were downloaded to the client but not yet installed.

Status events

MSIAction

X

String

A Microsoft Windows Installer (MSI) action that failed.

MSI/MSP install failure events

MSITransactionCode

Y

GUIDs

Unique ID identifying the transaction that the update was part of.

MSI/MSP install failure events

MSIProductCode

Z

GUIDs

Product code of the MSP.

MSI/MSP install failure events

MSIErrorRec

f

int

Extended MSI error code.

MSI/MSP install failure events

SelfUpdatePackageName

a

String

The name of the self-update package.

Self-update events

OSProductType

c

Int

Client operating system ProductType. The value provided in the OSProductType tag is implementation-specific. <20>

All events, if client is Windows Vista operating system or later

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.

 Name

 Event ID

 Description

 Remarks

 English message template

Detection Events

AGENT_DETECTION_FINISHED

147

Detection succeeded.

Agent has finished detecting items.

AGENT_DETECTION_FAILED

148

Detection failed.

Error: Agent failed detecting with reason: %1.

Status Events

AGENT_STATUS

153

Reports status of all updates to MS-WUSP 2.0.

Reporting client status.

AGENT_STATUS_30

156

Reports status of all updates to MS-WUSP 3.0.

This event is new in version 3.0 of the protocol.

Reporting client status.

Download Events

AGENT_DOWNLOAD_FAILED

161

Download failed.

Error: Download failed.

AGENT_DOWNLOAD_SUCCEEDED

162

Download succeeded.

Download succeeded.

AGENT_DOWNLOAD_CANCELED

163

Download canceled.

Download canceled.

Install Events

AGENT_INSTALLING_FAILED

182

User-initiated installation failed.

Installation Failure: Windows failed to install the following update with error %1: %2.

AGENT_INSTALLING_SUCCEEDED

183

User-initiated installation succeeded.

Installation Successful: Windows successfully installed the following update: %1.

AGENT_INSTALL_COMPLETE_

WITH_REBOOT

184

User-initiated installation succeeded, requires reboot.

Installation successful and restart required for the following update: %1.

AGENT_INSTALL_CANCEL

186

User-initiated installation canceled.

User canceled the installation.

AGENT_INSTALL_KILLED

187

User-initiated installation timed out, was terminated by the WUA.

Installation killed: Installation of the following update is killed by the agent: %2.

AU_SCHEDULED_INSTALL_SUCCESS

190

Scheduled installation succeeded.

Installation Successful: Windows successfully installed the following update: %1.

AU_SCHEDULED_INSTALL

_COMPLETE_WITH_REBOOT

191

Scheduled installation succeeded, requires reboot.

Installation successful and restart required for the following update: %1.

AU_SCHEDULED_INSTALL_KILLED

192

Scheduled installation timed out, was terminated by the WUA.

Installation killed: Installation of the following update is killed by the agent: %2

AU_SCHEDULED_INSTALL_FAILED

195

Scheduled installation failed.

Installation Failure: Windows failed to install the following update with error %1: %2.

AU_SHUTDOWN_INSTALL_SUCCESS

197

Install at shutdown succeeded.

Installation Successful: Windows successfully installed the following update: %1.

AU_SHUTDOWN_INSTALL_FAILED

198

Install at shutdown failed.

Installation Failure: Windows failed to install the following update with error %1: %2.

AU_SHUTDOWN_INSTALL_COMPLETE

_WITH_REBOOT

199

Install at shutdown succeeded, requires reboot.

Installation successful and restart required for the following update: %1.

AU_SHUTDOWN_INSTALL_KILLED

200

Install at shutdown timed out, was terminated by the WUA.

Installation killed: Installation of the following update is killed by the agent: %2.

AGENT_INSTALLING_FAILED

_POST_REBOOT

203

Post-reboot processing of an installed update failed.

New to Windows Vista

Installation Failure Post Reboot.

AGENT_UNINSTALLING_FAILED

221

Uninstallation failed.

Uninstallation Failure: Windows failed to uninstall the following update with error %1: %2.

AGENT_UNINSTALLING_SUCCEEDED

222

Uninstallation succeeded.

Uninstallation Successful: Windows successfully uninstalled the following update: %1.

AGENT_UNINSTALL_CANCEL

223

Uninstallation canceled.

User canceled the uninstall.

AGENT_UNINSTALL_COMPLETE

_WITH_REBOOT

224

Uninstallation succeeded, requires reboot.

Uninstallation successful and restart required for the following update: %1.

AGENT_UNINSTALL_KILLED

225

Uninstallation timed out, was terminated by the WUA.

Uninstallation killed: Uninstallation of the following update is killed by the agent: %2.

Update Hidden/Unhidden Events

AGENT_INSTALL_HIDE

185

User chose to hide the update from the UI.

Hide update: user hid one update.

AGENT_INSTALL_UNHIDE

196

User chose to unhide the update from the UI.

Unhide update: user unhide one update.

Misc Events

AGENT_INSTALLING_PENDING

201

Self-update is about to begin.

Installation pending.

AU_REBOOT_COMPLETED

202

Client computer has finished rebooting following an install/uninstall.

Reboot completed.

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.

Show: