4. Technical documentation

Here you can find useful information about how WMI is built. You can use this page to better know the structure & the architecture of WMI.

File structure

WMI is split up in various files, each one containing a specific part of the application.

In the include/ folder, you'll find three header files:

• core.hpp holds some function declarations, the same functions are defined inside the src/core.cpp file;

• reg.hpp contains the declaration of some functions (defined inside of src/reg.cpp) that are needed to let WMI access, read from and write to the Windows Registry (it is far more efficient than having files floating around all the time);

• rollback.hpp contains the declaration of the wmi_rollback() function (the actual body of WMI Rollback) along with some other function declarations.

While, in the src/ folder, you'll find four files:

• main.cpp holds the main() function, along with the actual body of the application;

• core.cpp: it contains some functions needed to change the console color, clear the screen, get the window size, select the disk letter. It also contains the definition of very important variables that are used by WMI all the time;

• reg.cpp contains functions that allow WMI to create registry keys, delete them, and also create, delete, and get the values stored inside of them;

• rollback.cpp holds the main function that makes up WMI Rollback and other functions that allow it to select a disk and format it.

If you've got any suggestion on how I could improve the application architecture (file structure, functions & so on and so forth), please let me know either by opening a pull request or by opening a new discussion under the "Suggestions" category.

Every single suggestion is higly appreciated - my goal is to make WMI as readable, workable and "enjoyable" (from a development point of view) as possible!

Dependencies

WMI is shipped with a buch of other sub-applications that play a crucial role in the overall application efficiency. Let's explore them one by one.

WMI Rollback

WMI Rollback is a piece of software meant to be started by WMI whenever there's an error that would prevent Windows from installing. It's purpose is to format the target disk you chose when installing Windows via WMI, clean it and make it usable again.

For "usable" I mean the following: whenever WMI asks you to select the disk you'd like to install Windows on, the disk you select will be specifically formatted for a Windows installation, meaning that it would get split up in two partitions:

• the Data partition, which contains the system itself along with all your files, folders and programs;

• the Boot partition, namely a 500MBs in size FAT partition whose only purpose is to store the boot configuration along with all the boot files that are needed by Windows to properly load.

Both partitions are formatted in a particular way that would leave your disk in a limbo state: it would be ready for a new Windows installation, but at the same time that partition scheme is not really good for an everyday use (for storing files etc.).

And to avoid leaving your disk in this weird state, WMI Rollback offers you the option to format it in a way you can quickly resume using it.

But let's take a look at what really is WMI Rollback.

Structure

The entire body of WMI Rollback is stored inside of the src/rollback.cpp file. The functions you can find in this source file are declared inside of the include/rollback.hpp header.

The main function is wmi_rollback(). It's job is to display a basic TUI and identify the reason why it's being called.

This function needs two parameters to be called. The first one is an integer, called interruptCode. It's got a fixed number of values, each one representing a different "reason" to call the function.

These values are defined inside of the include/rollback.hpp header file. We can find five major interrupt codes:

• INT_WIMFILE_NOT_FOUND, which evaluates to -10. WMI Rollback is invoked with this specific interrupt code when WMI cannot happen to find the install.wim file anywhere on the system. It directly sends the user to the disk formatting phase (without asking them to select a drive to recover), because this interrupt call is meant to be issued during the setup process, when the user has already selected a target disk.

• INT_DISM_ERROR, which is equal to -11. If during the image extraction process DISM happens to exit with an exitcode different from 0, it means that something went wrong. But since DISM has many ways to fail (many of which however relate to a failure when trying to find the WIM image or when trying to find the destination disk), we generalize the error by redirecting the user to the formatting phase without asking for a disk number, for the same reason as before.

• INT_INSTALLER_NOT_FOUND, with a value of -12. There's just a single case when this interrupt call gets issued, and it's when WMI would normally check if the installer drive is ready to begin the image extraction. This check is performed by changing the current working directory to the installer drive partition. More specifically, if an exception gets thrown mid-check, we know that the user might've selected the installer drive as the target drive for the installation, and by doing so he made WMI wipe all the data out of it by mistake. This needs the installer drive to be completely formatted. You'll need to re-flash the Windows ISO image to make it bootable again.

• INT_INVOKED_FROM_COMMAND_LINE, which equals to -13. This interrupt code is used to call WMI Rollback just when the user invokes it by command line.

  WMI Rollback can in fact be called by command line if you need a particular disk to be formatted or cleaned.

  You can do so with the /rollback or the -rb command line argument.

  After loading, WMI Rollback will ask the user to select a disk to recover, and would then proceed in order to format it.

• INT_KILLED_BEFORE_END: it represents a value of -14 and it's used every time that WMI exits before the setup is complete. More specifically, every time you exit from WMI mid-installation and try to start it again, it will detect that the HKLM\SYSTEM\Setup\WMI\KilledBeforeEnd registry value (that is normally set to True the very first time you run WMI) is still present, therefore meaning that WMI has been alredy run but couldn't get to the end of the setup phase.

The second parameter you need to call the wmi_rollback() function is the variable that would normally contain the disk number entered by the user.

This variable is passed by reference because if the case happens to need a target disk to be selected again, it will be stored in that variable.

Otherwise, WMI Rollback will just read its value (without having to change it) and format the specified drive.

Features

WMI Rollback is a key component of WMI as a whole. It allows you to safely reset your disk and bring it to a stable state in order to let you resume using it.

While it will NOT bring back your data (as stated by WMI during the disk selection step), it will still allow you to get your disk back and working in the easiest way possible.

You can call WMI Rollback from the command line with one of the following commands:

> wmi.exe /rollback

> wmi.exe -rb

Both commands allow you to load WMI Rollback and select a disk you might want to recover, format, clean or wipe the data out of.

WMI Rollback will be automatically started whenever WMI detects a problem during the setup phase (Stage 0).

Usage

Whenever WMI Rollback gets called, you're welcomed with the below screen:

Depending on whether or not the call was made by WMI or by the user, the next screen will be depending on the case.

WIMFILE not found / Installer not found error

If you get to WMI Rollback due to an INT_WIMFILE_NOT_FOUND interrupt call, you should see the below screen:

You'll get brought to a similar screen even if your error is INT_INSTALLER_NOT_FOUND.

The shown text will be different, but I can't actually repro the scenario at the time of writing this, so I can't show you.

Pressing Enter will take you to the disk formatting phase. Your disk will get cleaned and made ready for a new installation.

DISM error

If you get an INT_DISM_ERROR interrupt call, your screen should look like this:

Once you press Enter, you'll get brought to the disk formatting phase.

Invoked from command line interrupt

If you issued the wmi.exe -rb command when starting WMI, you should see the below screen:

You'll get to choose which disk to clean and format. Enter your disk number, then press Space to confirm your choice.

Your disk will be instantly formatted.

Killed before end error

If WMI got killed before having a chance of completing the installation process, you'll see the above screen.

You'll need to type the number corresponding to the disk you first chose as the target disk where to install Windows on, then you have to press Space to confirm the choice.

Disk formatting process

You'll eventually get to a similar screen (the upper part of the text may vary based on your specific interrupt code).

This means your drive is currently being formatted.

You're asked to wait a moment, depending by how big/how fast your disk is.

End screen

After your disk is formatted, WMI Rollback shows you the following screen.

You need to press Enter to reboot your computer.

WMI Post-Install Utility

WMI Post-Install Utility is a Batch script that lets the user perform some basic post-install actions.

It is a temporary solution to a problem I’m willing to fix in the next version (not a bug, it’s just not that big of a deal really), and its main purpose is to just let you get rid of WMI once the installation is complete.

It's started right after you logon to Windows for the first time.

Features

It's got a simple menu that allows you to perform the action you want in seconds.

The WPU allows you to:

• Activate Windows with Microsoft Activation Scripts, All in One version.

  MAS allows you to activate your Windows installation in a few clicks.

  With MAS you can also perform a set of other actions that may be useful to you, like:

  • Activating Windows (HWID, KMS38, Online KMS);

  • Activating Microsoft Office (Ohook);

  • Seeing your activation status;

  • Performing some troubleshooting commands (DISM RestoreHealth, SFC Scannow);

  • Changing your Windows edition;

  • Extracting OEM folder;

  • Download genuine Windows/Office images;

• Create new user accounts;

• Install Google Chrome;

• Run a files cleanup (delete WMI from your computer - only run this when you're done using the WPU);

• Open "franzageek/wmi".

Activate Windows with MAS

Choosing this option will make MAS pop up. You can then choose the activation method you prefer.

If you need some more info, please visit massgravel/MAS.

Create a new user account

This option will let you create one or more user accounts at a glance.

You just need to choose the username, the password and whether or not to make your account part of the Administrators group.

Install Google Chrome

This option will take you to a webpage from where you can download and install Google Chrome.

Run a files cleanup

This options allows you to remove old files that were previously needed by WMI during Stage 1 but that are no longer required.

These files include:

• C:\wmi.exe - the WMI copy that carried you through Stage 1;

• C:\WMIFILES\ - a folder containing some files required by WMI;

• DLL files - required for WMI to run. They're not necessary anymore.

Performing this operation will also reset/disable the sethc hack that was needed by WMI as a fallback to start if something went wrong during Stage 1 or Stage 2.

This hack consists in replacing the C:\Windows\System32\sethc.exe with a copy of the cmd.exe executable. This way, we can easily get access to an elevated command prompt by simply pressing 5 times the Shift key.

This allows the user to manually repair their Windows installation, avoiding the possibility of trashing the whole installation altogether.

To discover how you can repair errors during Stage 1 and Stage 2, check out this page.

Noteworthy additions

In this section you'll find some useful information about certain features of WMI and the way I managed to integrate them into WMI. This will be primarily used to further describe some features that have been briefly mentioned in changelogs, but that are worth describing.

Audit Mode bug

Description

The Audit Mode bug is something I literally discovered by accident. I was trying to activate Windows using MAS, but it failed and threw an error regarding some "Audit Mode detection evaluated as true" error. This was preventing Windows to be activated via MAS at all, due to this thing called Audit Mode.

Audit Mode is basically a built-in Windows feature heavily used by OEMs. It allows you to boot your freshly installed Windows into a state you can easily change everything you want and bundle it altogether in an image file. You basically obtain a single Windows copy (that has the customizations you'd like to bring over to other computers) in the form of a portable image file that you can later flash onto many other PCs, keeping all the changes you've made to the source ISO file.

Audit Mode can be accessed by everyone through the Sysprep tool, or when you're at the OOBE phase of the Windows setup by pressing CTRL+Shift+F3. OEMs usually enter Audit Mode the last way, to make sure that every user can later go through the OOBE by themselves.

Fix

This is when stuff gets interesting: if you went through a full setup via WMI and you managed to successfully install it, you'd still be running under that Audit Mode thing. This is due to the fact that during the OOBE Windows assumes (by default) that you will eventually enter Audit Mode to further customize your Windows installation. And if you don't enter it by the end of the OOBE phase, Windows just resets some registry keys (which I wasn't aware of apparently) and proceeds to log you on.

With WMI, obviously, those registry keys weren't being reset before logon, thus leaving Windows in an Audit Mode-like state. The user wouldn't acutally be able to notice, but some features were disabled and some other were being reset at each reboot.

I then managed, by carefully examining every piece of information available, to figure out which keys to set to exit Audit Mode. I solved this "bug" by checking out this and this.

BIOS and UEFI detection

Description

If you're a real OG you may remember that, back in Batchfile days, WMI was split up into two major versions: BIOS version and UEFI version. BIOS version was created to install Windows on MBR systems, while UEFI was created to support Windows 11 and, additionally, to allow users to install Windows on an EFI system.

Their differences primarily concern the way the disk was formatted and the way boot files were created. You may compare the BIOS and UEFI versions from an old WMI release to figure it out for yourself.

This was an incredibly desultory and hard as fuck to maintain choice I myself 200% regret to have taken, though.

So I thought to include both the BIOS and UEFI version in the same executable at the same time, since there was just a couple lines of code difference between one another. I started to notice a problem when I discovered there's really no registry key associated with the system firmware type I could use to detect if WMI should take the BIOS or UEFI route during the setup, unlike I first thought.

Fix

I was aware of this problem right here that seemed very unrelated at first, but I later decided to start from there and search a possible clue about the system firmware type.

I stumbled across some articles writing about using WMIC to determine the firmware type - unfortunately that wouldn't produce the desired result, plus we've got no WMIC support in the Windows setup out of the box whatsoever.

I then thought that I could use the HKLM\SYSTEM\CurrentControlSet\Control\SecureBoot\State\UEFISecureBootEnabled key to detect if the Secure Boot was enabled or not, but that would be far too vague to make an assumption of the firmware type.

Then I started noticing a pattern. I was trying to test how reliable the assertion was based on that registry key, when I noticed that every UEFI system had that key set to 0 by default during the setup phase. But I also noticed that very key was not present on MBR systems at all.

I then started to investigate further, to see how reliable this route was. The result? 100% of cases where the key was present, they were all UEFI systems. Every system where it was not present was a MBR system. Always.

You may think I cheated a little bit, but I found NO MENTION WHATSOEVER that explicitely pointed out the relation between the firmware type and that specific key.

I hope I'm not reinventing the wheel, and that you guys can find this somewhat helpful.

Note

I've just found this method: it seems to be working but 1) it requires an extra command to be performed and 2) it would require the reg_get_value() function to be tweaked a bit. I think imma stick with the method I've used in 0.5.0.