IOCTL_HAL_GET_HIVE_CLEAN_FLAG

Article
06/30/2006

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 table shows the 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.

nInBufSize
[in] Set to sizeof(DWORD). Can be set to the same values as lpInBuf.
lpOutBuf
[in] Set to NULL.
nOutBufSize
[in] Set to 0.
lpBytesReturned
[in] Set to NULL.

Return Values

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

Remarks

This IOCTL has no effect on the object-store–based registry. If the OEM sets the flag to TRUE, it will have 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 would be once for the system hive and once for the user hive.

This IOCTL is supported to provide the OEM with a way to force a clean boot. 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 will be cleaned up regardless of the return value from IOCTL_HAL_GET_HIVE_CLEAN_FLAG. This mechanism 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: Pwinreg.h.

Share via