Software Distribution Channel APIs

Software Distribution Channel APIs


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.

arrowy.gifUsing the Software Distribution Channel APIs

arrowy.gifFunctions

arrowy.gifStructures

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.

Software Update Message Box

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.
    }
}

Functions

The following section contains the software distribution channel APIs.

GetSoftwareUpdateInfo

HRESULT GetSoftwareUpdateInfo(
    LPCWSTR szDistUnit,
    LPSOFTDISTINFO psdi
);

Retrieves the version information about the specified distribution unit.

szDistUnit
String value containing the identifier for the code distribution unit. For ActiveX™ Controls, this string is typically a GUID.
psdi
Address of the SOFTDISTINFO structure to store the update information. The cbSize member of the structure must be initialized to the size of the SOFTDISTINFO structure.

SetSoftwareUpdateAdvertisementState

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.

szDistUnit
String value containing the identifier for the code distribution unit. For ActiveX™ Controls, this string is typically a GUID.
dwAdState
Unsigned long integer value that contains the advertisement state. Can be one of the following values:
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.
dwAdvertisedVersionMS
Unsigned long integer value that contains the most significant unsigned long integer value of the version number of the latest version that the user has been informed about.
dwAdvertisedVersionLS
Unsigned long integer value that contains the least significant unsigned long integer value of the version number of the latest version that the user has been informed about.

SoftwareUpdateMessageBox

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.

hWnd
Handle of the parent window.
szDistUnit
String value containing the identifier for the code distribution unit. For ActiveX™ Controls, this string is typically a GUID.
dwFlags
Reserved. Must be set to zero.
psdi
Address of the SOFTDISTINFO structure to store the update information. The cbSize member of the structure must be initialized to the size of the SOFTDISTINFO structure.

Structures

The following section contains the structures used by the software distribution channel APIs.

SOFTDISTINFO

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.

cbSize
Unsigned long integer value that contains the size of the structure.
dwFlags
Unsigned long integer value containing the flags. Can be one of the following values:
SOFTDIST_FLAG_USAGE_EMAIL
SOFTDIST_FLAG_USAGE_PRECACHE
SOFTDIST_FLAG_USAGE_AUTOINSTALL
SOFTDIST_FLAG_DELETE_SUBSCRIPTION
dwAdState
Unsigned long integer value that contains the advertisement state. Can be one of the following values:
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.
szTitle
String value that contains the contents of the TITLE tag from the associated CDF file.
szAbstract
String value that contains the contents of the ABSTRACT tag from the associated CDF file.
szHREF
String value that contains the URL of the Web page to advertise the update or to install the update.
dwInstalledVersionMS
Unsigned long integer value that contains the most significant unsigned long integer value of the version number of the installed version.
dwInstalledVersionLS
Unsigned long integer value that contains the least significant unsigned long integer value of the version number of the installed version.
dwUpdateVersionMS
Unsigned long integer value that contains the most significant unsigned long integer value of the version number of the update version.
dwUpdateVersionLS
Unsigned long integer value that contains the least significant unsigned long integer value of the version number of the update version.
dwAdvertisedVersionMS
Unsigned long integer value that contains the most significant unsigned long integer value of the version number of the latest version that the user has been informed about.
dwAdvertisedVersionLS
Unsigned long integer value that contains the least significant unsigned long integer value of the version number of the latest version that the user has been informed about.
dwReserved
Reserved. Must be set to zero.

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.