IOCTL_HAL_GET_HIVE_CLEAN_FLAG (Windows CE 5.0)

Article
09/14/2012

This IOCTL is used by Filesys.exe to query the OEM to determine if the registry hives and user profiles should be deleted and recreated.

Parameters

dwIoControlCode
[in] Set to IOCTL_HAL_GET_HIVE_CLEAN_FLAG.

lpInBuf
[in] Pointer to a DWORD.

The following are possible values for DWORD.

Value	Description
HIVECLEANFLAG_SYSTEM	Inquiring about the system hive.
HIVECLEANFLAG_USERS	Inquiring about data in all user profile directories. If you specify a clean up, all user profile directories and their contents will be removed. You can identify the user profile directory because it contains a file called User.hv.

HIVECLEANFLAG_SYSTEM

Inquiring about the system hive.

HIVECLEANFLAG_USERS

Inquiring about data in all user profile directories.

If you specify a clean up, all user profile directories and their contents will be removed.

You can identify the user profile directory because it contains a file called User.hv.

nInBufSize
[in] Set to sizeof(DWORD).

Can be set to the same values as lpInBuf.
lpOutBuf
[out] Pointer to a DWORD. The output DWORD value should be set to TRUE if the hive described by the flag in lpInBuf should be cleaned. Set the DWORD value to FALSE if the hive should not be cleaned.
nOutBufSize
[in] Set to sizeof(DWORD).
lpBytesReturned
[in] Set to NULL.

Return Values

You can set the output value to TRUE if the system or user hive should be cleaned up or FALSE if it should not be cleaned up. The default is FALSE, if this IOCTL is not implemented.

Remarks

This IOCTL is supported to provide the OEM with a way to force a clean boot.

This IOCTL has no effect on the registry based on the object store. If the OEM sets the flag to TRUE, it has the same effect as starting with a new user or system registry. The OAL is called one time for each registry hive file that is loaded. On a typical boot, this is once for the system hive and once for the user hive.

Setting the flag to FALSE does not prevent other cleanup mechanisms from operating. For example, if the device is flashed with a new ROM image that contains different registry settings, the registry hive files are cleaned up regardless of the return value from IOCTL_HAL_GET_HIVE_CLEAN_FLAG.

This approach prevents conflicts between registry settings in a persisted hive file from an old image, and registry settings in a new ROM image. For more information, see Registry Hive ROM Dependency.

Code Example

case IOCTL_HAL_GET_HIVE_CLEAN_FLAG:
   if (!lpInBuf || (nInBufSize != sizeof(DWORD))
     || !lpOutBuf || (nOutBufSize != sizeof(BOOL))) {
   SetLastError(ERROR_INVALID_PARAMETER);
     return FALSE;
   } else {
     DWORD *pdwFlags = (DWORD*)lpInBuf;
     BOOL  *pfClean  = (BOOL*)lpOutBuf;
   if (*pdwFlags == HIVECLEANFLAG_SYSTEM) {
     RETAILMSG(1, (TEXT("OEM: Not cleaning system hive\r\n")));
     *pfClean = FALSE;
   } else if (*pdwFlags == HIVECLEANFLAG_USERS) {
     RETAILMSG(1, (TEXT("OEM: Cleaning user profiles\r\n")));
     *pfClean = TRUE;
   }
  }
return TRUE;

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Pkfuncs.h.