TXF API Reference

Introduction to TXF

The Transactional File System (TXF) API provides a way to perform file operations atomically, ensuring that either all operations within a transaction succeed or none of them do. This is crucial for maintaining data integrity in applications that involve complex file manipulations.

TXF leverages Windows Transactional Synchronization Service (WTSS) to manage file system transactions. It allows developers to group multiple file operations (like creating, deleting, renaming, writing, or reading files) into a single atomic unit.

Core Concepts

  • Transaction: A logical unit of work that can be committed or rolled back.
  • Atomic Operation: A file operation that is part of a transaction.
  • Commit: Making the changes within a transaction permanent.
  • Rollback: Undoing all changes made within a transaction.

Key Functions

CreateTransaction()

Creates a new transaction object.

HANDLE CreateTransaction(
  LPTRANSACTION_NOTIFICATION lpNotificationRoutine,
  ULONGLONG                IsolationLevel,
  ULONGLONG                IsolationFlags,
  ULONGLONG                Timeout,
  LPGUID                   pFilterUow,
  PVOID                    pvReserved1,
  PVOID                    pvReserved2
);

Parameters:

Name Type Description
lpNotificationRoutine LPTRANSACTION_NOTIFICATION Pointer to a notification routine.
IsolationLevel ULONGLONG The isolation level for the transaction.
IsolationFlags ULONGLONG Flags to control isolation behavior.
Timeout ULONGLONG The timeout value for the transaction.
pFilterUow LPGUID Pointer to a filter UOW.
pvReserved1 PVOID Reserved. Must be NULL.
pvReserved2 PVOID Reserved. Must be NULL.

CommitTransaction()

Commits a transaction, making its changes permanent.

BOOL CommitTransaction(
  HANDLE  TransactionHandle,
  DWORD   dwReason,
  DWORD   dwOptions
);

Parameters:

Name Type Description
TransactionHandle HANDLE Handle to the transaction to commit.
dwReason DWORD Reason for the commit.
dwOptions DWORD Options for committing the transaction.

RollbackTransaction()

Rolls back a transaction, undoing all its changes.

BOOL RollbackTransaction(
  HANDLE  TransactionHandle,
  DWORD   dwReason
);

Parameters:

Name Type Description
TransactionHandle HANDLE Handle to the transaction to roll back.
dwReason DWORD Reason for the rollback.

AddTransactionFile()

Associates a file with a transaction.

BOOL AddTransactionFile(
  HANDLE  TransactionHandle,
  HANDLE  FileHandle
);

Parameters:

Name Type Description
TransactionHandle HANDLE Handle to the transaction.
FileHandle HANDLE Handle to the file.

Example Usage

The following C++ code snippet demonstrates how to perform a transactional file copy:

#include <windows.h>
#include <ktmw32.h>
#include <stdio.h>

int main() {
    HANDLE hTransaction = CreateTransaction(NULL, 0, 0, 0, NULL, NULL, NULL);
    if (hTransaction == INVALID_HANDLE_VALUE) {
        printf("Failed to create transaction: %lu\n", GetLastError());
        return 1;
    }

    HANDLE hSourceFile = CreateFileA("source.txt", GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
    if (hSourceFile == INVALID_HANDLE_VALUE) {
        printf("Failed to open source file: %lu\n", GetLastError());
        CloseHandle(hTransaction);
        return 1;
    }

    HANDLE hDestFile = CreateFileA("destination.txt", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
    if (hDestFile == INVALID_HANDLE_VALUE) {
        printf("Failed to open destination file: %lu\n", GetLastError());
        CloseHandle(hSourceFile);
        CloseHandle(hTransaction);
        return 1;
    }

    if (!AddTransactionFile(hTransaction, hSourceFile)) {
        printf("Failed to add source file to transaction: %lu\n", GetLastError());
        CloseHandle(hDestFile);
        CloseHandle(hSourceFile);
        CloseHandle(hTransaction);
        return 1;
    }

    if (!AddTransactionFile(hTransaction, hDestFile)) {
        printf("Failed to add destination file to transaction: %lu\n", GetLastError());
        CloseHandle(hDestFile);
        CloseHandle(hSourceFile);
        CloseHandle(hTransaction);
        return 1;
    }

    // Perform file copy operations here...
    // For simplicity, this example just creates an empty destination file.

    if (CommitTransaction(hTransaction, 0, 0)) {
        printf("Transaction committed successfully.\n");
    } else {
        printf("Failed to commit transaction: %lu\n", GetLastError());
        RollbackTransaction(hTransaction, 0);
    }

    CloseHandle(hDestFile);
    CloseHandle(hSourceFile);
    CloseHandle(hTransaction);

    return 0;
}