Explorering Windows APIs: WUA

Explorering Windows APIs; WUA

Windows XP SP2 introduced a new API for managing = the Windows Update Service. As with many a new API this one is com-callable and therefore can be used from Visual Objects applications. In this article I = would like to present an example for getting you started. The API however is reasonably complex and powerful and there’s much more to explore. You might want to have a good look at the reference documentation in detail on= MSDN to see what else is on the menu and to your liking. The sample presented h= ere searches updates, presents them in a modern XP-style UI and allows the use= r to select and install updates selectively. It will also show you how to check= for installed updates and install them programmatically when you need that.

Before we dive into the VO-code= a little about the Windows Update Service. This is actually a website and service available to all Windows us= ers. You’ve probably seen it. It is where the system takes you when you h= it that Windows Update menu option. At this moment (may 2005) it is still all Windows, and there a different procedure for Office = for example, but this will soon change. There are also different versions of t= he Update service itself. I have tested the Interface using version 6. (beta) The interesti= ng thing about all of this though is that in the near future we will be able = to have a Service like this running on our own internal servers (WSUS) and it= will available for other products as well. Microsoft plans on releasing the next version as “Microsoft&#= 8221; update service (so not Windows anymore) which will also support Office, SQL Server and Exchange initially but should open up to all current products a= nd third parties. So Microsoft is pushing this technology hard and at the tim= e of writing (May 2005) there is even a new version (in beta) of the update Ser= vice and a .net version of the Client API.&nbs= p; When looking at the published documentation for this I found notices that the documentation is still Microsoft confidential, however it is actu= ally publicly available on Microsoft.com as of April 2005. All in all more than enough reasons I think to seriously have a look at this technology.=

To begin with for those of you that like to dive = right in and get your hands dirty I have included a Demo application written in Visual Objects 2.7b-1 which demonstrates how to query the Service for upda= tes, allows you to select a specific update and install it= for you.

Below is a picture of the Main dialog window of t= his application listing a few updates ready for installati= on.

It also shows how to apply L= istview grouping and a background image as provided by Windows XP styles.

Visiting the Windows Update Website for the first= time installs the Client, a DLL called WUAPI.DLL which you will find in your System32 directory. You can use this or WUAENG.DLL (the engine) to find out what version you have installed. It should be 5.4.3790.1000 or greater. From VO all you need to do is gen= erate Automation Wrapper classes using Tools, Automation server to be bale to start using the object model. Well, eh that = and study the documentation which you will find on MSDN. Although a lot of the samples are in Windows-script they are pret= ty good and fairly easy to translate into VO code.

First of all we can inspect or change the user specific settings, we’ll do that the easy way by popping up the UI Windows XP now has for that. The code for that is very straight forward, just instantiate the IAutomaticUpdates object and call the ShowSettingsDialog method. As you can see I prefixed my generated class with WUA_ to easily differentiate them from others I might use. Actually I’m pretty happy with the work the VO development team did on the Automation server code generation tool. They have gotten rid of many annoying ‘featuresR= 17; it had, if you haven’t seen or used it for a while it is worth having another look. Here’s the code I needed for showing that dialog.

METHOD ShowSettings( ) CLASS MainDialog

LOCAL oUSettings AS WUA_IAutoma= ticUpdates

oUSettings= :=3D WUA_= IAutomaticUpdates{}

oUSettings:ShowSettingsDialog()

RETURN SELF

You can now tell your users to switch it off completely and build them a nice application that handles the process for = them in Visual Objects.

So we are now ready for the more serious stuff, starting with querying the update information from the server. For this we= need the IUpdateSession object or “Interface&= #8221; if you prefer. We use that to create an IUpdateSearch= er object that has a search method which accepts a query string. The query st= ring will be used to specify what kind of updates you would like to see.

I must admit the documentation on the syntax to u= se is a bit complex but with a bit of exploring samples and testing I had the ba= sic thing working quickly. It’s clear that things can be added to this by Microsoft fairly easily and they probably intend to judging by the remarks in the very fresh documentation.=

The string "IsInstalled= =3D0 and Type=3D'Software'" gives you all not installed software updates t= hat are available, obviously when you leave out IsInstalled you will also get already installed updates allowing you to have a look at= the update history.

The results are passed back to you using an ISearchResult object which if it was successful has a collection of IUpdate Items. So simplified you= could end up with something like this to build a listview of IUpdate items:

METHOD GetUpdateInfo( ) CLASS MainDialog

LOCAL updateSearcher AS WUA_IUp= dateSearcher

LOCAL searchResult AS WUA= _ISearchResult

LOCAL update = AS WUA= _IUpdate

LOCAL I AS DWORD

SELF:Pointer :=3D Pointer{POINTERHOURGLASS}=

SELF:updateSession :=3D WUA_= IUpdateSession{}

// Issue a search

updateSearcher :=3D upda= teSession:CreateupdateSearcher()

searchResult :=3D upda= teSearcher:Search("IsInstalled=3D0") //and Type=3D'Software'"= )

SELF:oDClvUpdates:DeleteAll()

FOR I =3D 0 TO searchResult:Updates:Count-1<= span style=3D'font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareas= t-font-family: "Times New Roman"'>

u= pdate :=3D searchResult:Updates:[Item,I]

= SELF:oDClvUpdates:AddItem(update)

SELF:Pointer :=3D Pointer{POINTERARROW}

SELF:oDClvUpdates:SetFocus()

RETURN SELF

You can query the Resultcode= property of ISearchResult for <> S_OK an= d query the Warnings collection for info on what’s happening.

The UpdateItems conta= in all kinds of properties to display details about them, I am using the Descript= ion property for display purposes (in the ListviewItemCha= nged method) and IsBeta and Ma= xdownloadsize as column information. I use the Downloadpriority to set grouping options for the Listview.<= span style=3D'font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareas= t-font-family: "Times New Roman"'>

After we have a list of candidates for installati= on we need to download them. For this there is an IUpdateDo= wnloader interface which can not be instantiated but is created for you by calling the Session’s Create= UpdateDownloader method which is why in the previous code the Session-object was put in an = IVar of the Dialog in stead of a local. You tell the Downloader which updates you need by providing a colle= ction of Updateitems which in turn are created by ca= lling Add on this collection using the names of the updates.

Calling the Download method on the UpdateDownloader returns a DownloadResult object that can be interrogated to find out if the download was successful or a reason of fai= lure when something went wrong. The same routine will be needed for actual installation, using an UpdateInstaller class. = The code in the sample is synchronous but the object model also provides a-synchronous methods so you could do the downloading and installing in the background. Below is the code I used to download and install.

METHOD InstallSelectedUpdate( ) CLASS MainDialog

LOCAL oTb = ; = ; AS TextBox &= nbsp;

LOCAL cInfo &n= bsp; &nbs= p; AS STRING

LOCAL updateToInstall AS WUA_= IUpdateCollection

LOCAL downloader &n= bsp; AS WUA_IUpdateDownloader

LOCAL downloadResult= AS WUA_IDownloadResult

LOCAL installer &nb= sp; = ; AS = WUA_IUpdateInstaller

LOCAL installationResult AS WUA= _IInstallationResult

LOCAL oListViewItem&= nbsp; AS ListviewI= tem

updateToInstall:=3DWUA_IU= pdateCollection{}

oListViewItem :=3D SELF= :oDClvUpdates:GetSelectedItem()

IF oListViewItem # NULL_OBJECT

SELF:oCCInstallSelectedUpdate:Disable()

updateToInstall:Add( oListviewItem:GetValue(#Title) )

cInfo :=3D oListviewItem:GetText(#Title)

oTb :=3D T= extBox{SELF,"Confirm",;

= <= /span> = ; "Would you like to download and install "+;

cInfo+"= now? ",BUTTONOKAYCANCEL+BOXICONQUESTIONMARK}

IF oTb:Show() =3D=3D BOXREPLYOKAY

downloader :=3D updateSession:CreateUpdateDownloader()

downloader:Updates :=3D u= pdateToInstall

SELF:oCCShowSettings:Disable()

SELF:oCCGetUpdateInfo:Disable()

SELF:oDClvUpdates:Disable()

SELF:Pointer :=3D Pointer{POINTERHOURGLASS}=

SELF:oDCDescription:Textvalue :=3D "Downloading..."+CRLF=

DoEvents()

downloadResult :=3D downl= oader:Download()

SELF:oDCDescription:Textvalue +=3D "Download = Result: " +;

= ; ResultString= (downloadResult:ResultCode) + CRLF

SELF:oDCDescription:Textvalue +=3D "Installing update..." + CRLF

DoEvents()

installer :=3D updateSession:CreateUpdateInstaller()

installer:Updates :=3D up= dateToInstall

installationResult :=3D i= nstaller:Install()

SELF:oDCDescription:Textvalue +=3D "Installat= ion Result: " +;

= ; ResultString= (installationResult:ResultCode) + CRLF

DoEvents()

IF installationResult:RebootRequired

= Infobox{SELF,"Attention",;

&qu= ot;You Should re-boot now. (not a= utomatic ;-))"}:Show()

ENDIF

SELF:Pointer :=3D Pointer{POINTERARROW}

SELF:oCCInstallSelectedUpdate= :Enable()

SELF:oCCShowSettings:Enable()

SELF:oCCGetUpdateInfo:Enable<= /span>()

SELF:oDClvUpdates:Enable()

RETURN SELF

This covers the basics you need to know to get started. Additionally I have created a sample that allows you to research = the various Search expressions and one that that displays all properties of the Update items.

Search tester

WUASearchDialog.AEF is a sample application that allows us to experiment with different values as a parameter for the Updatesearcher search method. The SDK helpfile (WUA_SDK.CHM) has got a good table explaining the different options. You c= an download the SDK as a .chm or look it up on MS= DN.

Update Inspector

Double clicking on an update item in the WUASearchDialog app opens a detail dialog showing ma= ny available properties of the Update items demonstrating how to inspect an u= pdate item. I am sure you can think of interesting things to do with these Update items yourself.

Conclusion

We have only scratched the surface of what this A= PI is capable of and what Microsoft intends to offer in the future. In particula= r in situations where you need more control over when and how updates are insta= lled or when Microsoft decides to open this up for third parties (us) this API = will be of great value. It is also a very interesting way to explore OLE-client application development in Visual Objects using the well designed object m= odel WUA offers.

Interesting links:

Links to the SDK’s:

http://www.microsoft.com/windowsserversystem/updateservices/t= echinfo/default.mspx

http://wsuswiki.com/=

http://www.microsoft.com/windowsserversystem/updateservices/d= efault.mspx

Appendix A

Windows Update Agent API, what Microsoft says:=

Purpose

The Windows® Update Agent (WUA) API is a set = of COM interfaces that enable programmers to access Windows Update. Scripts or programs can be written to examine which updates are currently available f= or a computer, and install or uninstall updates.

This documentation describes a preliminary versio= n of the WUA API available with Windows XP SP2. Note that this preliminary vers= ion of the WUA API can be used to scan for updates on the local computer only. The capability to remotely scan the updates needed by other computers on a net= work, for example by using DCOM, has been disabled in this preliminary version.<= /span>

Where Applicable

System administrators can use WUA to programmatic= ally determine which updates should be applied to a computer, download those updates, and install them with little or no user intervention.

Independent software vendors (ISV) and end-user d= evelopers can integrate WUA features into computer management or patch management software to provide a seamless operating environment.

Developer Audience

You can write WUA applications in several languag= es. WUA defines interfaces and objects that are accessible from Visual Basic, Visual Basic Scripting Edition (VBScript), JScript, and from C and C++. A familiarity with COM programming is useful to the WUA programmer.

Run-Time Requirements

WUA requires Windows XP or Windows 2000 Professio= nal SP3. It also assumes the Windows Update Agent is installed on the client computer. This is done automatically when you visit the Update Website the first time (http://v5.windowsupdate.microsoft.com/v5consumer/default.aspx?ln=3Den-us)= .