The latter aren’t exactly difficult to use, but they are ugly and can be a bit nuanced. I will explain two of them in detail: CreateFileTransacted and RegCreateKeyTransacted. There is a great number of operations for which Microsoft has implemented transaction support, and they basically just took the every function they wanted to add support to, glued Transacted to the function name, and updated the parameter list to create a new function.
For the sake of completeness, I need to point out that it is possible to implement custom transaction managers and resource managers. If you have some sort of object management implemented in your system design, then it is possible to make it transaction aware so that it can work together with the rest of the Win32 transaction eco system. That too is well beyond the scope of this article. You can read more about that here: https://docs.microsoft.com/en-us ... tion-manager-portal
Sadly there is one regrettable thing that I must mention. Because there hasn’t been a significant adoption of the technology, Microsoft is putting notices in the documentation, encouraging users to find other solutions for NTFS transactions, and is warning that NTFS transaction may be removed in the future.
I do hope it doesn’t come to that because imo NTFS transactions are a phenomenal technology that should have been pushed harder. Registry and other transactions do not come with that warning at this time. That alone is worth putting in the time for, because the ability to handle complex registry updates in a transactional manner is great.
Creating the transaction
This is perhaps the simplest part of the process. You can simply create a transaction handle and that’s it. Microsoft has documented it as follows:
Copy Code
HANDLE CreateTransaction(
[in, optional] LPSECURITY_ATTRIBUTES lpTransactionAttributes,
[in, optional] LPGUID UOW,
[in, optional] DWORD CreateOptions,
[in, optional] DWORD IsolationLevel,
[in, optional] DWORD IsolationFlags,
[in, optional] DWORD Timeout,
[in, optional] LPWSTR Description);
UOW, IsolationLevel and IsolationFlags are reserved parameters so we just ignore them. lpTransactionAttributes is a way to assign a specific security descriptor to the transaction, which is something you don’t need if you’re a 3d party developer like us who create and use the transaction in a single process where the ACL comes from either the Primary user or the Impersonation user. The only parameter the may be of use is the Description parameter.
Because we don’t need these parameters in most cases, I have create a wrapper for it. It is possible to reuse the same function name and create an overloaded function but I prefer to do it like this, to make it obvious this is not an official function, and to make it clear to another developer that this is indeed a simplified function with a more limited scope.
//
// This function create a transaction with default settings, which is what
// is appropriate in most cases.
//
HANDLE CreateTransactionSimple(LPWSTR Description){
return CreateTransaction(
NULL, //Using default security.
NULL, //Reserved
0, //Create options, only relevant for inheriting handles
0, //Reserved
0, //Reserved
0, //Timeout
Description); //User readable description
}
CommitTransaction and RollbackTransaction do not require additional explanation because they just take the transaction handle as input and either commit or roll back the transaction respectively.
CreateFileTransacted
The CreateFileTransacted function name expands to either an ASCII or Unicode version. I’m showing the Unicode version. Most of these parameters are the same as the non-transactional version. I’m not going to describe them here. Of interest are only the three last parameters.
HANDLE CreateFileTransactedW(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter);
lpExtendedParameter is reserved so we just pass in NULL. hTransaction is the transa1ction we are using. If the file handle is created, it is linked to the transaction. Subsequent file operations can all be done using the normal APIs which don’t make a difference between transacted files or other types of file.
pusMiniversion is a not used except in very special cases. What that parameter does is if you are opening that file from multiple places, who gets to see which version of that file while transactions are ongoing. By default, the transaction that is modifying the file sees the dirty view of the file, and other clients see the view of the file as it was when it was last committed.
I created a simplified wrapper for this function too
//
// This function acts as a simplified wrapper for creating a transacted file handle to hide an
// obnoxiously long argument list that has several reserved parameters, and a couple that are
// fine with default values for our use.
//
HANDLE CreateFileTransactedSimple(
const LPCTSTR& filepath, //the file we want to create or open
DWORD desiredAccess, //the type of requested access
DWORD createDisposition, //optional specifier to determine if we want to open, or create, or always create, ...
const HANDLE& transaction) //the transaction under which this filehandle is covered.
{
return CreateFileTransacted(
filepath,
desiredAccess,
FILE_SHARE_READ, //We allow others to open the file for read access.
//For newly created files this is pointless because noone
//will see the file until we commit. But for previously
//created files, other clients see the last committed file
//while we are still updating it.
NULL, //File security will be default
createDisposition,
FILE_ATTRIBUTE_NORMAL, //the file is a regular file
NULL, //no template file is used
transaction,
NULL, //No need for a special miniversion of the file
NULL); //reserved
}
Aside from the parameters that are reserved or unused, the wrapper also specifies that the file is a regular file without special attributes (compressed, encrypted, ….). It also specifies that when we are using it, others can open the file for reading. For newly created files this is pointless because they won’t even see the file. But if we open an existing file, others can still see the previous view until we commit.
RegCreateKeyTransacted
This function creates a registry key handle which may be used for registry operations under a transaction. It is documented as follows:
LSTATUS RegCreateKeyTransactedW(
[in] HKEY hKey,
[in] LPCWSTR lpSubKey,
DWORD Reserved,
[in, optional] LPWSTR lpClass,
[in] DWORD dwOptions,
[in] REGSAM samDesired,
[in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[out] PHKEY phkResult,
[out, optional] LPDWORD lpdwDisposition,
[in] HANDLE hTransaction,
PVOID pExtendedParemeter
);
As with the previous function, I’m not going to cover the parameters that are also in the regular function call. Only the last two parameters are of interest, and the are conceptually the same as with the previous function. As soon as the registry key handle is created, the handle is linked to the transaction and you can use the normal APIs for using it.
For this function I also wrote a wrapper:
//
// Simplified wrapper for creating a registry key under a transaction to hide an
// obnoxiously long argument list that has several reserved parameters, and a couple that are
// fine with default values for our use.
//
LSTATUS RegCreateKeyTransactedSimple(
HKEY parentKey, //location where we want to open a new key
const LPCTSTR& regkey, //keyname
REGSAM samDesired, //requested rights
HKEY& regkeyhandle, //resulting registry key of the child.
const HANDLE& transaction) //transaction under which the key is opened.
{
return RegCreateKeyTransacted(
parentKey,
regkey,
0, //reserved
NULL, //user class. can be ignored
REG_OPTION_NON_VOLATILE,//the change is to be permanent
samDesired,
NULL, //security attributes. NULL -> default security inherited
®keyhandle,
NULL, //disposition feedback ->> was it created or opened? don't care.
transaction,
NULL); //reserved
}
Creating the application for our scenario
With all that out of the way, we can put everything together.
The overall structure
The structure of the client is very simple and easy to understand. After we create the transaction, we do all the relevant configurations. At the end, we either commit or roll back. It couldn’t be simpler and it’s definitely much less lines of code and much more reliable than a bunch of manually created data backup and restore code.
//Create the transaction covering the actions in this example
HANDLE transaction = CreateTransactionSimple();
if (transaction == INVALID_HANDLE_VALUE)
{
cout << "Failed to create Win32 Transaction\n";
return GetLastError();
}
// … Do stuff here
//Commit or rollback the transaction depending on whether the changes were
//successful and not cancelled by the user
if (error == NO_ERROR){
cout << "Committing transaction\n";
CommitTransaction(transaction);
}
else{
cout << "Rolling back the transaction\n";
RollbackTransaction(transaction);
}
CloseHandle(transaction);
}
Getting the user input
The logic of our program is that we get a new filename from the user which is acting as our pretend settings file.
Note that we don’t do any input validation on purpose here. The user can provide a filename with illegal characters. This will trigger an error and can be used to demonstrate the effectiveness of the transactions in dealing with errors.
Since the rest of the application is TCHAR aware, but the standard library doesn’t work with this concept, I implement these two options explicitly.
#ifdef _UNICODE
cout << "Enter the name of the file to be created:\n";
wstring filename;
getline(wcin, filename);
cout << "Enter the root folder or press enter for c:\\temp\\:\n";
wstring rootfolder;
getline(wcin, rootfolder);
if (rootfolder.empty())
rootfolder = wstring(TEXT("C:\\TEMP\\"));
wstring filepath = rootfolder + filename;
#else
cout << "Enter the name of the file to be created:\n";
string filename;
getline(cin, filename);
cout << "Enter the root folder or press enter for c:\\temp\\:\n";
string rootfolder;
getline(cin, rootfolder);
if (rootfolder.empty())
rootfolder = string(TEXT("C:\\TEMP\\"));
string filepath = rootfolder + filename;
#endif
Writing the registry
Here we update the registry after opening a registry key using the transaction we create earlier. You’ll note that the functions for updating the registry are the same ones you are used to. Although here I wrapped the SetRegValueEx function to hide the ugly typecasting that is required to write a string to the registry.
//Location in the registry where the path to the newly create file is to be stored
HKEY registryRoot = HKEY_CURRENT_USER;
LPCTSTR regkey = TEXT("Win32Transaction");
LPCTSTR valueName = TEXT("ConfigFile");
DWORD error = NO_ERROR;
//Open or create a registry key which is connected to the transaction
HKEY regkeyhandle = NULL;
if (ERROR_SUCCESS != RegCreateKeyTransactedSimple(
registryRoot, regkey, KEY_READ | KEY_WRITE, regkeyhandle, transaction))
error = GetLastError();
//write the path of the file to the registry. At this point no error checks have been
//performed so there is still the possibility that the 2nd half of this example will
//trigger an error.
if (error == NO_ERROR) {
if (ERROR_SUCCESS != SetRegValueExTString(regkeyhandle, valueName, filepath.c_str()))
error = GetLastError();
else
if (ERROR_SUCCESS != RegCloseKey(regkeyhandle))
error = GetLastError();
}
Writing the file
As with the registry access, after we create the file handle we can use the normal file IO functions for performing file IO.
Copy Code
//Create a file of which the path is based on the user input.
//No input validation was done so this part can trigger an error
if (error == NO_ERROR) {
HANDLE fileHandle = CreateFileTransactedSimple(
filepath.c_str(), GENERIC_READ | GENERIC_WRITE, CREATE_ALWAYS, transaction);
if (fileHandle == INVALID_HANDLE_VALUE)
error = GetLastError();
else
{
//so far so good, put something in the file and close it.
if (WriteFileTString(fileHandle, TEXT("Hello transacted world!")))
{
if (!CloseHandle(fileHandle))
error = GetLastError();
}
else
error = GetLastError();
}
}
Optionally choosing to roll back
For our purposes, we give the user the choice between committing or rolling back the changes. We do this to give them the time to manually check the registry or the folder on disk and verify that the changes are not yet active.
In the real world, you would probably not do this, although you could make an overview of the changes that were made, ask the user to review them before activating everything.
if (error == NO_ERROR)
{
char choice;
do {
cout << "Changes have been made.\n";
cout << "Enter C to commit or R to rollback.\n";
cin >> choice;
if(__isascii(choice) && islower(choice))
choice = _toupper(choice);
} while (choice != 'C' && choice != 'R');
if(choice == 'R')
error = ERROR_CANCELLED;
}
else {
cout << "An error was detected during the changes.\n";
}
Running the application
The source code for this application is included with the article, as is a built version which you can run on your system. I built it against the static runtime libraries so you can run it without needing a specific version of the runtime library installed.
The registry setting is stored under HKEY_CURRENT_USER which should never be a security problem. The file is stored in C:\temp unless you provide an alternative.
Conclusion
As you can see, Win32 Transactions are an incredibly powerful feature that deserves a lot more attention than it has received so far. I encourage everyone to look at them in more detail, and use them where appropriate. Not only can transactions save you a ton of manual coding, but they will also improve the reliability of your program.