IEmptyVolumeCache2::InitializeEx method (emptyvc.h)

Initializes the disk cleanup handler. It provides better support for localization than Initialize.

Syntax

HRESULT InitializeEx(
  [in]      HKEY    hkRegKey,
  [in]      LPCWSTR pcwszVolume,
  [in]      LPCWSTR pcwszKeyName,
  [out]     LPWSTR  *ppwszDisplayName,
  [out]     LPWSTR  *ppwszDescription,
  [out]     LPWSTR  *ppwszBtnText,
  [in, out] DWORD   *pdwFlags
);

Parameters

[in] hkRegKey

Type: HKEY

A handle to the registry key that holds the information about the handler object.

[in] pcwszVolume

Type: LPCWSTR

A pointer to a null-terminated Unicode string with the volume root—for example, "C:".

[in] pcwszKeyName

Type: LPCWSTR

A pointer to a null-terminated Unicode string with the name of the handler's registry key.

[out] ppwszDisplayName

Type: LPWSTR*

A pointer to a null-terminated Unicode string with the name that will be displayed in the disk cleanup manager's list of handlers. You must assign a value to this parameter.

[out] ppwszDescription

Type: LPWSTR*

A pointer to a null-terminated Unicode string that will be displayed when this object is selected from the disk cleanup manager's list of available disk cleaners. You must assign a value to this parameter.

[out] ppwszBtnText

Type: LPWSTR*

A pointer to a null-terminated Unicode string with the text that will be displayed on the disk cleanup manager's Settings button. If the EVCF_HASSETTINGS flag is set, you must assign a value to ppwszBtnText. Otherwise, you can set it to NULL.

[in, out] pdwFlags

Type: DWORD*

Flags that are used to pass information to the handler, and back to the disk cleanup manager.

These flags can be passed in to the object:

EVCF_OUTOFDISKSPACE

If this flag is set, the user is out of disk space on the drive. When this flag is received, the handler should be aggressive about freeing disk space, even if it results in a performance loss. The handler, however, should not delete files that would cause an application to fail, or the user to lose data.

EVCF_SETTINGSMODE

If the disk cleanup manager is run on a schedule, it will set the EVCF_SETTINGSMODE flag. You must assign values to the ppwszDisplayName and ppwszDescription parameters. If this flag is set, the disk cleanup manager will not call GetSpaceUsed, Purge, or ShowProperties. Because Purge will not be called, cleanup must be handled by InitializeEx. The handler should ignore the pcwszVolume parameter and clean up any unneeded files regardless of what drive they are on. Because there is no opportunity for user feedback, only those files that are extremely safe to clean up should be touched.

These flags can be passed by the handler back to the disk cleanup manager:

EVCF_DONTSHOWIFZERO

Set this flag when there are no files to delete. When GetSpaceUsed is called, set the pdwSpaceUsed parameter to zero, and the disk cleanup manager will omit the handler from its list.

EVCF_ENABLEBYDEFAULT

Set this flag to have the handler checked by default in the disk cleanup manager's list. The handler will be run every time the disk cleanup utility runs, unless the user clears the handler's check box. Once the check box has been cleared, the handler will not be run until the user selects it again.

EVCF_ENABLEBYDEFAULT_AUTO

Set this flag to have the handler run automatically during scheduled cleanup. This flag should only be set when deletion of the files is low-risk. As with EVCF_ENABLEBYDEFAULT, the user can choose not to run the handler by clearing its check box in the disk cleanup manager's list.

EVCF_HASSETTINGS

Set this flag to indicate that the handler can display a UI. An example of a simple UI is a list box that displays the deletable files and allows the user to select which ones to delete. The disk cleanup manager will then display a button below the cleanup handler's description. The user clicks this button to request the UI. Use the ppwszBtnText parameter to specify the button's text.

EVCF_REMOVEFROMLIST

Set this flag to remove the handler from the disk cleanup manager's list. All registry information will be deleted, and the handler cannot be run again until the key and its values are restored. This flag is used primarily for one-time cleanup operations.

Return value

Type: HRESULT

This method can return one of these values.

Return code	Description
S_OK	Success.
S_FALSE	There are no files to delete.
E_ABORT	The cleanup operation was ended prematurely.
E_FAIL	The cleanup operation failed.

Remarks

The Windows 2000 disk cleanup manager will first call IEmptyVolumeCache2::InitializeEx to initialize a disk cleanup handler. It will only call Initialize if the IEmptyVolumeCache2 interface is not implemented. The Windows 98 disk cleanup manager only supports Initialize.

InitializeEx is intended to provide better localization support than Initialize. When InitializeEx is called, the handler application must assign appropriately localized values to the ppwszDisplayName and ppwszDescription parameters. If the Settings button is enabled, you must also assign a value to the ppwszBtnText parameter. Unlike Initialize, if you set these strings to NULL to notify the disk cleanup manager to retrieve the default values from the registry, InitializeEx will fail.

Use CoTaskMemAlloc to allocate memory for the strings returned through ppwszDisplayName, ppwszDescription, and ppwszBtnText. The disk cleanup manager will free the memory when it is no longer needed.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	emptyvc.h
DLL	Shell32.dll (version 5.0 or later)