
The software distribution channel APIs assist applications with the notification and installation of software updates using the Open Software Description (OSD) format.
The OSD format uses an OSD file. That file, which is written in the Extensible Mark-up Language (XML), contains the installation instructions for the software.
Software updates and their associated OSD file are compressed in a Cabinet (CAB) file and signed. The application developer can create a software distribution channel, using a Channel Definition Format (CDF) file. The developer can subsequently notify users of updates through the software distribution channel. Depending on the security settings, the user's computer may download the update or just notify the user that the update is available. If the update is downloaded, the user's system can either install it automatically (following the instructions in the OSD file) or wait for the user to accept the update.
The software distribution channel APIs allow an application to notify the user of an update using a standard dialog box or create a customized notification or update process.
For more information about software distribution channels, see Creating Software Distribution Channels.
Using the Software Distribution Channel APIs
Developers of client applications and controls that plan to use software distribution channels to provide their users with updated versions of their products must include code to check for software updates reported by the software distribution channel.
The SoftwareUpdateMessageBox function provides a standard dialog box that can be used by any client application or control to notify the user of an update. The client application or control provides an identifier string and an initialized SOFTDISTINFO structure to the function and calls the GetSoftwareUpdateInfo function to retrieve the information about the installed version, update version, and advertised version.
The installed version is the version currently installed on the user's computer. The update version is the latest version reported by the software distribution channel. The advertised version is the last version that the user was notified about.
The SoftwareUpdateMessageBox function then displays the following dialog box to notify the user of a software update.
If the user chooses to update their software now, the client application should go to the Web page that is indicated in the SOFTDISTINFO structure.
The following sample demonstrates how to call the GetSoftwareUpdateInfo function.
HWND hwnd; //Handle of the parent window.
SOFTDISTINFO psdiUpdateInfo;
LPCWSTR szDistUnitID; // Contains the identifier of the distribution unit.
int intResponse;
// Initialize structure.
psdiUpdateInfo.cbSize = sizeof(SOFTDISTINFO);
// Call function.
intResponse = SoftwareUpdateMessageBox(hwnd, szDistUnitID, 0, &psdiUpdateInfo);
switch(intResponse)
{
case IDYES:
{
//Insert code that navigates to the Web page at psdiUpdateInfo.szHREF.
}
case IDABORT:
{
//Insert code to check the error by calling GetSoftwareUpdateInfo.
}
}
The following section contains the software distribution channel APIs.
HRESULT GetSoftwareUpdateInfo(
LPCWSTR szDistUnit,
LPSOFTDISTINFO psdi
);
Retrieves the version information about the specified distribution unit.
HRESULT SetSoftwareUpdateAdvertisementState(
LPCWSTR szDistUnit,
DWORD dwAdState,
DWORD dwAdvertisedVersionMS,
DWORD dwAdvertisedVersionLS
);
Updates the version information of the latest update that the user has been notified about.
| 0 | Update available dialog box has not been presented to the user. |
| 1 | Files downloaded dialog box has not been presented to the user. |
| 2 | Program installed dialog box has not been presented to the user. |
int SoftwareUpdateMessageBox (
HWND hWnd,
LPCWSTR szDistUnit,
DWORD dwFlags,
LPSOFTDISTINFO psdi
);
Provides a standard dialog box for alerting the user that a software update is available.
| IDNO | The user clicked on the "Don't Update" button on the dialog box. |
| IDYES | The user clicked on the "Update Now" or "About Update" button. The application should navigate to the HTML page referred to by the szHREF member of the SOFTDISTINFO structure to initiate the install or learn more about the update. |
| IDIGNORE | No pending software update. |
| IDABORT | An error occurred. Call GetSoftwareUpdateInfo for a more specific HRESULT. |
The following section contains the structures used by the software distribution channel APIs.
typedef struct _TagSOFTDISTINFO {
ULONG cbSize;
DWORD dwFlags;
DWORD dwAdState;
LPWSTR szTitle;
LPWSTR szAbstract;
LPWSTR szHREF;
DWORD dwInstalledVersionMS;
DWORD dwInstalledVersionLS;
DWORD dwUpdateVersionMS;
DWORD dwUpdateVersionLS;
DWORD dwAdvertisedVersionMS;
DWORD dwAdvertisedVersionLS;
DWORD dwReserved;
} SOFTDISTINFO, *LPSOFTDISTINFO;
Contains the information about a software update.
| SOFTDIST_FLAG_USAGE_EMAIL |
| SOFTDIST_FLAG_USAGE_PRECACHE |
| SOFTDIST_FLAG_USAGE_AUTOINSTALL |
| SOFTDIST_FLAG_DELETE_SUBSCRIPTION |
| 0 | Update available dialog box has not been presented to the user. |
| 1 | Files downloaded dialog box has not been presented to the user. |
| 2 | Program installed dialog box has not been presented to the user. |
The most significant unsigned long integer of a version number contains the major version and minor version numbers. The least significant unsigned long integer of the version number contains the custom version number and the build number.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.