[UDF] CompoundFile — Structured Storage virtual file system (pure AutoIt)

[Numeric1]

CompoundFile is a hierarchical, binary-safe virtual file system stored in a single file,
built on Windows Structured Storage (IStorage / IStream). Pure AutoIt: no DLL,
no third-party code, no COM objects left behind.

A script can ship any number of named streams (files) inside a tree of storages (folders) —
all inside one compound file (.cfb), a native Windows format readable by 7-Zip,
PowerShell or any OLE-aware tool.

Features

• Create / open / close compound files; an existing file is never overwritten
• Storages and streams with automatic creation of intermediate storages
• Text (UTF-8) and binary data, 64 KiB block I/O, up to 2 GiB per stream
• Explicit failure values plus @error ($CF_ERR_*) and the raw HRESULT in @extended; readable message via _CF_GetLastErrorMessage()
• Views: open a storage and work with paths relative to it, safely locked
• Transacted mode: commit / revert — changes published to disk atomically
• Enumeration (sorted), existence probe, stat, rename, recursive delete
• OLE name rules enforced (31 characters per component, case-insensitive, forbidden characters rejected)
• No MsgBox, no ConsoleWrite inside the UDF — safe to use in services
  

What is it for?
Shipping multi-file projects in a single file, and named resources that never touch the disk:

• Images and fonts read straight from memory — the GUI example displays 4 images stored in the .cfb and registers a TrueType font from memory (AddFontMemResourceEx) without ever extracting a file
• Binary-capable configuration (UTF-8 text or raw bytes)
• Plugin packages, asset bundles, structured data with rollback (transacted mode)
  

CompoundFile does not compress, so a ZIP stays smaller for redundant data — pick the container
that matches the need. Transactions, seekable named streams and zero dependencies are the trade-off.

Quick example

#include "CompoundFile.au3"

Local $hCF = _CF_Create(@ScriptDir & "\app.cfb")       ; fails if the file exists

_CF_WriteStream($hCF, "Config\settings.ini", "theme=dark")          ; UTF-8 text
_CF_WriteStream($hCF, "Assets\logo.bin", Binary("0x89504E47"), $CF_BINARY) ; binary

Local $sIni  = _CF_ReadStream($hCF, "Config\settings.ini")
Local $aAll  = _CF_Enum($hCF)                  ; 2D array, sorted, [0][0] = count
Local $iType = _CF_Exists($hCF, "Assets\logo.bin")    ; $CF_TYPE_STREAM

_CF_Rename($hCF, "Assets\logo.bin", "logo.png")
_CF_Delete($hCF, "Assets")                     ; recursive

_CF_Close($hCF)                                ; commits if transacted

Transacted mode

Local $hT = _CF_Create(@ScriptDir & "\data.cfb", $CF_TRANSACTED)
_CF_WriteStream($hT, "state.txt", "version 1")
_CF_Commit($hT)                                ; publish
_CF_WriteStream($hT, "state.txt", "version 2")
_CF_Revert($hT)                                ; discard -> back to "version 1"
_CF_Close($hT)                                 ; commits automatically

Function reference

_CF_Create($sFile, $iFlags)                  ; new compound file, fails if it exists
_CF_Open($sFile, $iFlags)                    ; exclusive open
_CF_Close($hCF)                              ; closes views first, commits if transacted
_CF_CreateStorage($hCF, $sPath)              ; folder, intermediates created
_CF_OpenStorage($hCF, $sPath)                ; view handle, paths relative to it
_CF_WriteStream($hCF, $sPath, $vData, $iMode, $bOverwrite)
_CF_ReadStream($hCF, $sPath, $iMode)         ; string or binary
_CF_Exists($hCF, $sPath)                     ; 0 / $CF_TYPE_STORAGE / $CF_TYPE_STREAM
_CF_Stat($hCF, $sPath)                       ; [type, size]
_CF_Enum($hCF, $sPath)                       ; 2D array, sorted, [0][0] = count
_CF_Delete($hCF, $sPath)                     ; recursive
_CF_Rename($hCF, $sPath, $sNewName)
_CF_Commit($hCF) / _CF_Revert($hCF)          ; transacted handles
_CF_GetLastErrorMessage()

Data modes for

_CF_WriteStream / _CF_ReadStream: $CF_AUTO (default), $CF_TEXT, $CF_BINARY

 

.

Error codes (@error, raw HRESULT always in @extended)

$CF_ERR_HANDLE  (1)  invalid or closed handle    $CF_ERR_STREAM   (8)  stream read/write failure
$CF_ERR_PATH    (2)  invalid path or name        $CF_ERR_ENCODING (9)  not valid UTF-8 in text mode
$CF_ERR_NOT_FOUND (3) element does not exist     $CF_ERR_NOT_TRANSACTED (10)
$CF_ERR_EXISTS  (4)  element/file already exists $CF_ERR_MEMORY   (11) buffer allocation failure
$CF_ERR_ACCESS  (5)  element already open        $CF_ERR_FORMAT   (12) not a compound file
$CF_ERR_FLAGS   (6)  invalid flag/parameter      $CF_ERR_HRESULT  (13) unmapped, see @extended
$CF_ERR_STORAGE (7)  internal storage failure

 

GUI demo

 

CompoundFile_Example_GUI.au3 builds a package in memory (4 GDI+-generated slides, a real
TrueType font, an ini) and plays it in a small configuration GUI. Nothing is ever extracted:
images are rebuilt from raw pixels, the font is registered from memory, the config is rewritten
inside the package.  Self-closing demo.

Feedback and suggestions are welcome.
 

CompoundFile_v1.0.0.zip

[water]

Added your UDF to the Wiki