IOCTL_HAL_GET_HIVE_CLEAN_FLAG (Compact 2013)

  • Article

10/16/2014

This I/O control message is used by Filesys.exe to query the OEM to determine if the registry hives and user profiles should be deleted and recreated. Send this message with OEMIoControl.

Syntax

BOOL OEMIoControl (
    DWORD dwIoControlCode,    // use IOCTL_HAL_GET_HIVE_CLEAN_FLAG
    LPVOID lpInBuffer,        // pointer to input buffer
    DWORD nInBufferSize,      // input buffer size
    LPVOID lpOutBuffer,       // pointer to output buffer
    DWORD nOutBufferSize,     // output buffer size
    LPDWORD lpBytesReturned  // number of bytes returned
);

Parameters

  • dwIoControlCode
    [in] Control code for the operation. Use IOCTL_HAL_GET_HIVE_CLEAN_FLAG for this operation.

  • lpInBuffer
    [in] Pointer to a DWORD. The following list possible values for the 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.
  • nInBufferSize
    [in] Set to sizeof(DWORD). Can be set to the same values as lpInBuffer.
  • lpOutBuffer
    [out] Pointer to a DWORD. The output DWORD value should be set to TRUE if the hive described by the flag in lpInBuffer should be cleaned. Set the DWORD value to FALSE if the hive should not be cleaned.
  • nOutBufferSize
    [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. If this I/O control is not implemented, the default return value is FALSE.

Remarks

This I/O control is supported to provide the OEM with a way to force a clean boot.

This I/O control 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 this I/O control.

This approach prevents conflicts between registry settings in a persisted hive file from an old image, and registry settings in a new ROM image.

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

Header

pkfuncs.h

See Also

Reference

Filesys.exe IOCTLs